Skip to content

Claude Agent SDK

An agent built on the Claude Agent SDK can make hundreds of model calls for one task: turns, sub-agents, compaction, background summaries. Set two environment variables and all of them go through the gateway: checked against your policies, charged to the agent's team and recorded in Request logs, one row per call.

What it is

The claude-agent-sdk package for Python and @anthropic-ai/claude-agent-sdk for TypeScript. It doesn't call the model itself: it starts Claude Code as a separate process and drives it. Claude Code speaks the Anthropic Messages format, which the gateway accepts at /v1/messages. So you configure the agent the way you configure Claude Code: with environment variables, not with a client object.

The two settings

Setting Environment variable Value
Base address ANTHROPIC_BASE_URL https://<your-gateway>, without /v1 (Claude Code adds /v1/messages)
Key ANTHROPIC_AUTH_TOKEN (sent as Authorization: Bearer) or ANTHROPIC_API_KEY (sent as x-api-key) The agent's Vidai key (starts vk_), never a provider's key

The gateway accepts either header. Set one of the two variables, not both with different keys: two different keys on one call are refused with conflicting_auth_headers.

Issue the key to the agent under Applications & agents (the agent's Keys section, Issue a key); its secret is shown once. The gateway's address is under Connect your app on the Keys page and in System › Settings › Gateway.

export ANTHROPIC_BASE_URL="https://<your-gateway>"
export ANTHROPIC_AUTH_TOKEN="vk_…"

Or pass them to the process the SDK starts, through the env option:

import os
from claude_agent_sdk import ClaudeAgentOptions

options = ClaudeAgentOptions(
    model="claude-sonnet-4.5",
    env={
        "ANTHROPIC_BASE_URL": "https://<your-gateway>",
        "ANTHROPIC_AUTH_TOKEN": os.environ["VIDAI_KEY"],
    },
)
import { query } from "@anthropic-ai/claude-agent-sdk";

const options = {
  model: "claude-sonnet-4.5",
  env: {
    ...process.env, // TypeScript's env replaces the whole environment: keep the rest
    ANTHROPIC_BASE_URL: "https://<your-gateway>",
    ANTHROPIC_AUTH_TOKEN: process.env.VIDAI_KEY!,
  },
};

In Python, env is added on top of the inherited environment; in TypeScript it replaces it, hence the spread.

A minimal call

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    options = ClaudeAgentOptions(model="claude-sonnet-4.5", max_turns=1)
    async for message in query(prompt="Say hello in Dutch.", options=options):
        print(message)

asyncio.run(main())
import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Say hello in Dutch.",
  options: { model: "claude-sonnet-4.5", maxTurns: 1 },
})) {
  console.log(message);
}

The same agent can run on a GPT or Gemini model: put a name such as gpt-4.1 in model. The gateway translates each Messages call for that provider and the answer back into the Anthropic shape, streams and tool calls included. Anthropic supports Claude Code on Claude models only, so test your agent on the model you choose; see "Good to know".

Streaming

Claude Code always streams. A stream from a GPT or Gemini model arrives in Anthropic's own event format, through to message_stop, so the SDK sees nothing different. If the provider fails after the stream has started, the connection closes; Claude Code treats it as a dropped connection and may send the turn again.

Tool calls

The SDK's built-in tools (reading and editing files, running commands, searching) and your own tools (@tool with create_sdk_mcp_server, or any MCP server) are run by Claude Code on your machine. The model only sees them as ordinary tool definitions, and tool calls work across providers.

from claude_agent_sdk import tool, create_sdk_mcp_server, ClaudeAgentOptions

@tool("get_weather", "Weather for a city", {"city": str})
async def get_weather(args):
    return {"content": [{"type": "text", "text": f"Sunny in {args['city']}"}]}

weather = create_sdk_mcp_server(name="weather", tools=[get_weather])
options = ClaudeAgentOptions(
    model="claude-sonnet-4.5",
    mcp_servers={"weather": weather},
    allowed_tools=["mcp__weather__get_weather"],
)

Two built-in tools lean on Anthropic's side:

  • Web search is a tool Anthropic's API runs. On a Gemini model the gateway maps it to Google Search (dropped if the call also offers other tools); on an OpenAI model to web search, where the model has it; otherwise it's dropped and web_search is reported in x-vidai-adapted.
  • Web fetch fetches on your machine, but first asks api.anthropic.com whether the domain is safe, outside the gateway. Turn that check off with skipWebFetchPreflight: true in Claude Code's settings if your network only lets traffic out to the gateway.

