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_searchis reported inx-vidai-adapted. - Web fetch fetches on your machine, but first asks
api.anthropic.comwhether the domain is safe, outside the gateway. Turn that check off withskipWebFetchPreflight: truein 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_RETRIESlower (inenv) if you don't want both. - The gateway's own 429 has no
Retry-Afterheader, 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_managementand reports it inx-vidai-adapted, and the call goes ahead; on Claude both it anddefer_loadingpass on unchanged. Test before you rely on it. If a translated call fails on a pre-release field, setCLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1.