Run the Claude Agent SDK on Router One with the two Claude Code variables

Install the Python SDK and set your credentials

Use Python 3.10 or newer and install claude-agent-sdk; the wheel bundles a native Claude Code binary, so no separate Claude Code install is needed. If pip installs the source distribution instead of a platform wheel (the official docs name ARM64 Windows), install Claude Code natively and the SDK finds it on PATH. The TypeScript package is @anthropic-ai/claude-agent-sdk on Node.js 18 or newer. The shell example below is for macOS/Linux; replace both placeholders with a Router One key and the exact ID of a current Claude-family model whose detail page lists POST /v1/messages. These ROUTER_ONE_* names belong to the example, which reads them and hands the engine ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN; exporting those two directly, as the Claude Code guide does, works the same way because the Python SDK merges env on top of the inherited environment. The SDK does not load .env files, so keep the same environment active when running the Python file.

python -m pip install claude-agent-sdk
export ROUTER_ONE_API_KEY="sk-your-router-one-key"
export ROUTER_ONE_MODEL_ID="<exact-model-id-from-/models>"

Configure Claude Agent SDK to use the Router One base URL

Save this as claude_agent_sdk_router_one.py and run python claude_agent_sdk_router_one.py. query() starts the bundled Claude Code engine as a subprocess and yields its messages. The env option is merged on top of the inherited environment: ANTHROPIC_BASE_URL is the host root https://api.router.one without /v1, because the engine appends /v1/messages itself, and ANTHROPIC_AUTH_TOKEN carries your Router One key as an Authorization: Bearer header, so every model turn is an Anthropic Messages request to the gateway. ANTHROPIC_API_KEY is not required and is deliberately absent. model= passes the catalog ID unchanged to the engine's --model flag; an unset model falls back to Claude Code's default alias, which resolves to a built-in default ID that may not be a catalog entry. max_turns=3 caps tool-use round trips. permission_mode is left unset and no can_use_tool callback is given, so a tool request would be denied rather than executed; the first run is model requests only. The loop prints every TextBlock from each AssistantMessage, then the ResultMessage subtype and num_turns.

import asyncio
import os

from claude_agent_sdk import (
    AssistantMessage,
    ClaudeAgentOptions,
    ResultMessage,
    TextBlock,
    query,
)

options = ClaudeAgentOptions(
    model=os.environ["ROUTER_ONE_MODEL_ID"],
    env={
        "ANTHROPIC_BASE_URL": "https://api.router.one",
        "ANTHROPIC_AUTH_TOKEN": os.environ["ROUTER_ONE_API_KEY"],
    },
    max_turns=3,
)


async def main() -> None:
    prompt = "Reply with one short greeting."
    async for message in query(prompt=prompt, options=options):
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if isinstance(block, TextBlock):
                    print(block.text)
        elif isinstance(message, ResultMessage):
            print(f"{message.subtype}: {message.num_turns} turn(s)")


asyncio.run(main())

Options that decide what reaches the gateway

Most ClaudeAgentOptions fields shape what the engine does locally. These are the ones that change the requests Router One receives; TypeScript uses the camelCase twins on its Options object, and one of them behaves differently between the two SDKs.

Budget one query and reconcile its turns in Logs

One query() call is a sequence of Messages requests: at least one per turn, more when the engine spawns subagents, plus the background requests the Claude Code engine documents. max_turns bounds tool-use round trips, not spend, and max_budget_usd compares a list-price estimate that the official docs say can drift and must not drive financial decisions. Give the agent its own Router One key with maxSpend, then read the run in Dashboard → Logs: filter by that key and the exact model, match traces to the run's time window and to num_turns on the ResultMessage, and keep the request_id of any failed trace. total_cost_usd on the result is the SDK's estimate; the cost the gateway records per trace is what you are charged. Router One serves and records the model requests only: tool execution, hooks, permission checks, sessions, and subagents run in the SDK on your machine or container.

Which model ID should Claude Agent SDK send?

Copy the exact model ID from /models, preserving case, hyphens, and version suffixes; do not substitute a display name. Open its detail page and match the supported API endpoints, context window, and capabilities such as tool calling to the provider and features selected in Claude Agent SDK. A catalog listing does not mean the client can use every feature of that model. Give each tool a dedicated API key with a maxSpend cap.

Which API protocol is Claude Agent SDK using?

OpenAI-compatible describes an interface format; it does not make Chat Completions (/v1/chat/completions), Responses (/v1/responses), and Anthropic Messages (/v1/messages) interchangeable. Check the installed client version, provider configuration, and actual request path against the model detail page and API compatibility fact sheet. A successful plain-text chat does not establish support for hosted tools, conversation state, or file-editing features.

Verify the Claude Agent SDK call in your request trace

Send a simple text request from Claude Agent SDK, then match its trace in Dashboard → Logs by time, model, and request_id: tokens, cost, latency, and status. Next, test streaming, tool calls, and multi-turn history separately. For failures, retain the actual request path, full error message, and request_id. If there is no matching log, check client configuration and connectivity before attributing the error to the gateway or upstream.

FAQ