Anthropic's schema-defined tool types bash_* and text_editor_* are refused with a 400 on any model that isn't Claude. The SDK's built-in Bash and Edit tools are not those types: they run in Claude Code.

Reading what the gateway did

The SDK doesn't hand you the response headers. Look the calls up in Request logs: filter Agent (or Key), Model or Path (/v1/messages). Each call shows the model that answered, what translation or a guardrail changed, the routing rule or fallback that acted, and what it cost.

Claude Code also sends its own headers with each call, such as x-claude-code-session-id (and, with CLAUDE_CODE_GATEWAY_HINT_HEADERS=1, x-claude-code-request-class: main, subagent, compaction, auxiliary); the gateway doesn't read them.

The cost the SDK reports (total_cost_usd on the result message) is Claude Code's own estimate at Anthropic's list prices. What Vidai charged, with your organisation's prices and the model that really answered, is in Request logs and Cost.

Errors

The gateway writes its errors in the Anthropic format, so Claude Code shows them as API errors with the status and message. Its own log doesn't show the gateway's headers: take the status, then find the call in Request logs (filter Exact status or Why it failed).

Status Common gateway codes What to do
401 missing_api_key, invalid_api_key, conflicting_auth_headers Check the key, and that only one credential variable is set
403 api_key_disabled, model_not_allowed, denied_by_routing_rule, content_guardrail_blocked Check the agent's state and its models; the call's row says which policy refused it
404 model_not_found Use a name from Models (see below)
429 rate_limit_exceeded, token_limit_exceeded, concurrency_limit_exceeded Claude Code waits and retries; lower its retries if you prefer to fail fast
5xx ai_traffic_suspended, fallback_exhausted, upstream_timeout, upstream_unreachable See the call's row for the provider's own message

When the agent is suspended, or its key is switched off, its calls get api_key_disabled with a short reason in the error body (for example agent_suspended); treat the list of reasons as open-ended.

Model names

Claude Code uses more than the model you name: it sends background work (titles, summaries) to its "haiku" model, and sub-agents may use others. Every one must be a name the agent's key may call, or that call is refused with model_not_allowed. Pin them all to approved names:

export ANTHROPIC_MODEL="claude-sonnet-4.5"
export ANTHROPIC_DEFAULT_SONNET_MODEL="claude-sonnet-4.5"
export ANTHROPIC_DEFAULT_OPUS_MODEL="claude-sonnet-4.5"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="claude-haiku-4.5"   # for example; background work

Use the names your organisation approved under Models in the Control room. GET /v1/models on the gateway lists exactly the models the key may call.

What goes through the gateway

Feature Through the gateway
Every turn, sub-agent, compaction and background call, streaming, tool calls Yes, to Anthropic and Bedrock Claude models, and translated to OpenAI, Azure OpenAI, Gemini and Vertex AI models
Token counting (/v1/messages/count_tokens) Yes; for another provider's model the gateway counts the tokens itself
Web search on a model that isn't Claude Mapped where the provider has search, otherwise dropped (see above)
Prompt caching on a model that isn't Claude The cache markers are removed; the provider's own caching still applies and is reported
Claude Code's version checks, telemetry, the web-fetch domain check No: they go to Anthropic directly. Set CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 to stop all but the domain check

Check it works in a minute

export ANTHROPIC_BASE_URL="https://<your-gateway>"
export ANTHROPIC_AUTH_TOKEN="vk_…"
curl -sS "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4.5","max_tokens":5,"messages":[{"role":"user","content":"ping"}]}'

A JSON answer that starts {"id":"msg_ means the address and key are right; then run the minimal call above. The calls show under the agent in Request logs within seconds.

Good to know

  • Claude Code retries a failed call up to 10 times by default. A fallback chain may already have tried another model first; set CLAUDE_CODE_MAX_RETRIES lower (in env) if you don't want both.
  • The gateway's own 429 has no Retry-After header, so Claude Code backs off on its own schedule.
  • Anthropic supports Claude Code on Claude models only. It works on other models through translation (extended thinking becomes the provider's reasoning setting), but Anthropic's pre-release features may be dropped: on a GPT model the gateway drops context_management and reports it in x-vidai-adapted, and the call goes ahead; on Claude both it and defer_loading pass on unchanged. Test before you rely on it. If a translated call fails on a pre-release field, set CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1.