> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Router V3 & Agents V3

> Migration guide for AI Router V3 and Agents V3 endpoints. Rewritten in Go for lower latency, reduced memory, and full OpenAI SDK compatibility.

As part of Release 4.7, we rewrote the AI Router and Agents runtime in Golang for improved performance, lower latency, and reduced memory consumption. Both are in beta for April and moving to GA in May.

This page covers the new endpoints and how to use them.

## AI Router V3

The V3 router exposes the same chat completions endpoint you already use, now at `/v3/router/chat/completions`. It supports all existing functionality (chat completions, embeddings, image generation, transcription, translation) with the addition of extended parameters like `identity` and `thread`.

The router stays fully compatible with the OpenAI SDK.

### Chat Completions

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --location 'https://api.orq.ai/v3/router/chat/completions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $ORQ_API_KEY' \
--data-raw '{
    "model": "openai/gpt-4o-mini",
    "messages": [
        {
            "role": "system",
            "content": "You are a helpful assistant."
        },
        {
            "role": "user",
            "content": "What can you help me with today?"
        }
    ],
    "identity": {
        "id": "user-123",
        "display_name": "Jane Doe",
        "email": "jane.doe@example.com"
    },
    "thread": {
        "id": "thread-001",
        "tags": ["support", "v3"]
    },
    "stream": false
}'
```

### Key Parameters

| Parameter  | Description                                                                |
| ---------- | -------------------------------------------------------------------------- |
| `model`    | Provider and model in `provider/model` format (e.g., `openai/gpt-4o-mini`) |
| `messages` | Standard chat completion messages array                                    |
| `identity` | Associate the request with a user identity for tracking and analytics      |
| `thread`   | Group requests into a conversation thread with optional tags               |
| `stream`   | Set to `true` for streaming responses                                      |

V3 supports all the same extended parameters as the V2 router, including fallback configurations, retry logic, and all other orq-specific parameters you are already using.

## Responses V1

The `/v1/responses` endpoint follows the [OpenResponses specification](https://www.openresponses.org/). It provides a stateful, interaction-based way to work with models and agents. You can use it in two ways:

1. **With a model and tools** - invoke any model directly with tools, variables, and extended parameters.
2. **With an agent** - invoke an agent you created via the [Agents API](https://docs.orq.ai/reference/agents/create-agent) or [Agent Studio](https://docs.orq.ai/docs/agents/agent-studio#getting-started).

### Invoking a Model with Tools

Use the `model` field with a `provider/model` format to invoke a model directly. You can attach tools, variables, identity, and thread parameters.

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --location 'https://api.orq.ai/v1/responses' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $ORQ_API_KEY' \
--data-raw '{
    "model": "openai/gpt-4o",
    "input": "What is the current CET time? Answer in {{language}}",
    "tools": [
        {
            "type": "orq:current_date"
        }
    ],
    "variables": {
        "language": {
            "value": "hungarian"
        }
    },
    "identity": {
        "id": "user-123",
        "display_name": "Jane Doe",
        "email": "jane.doe@example.com"
    },
    "thread": {
        "id": "thread-001",
        "tags": ["support", "v3"]
    },
    "stream": false
}'
```

### Invoking an Agent

To invoke an agent, set the `model` field to `agent/your_agent_name`. The agent must first be created via the [Agents API](https://docs.orq.ai/reference/agents/create-agent) or the [Agent Studio](https://docs.orq.ai/docs/agents/agent-studio#getting-started).

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --location 'https://api.orq.ai/v1/responses' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $ORQ_API_KEY' \
--data-raw '{
    "model": "agent/support_agent",
    "input": "What is the current CET time? Answer in {{language}}",
    "tools": [
        {
            "type": "orq:current_date"
        }
    ],
    "variables": {
        "language": {
            "value": "hungarian"
        }
    },
    "identity": {
        "id": "user-123",
        "display_name": "Jane Doe",
        "email": "jane.doe@example.com"
    },
    "thread": {
        "id": "thread-001",
        "tags": ["support", "v3"]
    },
    "stream": false
}'
```

### Key Parameters

| Parameter   | Description                                                                                                                                                                    |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `model`     | Either `provider/model` for direct model invocation or `agent/agent_name` for agent invocation                                                                                 |
| `input`     | The user input. Supports `{{variable}}` template syntax                                                                                                                        |
| `tools`     | Array of tools the model or agent can use (e.g., `orq:current_date`)                                                                                                           |
| `variables` | Key-value pairs for template variables. Each variable has a `value` and an optional `secret` flag (set to `true` for sensitive values like API keys to mark them as encrypted) |
| `identity`  | Associate the request with a user identity                                                                                                                                     |
| `thread`    | Group requests into a conversation thread with optional tags                                                                                                                   |
| `stream`    | Set to `true` for streaming responses                                                                                                                                          |