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

# Agent Runtimes — Claude, Codex & Grok Build

> How the Agent API runs your task on one of three fully-managed agent runtimes — the Claude Agent SDK, the OpenAI Codex SDK, or the Grok Build CLI — selected from the model id, and how all three behave identically from the caller's side.

Every Claude-mode task (`type: "claude"`, the default) executes on one of **three agent runtimes**. All are fully managed by the Agent API: they run inside the same sandbox, expose the **same task lifecycle and event stream**, and are interchangeable from your perspective. You normally pick a **model**, and the runtime follows.

## The three runtimes

| Runtime                      | SDK                              | Wire protocol                                    | Used for                                                                 |
| ---------------------------- | -------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------ |
| **Claude Agent** *(default)* | `@anthropic-ai/claude-agent-sdk` | Anthropic Messages (`/v1/messages`)              | Anthropic/Claude ids and every other provider (NVIDIA, MiniMax, Z.ai, …) |
| **Codex Agent**              | `@openai/codex-sdk`              | OpenAI Responses (`/v1/responses`)               | OpenAI / Codex ids                                                       |
| **Grok Build**               | `grok-build-cli`                 | OpenAI Chat Completions (`/v1/chat/completions`) | xAI / Grok Build ids                                                     |

Both runtimes drive the same managed sandbox, the same GitHub clone/branch/commit flow, and emit the [same event contract](#event-stream-contract). Switching runtime requires **no client changes** — only a different `model` (or an explicit `agent` override).

## Selection rule

When you omit `agent`, the runtime is inferred from the `model` id. A model runs on the **Codex** runtime when its id:

* contains `codex`, **or**
* contains `openai/`, **or**
* contains `/gpt-` or starts with `gpt-`, **or**
* starts with `o1`, `o3`, or `o4`

A model runs on the **Grok Build** runtime when its id contains `grok-build`.

Every other id runs on the **Claude** runtime.

| Example model id                                                           | Runtime    |
| -------------------------------------------------------------------------- | ---------- |
| `blackboxai/openai/gpt-5.3-codex`                                          | Codex      |
| `blackboxai/openai/gpt-5.5` (and `gpt-5.4`, `gpt-5.4-pro`, `gpt-5.4-nano`) | Codex      |
| `blackboxai/openai/o3-mini`                                                | Codex      |
| `blackboxai/x-ai/grok-build-0.1`                                           | Grok Build |
| `blackboxai/anthropic/claude-opus-4.7` / `claude-sonnet-4.5`               | Claude     |
| `blackboxai/nvidia/nemotron-3-nano-30b-a3b`                                | Claude     |
| `blackboxai/minimax/minimax-m2.7`                                          | Claude     |
| everything else                                                            | Claude     |

## Explicit override — the `agent` field

Pass `agent` on the request body to force a runtime regardless of the model id:

<ParamField body="agent" type="string">
  `"claude"`, `"codex"`, or `"grok"`. When set, overrides the runtime inferred from `model`. Omit to auto-select (default: **claude**). An invalid value returns `400` listing the supported agents.
</ParamField>

* `agent: "codex"` — run a non-OpenAI model on the Codex (Responses) runtime.
* `agent: "claude"` — run an OpenAI-shaped id on the Claude (Messages) runtime.
* `agent: "grok"` — run a model on the Grok Build (Chat Completions) runtime.

The same `agent` field is accepted by [`POST /api/v1/tasks`](/api-reference/v1/create-task) and [`POST /api/v1/benchmarks/runs`](/api-reference/v1/benchmarks).

<Note>
  **Continuation** — [`POST /api/v1/tasks/:id/continue`](/api-reference/v1/continue-task) follows an inheritance rule: omit both `model` and `agent` to inherit the original run's model **and** runtime; if you change `model` (or the runtime), you must pass `agent` explicitly. This lets a follow-up keep a codex+opus override intact, while making any runtime change explicit.
</Note>

## Event stream contract

Both runtimes emit the **same event types** over [`GET /api/v1/tasks/:id/logs/stream`](/api-reference/v1/stream-logs) and [`GET /api/v1/agent/stream`](/api-reference/v1/agent-stream). Your stream-consuming code does not need to know which runtime produced the events.

| Event `type`                             | Meaning                                                                                  |
| ---------------------------------------- | ---------------------------------------------------------------------------------------- |
| `start`                                  | Run started.                                                                             |
| `session-init`                           | Sandbox/session initialized; carries session metadata.                                   |
| `text-start` / `text-delta` / `text-end` | Assistant text — streamed token deltas bracketed by start/end.                           |
| `tool-call-start`                        | The agent invoked a tool (e.g. `Bash`, `Read`, `Write`, or a Codex `command_execution`). |
| `tool-input-available`                   | Full tool input/arguments are available.                                                 |
| `tool-output-available`                  | Tool finished; output/result is available.                                               |
| `delegate-to-sandbox`                    | The orchestrator delegated work to the sandbox agent.                                    |
| `result`                                 | Terminal run result (success/failure + summary).                                         |
| `error`                                  | An error occurred during the run.                                                        |
| `finish`                                 | Stream finished.                                                                         |

<Tip>
  Set `includeDeltas=false` on the log stream to drop `text-delta` events and receive only the structural events above.
</Tip>

## Codex specifics

* **Wire protocol** — the Codex runtime talks to the router's OpenAI **Responses** API (`/v1/responses`). Codex models are configured `mode: responses` end-to-end.
* **Reasoning** — pass `reasoning.effort` (`minimal` | `low` | `medium` | `high`) the same way you would on the Responses API; it is honored by the Codex runtime.
* **Tool use** — Codex executes shell/file work via `command_execution`; these surface through the same `tool-call-start` / `tool-output-available` events as Claude's tools.

## Managed sandbox & SDKs

Both runtimes run inside the same managed Vercel sandbox. The SDKs are provisioned for you — you never install anything:

| Runtime    | Package                                                  | Pinned version                  |
| ---------- | -------------------------------------------------------- | ------------------------------- |
| Claude     | `@anthropic-ai/claude-agent-sdk` (bundles `claude-code`) | `0.2.87` (claude-code `2.1.87`) |
| Codex      | `@openai/codex-sdk`                                      | `0.138.0`                       |
| Grok Build | `grok-build-cli`                                         | `0.1.0`                         |

## Examples

<CodeGroup>
  ```bash Claude runtime (default) theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  curl -X POST 'https://agent.blackbox.ai/api/v1/tasks' \
    -H 'Authorization: Bearer YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "prompt": "Add a CONTRIBUTING.md with a setup section",
      "model": "blackboxai/anthropic/claude-sonnet-4.5",
      "repoUrl": "https://github.com/org/repo.git",
      "selectedBranch": "main"
    }'
  ```

  ```bash Codex runtime (by model id) theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  curl -X POST 'https://agent.blackbox.ai/api/v1/tasks' \
    -H 'Authorization: Bearer YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "prompt": "Add a CONTRIBUTING.md with a setup section",
      "model": "blackboxai/openai/gpt-5.3-codex",
      "repoUrl": "https://github.com/org/repo.git",
      "selectedBranch": "main"
    }'
  ```

  ```bash Force Codex on a non-OpenAI model theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  curl -X POST 'https://agent.blackbox.ai/api/v1/tasks' \
    -H 'Authorization: Bearer YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "prompt": "Run the test suite and fix any failures",
      "model": "blackboxai/openai/gpt-5.5",
      "agent": "codex",
      "repoUrl": "https://github.com/org/repo.git"
    }'
  ```

  ```bash Grok Build runtime theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  curl -X POST 'https://agent.blackbox.ai/api/v1/tasks' \
    -H 'Authorization: Bearer YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "prompt": "Run the test suite and fix any failures",
      "model": "blackboxai/x-ai/grok-build-0.1",
      "agent": "grok",
      "repoUrl": "https://github.com/org/repo.git"
    }'
  ```
</CodeGroup>

The response shape (`taskId`, `runId`, `chatId`, …) and every downstream endpoint — [status](/api-reference/v1/task-status), [logs](/api-reference/v1/stream-logs), [files](/api-reference/v1/files-list), [continue](/api-reference/v1/continue-task), [cancel](/api-reference/v1/cancel-task) — are **identical across runtimes**.

<CardGroup cols={2}>
  <Card title="Create a Task" icon="play" href="/api-reference/v1/create-task">
    Start a task; pass `model` and optional `agent`.
  </Card>

  <Card title="Models" icon="layer-group" href="/api-reference/v1/models">
    Full model list with per-model runtime mapping.
  </Card>

  <Card title="Stream Task Logs" icon="signal-stream" href="/api-reference/v1/stream-logs">
    The shared SSE event stream for both runtimes.
  </Card>

  <Card title="Benchmarks" icon="flask" href="/api-reference/v1/benchmarks">
    Run benchmarks on either runtime via the same `agent` field.
  </Card>
</CardGroup>