Guides

Agent SDK

An agent runtime talks to the Messages API, so pointing it at the gateway is a matter of two environment variables — the code stays as it is.

Agent runtimes send ordinary Messages API requests under the hood and read the reply as a stream. The gateway serves that shape, so nothing in the agent code has to change: the base URL points here and the key travels as the auth token.

What the gateway does with an agent session

Messages, streaming, prompt caching and tool calls are all served: the request goes upstream as the runtime built it, and tool_use blocks come back in the stream as they are, so a runtime configured to execute tools gets them and carries on with the loop. The examples below declare no tools only to stay short. The model is named by its catalogue identifier, in the form vendor/model.

Configuration

Set these before starting the runtime. The base URL is the gateway root, without a version segment — the client appends the path itself.

shell

export ANTHROPIC_BASE_URL=https://api.gtokens.io
export ANTHROPIC_AUTH_TOKEN=sk-sl-your-key

# The API-key variable must be empty, not merely unset: when both are present
# the runtime prefers the key and sends a header the gateway does not read.
export ANTHROPIC_API_KEY=

The third line is not decoration. Most clients pick the API key over the auth token when both are set, and the gateway does not read the x-api-key header at all — leaving an old value in place is the single most common reason the first call comes back 401.

TypeScript example

Install the SDK:

shell

npm install @anthropic-ai/claude-agent-sdk

Run a single query against the gateway:

agent.ts

// ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN must be set; see above.
import { query } from '@anthropic-ai/claude-agent-sdk'

for await (const message of query({
  prompt: 'Summarise what this repository does, in five lines.',
  options: { model: 'anthropic/claude-sonnet-5' },
})) {
  if (message.type === 'assistant') console.log(message.message.content)
}

Python example

Install the SDK:

shell

pip install claude-agent-sdk

The same query, in Python:

agent.py

# ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN must be set; see above.
import anyio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="Summarise what this repository does, in five lines.",
        options=ClaudeAgentOptions(model="anthropic/claude-sonnet-5"),
    ):
        print(message)

anyio.run(main)

Cache reads are most of an agent bill

An agent session resends its context on every turn, so the cache-read counter usually dwarfs the other three. Its rate is the lowest of the four and is published per model in the catalogue, next to the other three. See the rates

The Messages API, field by field