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

Both runtimes drive the same managed sandbox, the same GitHub clone/branch/commit flow, and emit the same event 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.

Explicit override — the agent field

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

• 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 and POST /api/v1/benchmarks/runs.

Event stream contract

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

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:

Examples

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"
  }'

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"
  }'

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"
  }'

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"
  }'

The response shape (taskId, runId, chatId, …) and every downstream endpoint — status, logs, files, continue, cancel — are identical across runtimes.