Claude Agent SDK

Buscar uma opção base_url no SDK não retorna nada, e isso não é uma omissão na documentação — a opção não existe. O SDK executa a CLI do Claude Code como um subprocesso, e é a CLI que lê ANTHROPIC_BASE_URL e ANTHROPIC_AUTH_TOKEN. Defina essas duas variáveis e todas as chamadas feitas pelo agente serão direcionadas, sem alterar o código do agente.

# The SDK has no base_url option. The CLI it spawns reads these, and the
# SDK passes the parent environment straight through — so exporting them
# before your program starts is enough.
export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...

# Pin models Kunavo serves: the CLI's default and its opus/sonnet aliases
# follow Anthropic's newest models, and the sonnet alias asks for Sonnet 5.5,
# which Kunavo does not serve — unpinned, those requests 404.
export ANTHROPIC_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5

python my_agent.py

Por que o ambiente chega à CLI

Vale dedicar um parágrafo a isso, pois essa é a diferença entre um truque que pode deixar de funcionar e uma propriedade documentada na qual você pode confiar. O transporte de subprocessos do SDK Python constrói o ambiente do processo filho a partir do os.environ do processo pai, com a remoção de uma única chave — CLAUDECODE, para que o processo filho não pense que está sendo executado dentro de uma sessão do Claude Code —, e depois mescla CLAUDE_CODE_ENTRYPOINT, em seguida ClaudeAgentOptions.env e, por fim, a versão do SDK.

Disso decorrem duas coisas, e a segunda é onde as pessoas costumam se confundir. Tudo o que estiver no seu shell chega à CLI, então exportar as duas variáveis funciona. Além disso, options.env é mesclado por cima do ambiente herdado, portanto a forma explícita prevalece sobre uma variável exportada desatualizada, em vez de ser sobrepujada por ela. O código está em subprocess_cli.py.

A forma explícita e quando insistir nela

Variáveis exportadas funcionam bem na sua própria máquina, mas são frágeis em qualquer outro ambiente: o endpoint do agente passa a depender da forma como o processo foi iniciado, o que deixa de funcionar na primeira vez que ele é executado por um agendador, em um contêiner ou em uma tarefa de CI que não carrega seu perfil. Passar env no objeto de opções torna o roteamento parte do programa.

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

# The explicit form. options.env is merged ON TOP of the inherited
# environment, so this wins over whatever the shell happens to hold —
# which is what you want in anything that is not your own laptop.
options = ClaudeAgentOptions(
    env={
        "ANTHROPIC_BASE_URL": "https://api.kunavo.com",
        "ANTHROPIC_AUTH_TOKEN": "sk-kn-...",
        "ANTHROPIC_MODEL": "claude-sonnet-5",
        "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5-5",
        "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5",
        "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5",
    },
)

async with ClaudeSDKClient(options=options) as client:
    await client.query("Summarise the open TODOs in this repo")
    async for message in client.receive_response():
        print(message)

Passo a passo

1. Crie uma chave em /app/keys e copie-a — ela é exibida uma única vez.
2. Decida onde o roteamento será definido: variáveis exportadas para o trabalho local, ClaudeAgentOptions(env=…) para tudo o que é executado sem supervisão.
3. Defina ANTHROPIC_BASE_URL como https://api.kunavo.com e ANTHROPIC_AUTH_TOKEN como sua chave sk-kn-….
4. Defina ANTHROPIC_MODEL, ANTHROPIC_DEFAULT_OPUS_MODEL e ANTHROPIC_DEFAULT_SONNET_MODEL como IDs oferecidos: o padrão integrado da CLI e seus aliases opus e sonnet seguem os modelos mais recentes da Anthropic, e um modelo que a Kunavo não oferece — Sonnet 5.5, solicitado pelo alias sonnet — retorna 404.
5. Defina ANTHROPIC_DEFAULT_HAIKU_MODEL como claude-haiku-4-5 também: sem essa configuração, o alias haiku da CLI solicita um ID de modelo que a Kunavo não oferece (Haiku 5.5 a partir da v2.1.293), então os subagentes definidos com model: haiku retornam 404. Essa mesma linha também direciona as subtarefas em segundo plano iniciadas pela CLI para o nível mais barato.
6. Execute seu programa. Nada muda no código do agente.

Qual nível usar em cada subtarefa

Um agente distribui o trabalho — uma coisa que você pede se transforma em várias chamadas de ida e volta cobradas —, por isso o mapeamento de níveis importa mais aqui do que em um aplicativo de chat. As tarifas são em USD por 1M de tokens, entrada / saída, consultadas em tempo real no catálogo.

Verifique antes de depurar o SDK

Uma solicitação basta para determinar se a falha está na chave, no endpoint ou no SDK. Se ela retornar 200, a mesma credencial funciona para a CLI iniciada pelo SDK, e qualquer problema restante está na forma como as variáveis foram definidas, não no conteúdo delas.

# Settles whether a failure is the key, the endpoint, or the SDK.
# 200 here means the same credential works for the CLI the SDK spawns.
curl -sS https://api.kunavo.com/v1/messages \
  -H "Authorization: Bearer sk-kn-..." \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-haiku-4-5","max_tokens":16,
       "messages":[{"role":"user","content":"ping"}]}'

Referência

O SDK é de código aberto em anthropics/claude-agent-sdk-python. O comportamento do ambiente descrito aqui vem do transporte de subprocessos do próprio SDK, consultado em 2026-09-04. O SDK TypeScript tem a mesma arquitetura — ele controla a CLI em vez de chamar a API —, então a CLI novamente lê as variáveis de roteamento. O README do SDK TypeScript não documenta nem a opção nem esse comportamento; confirme o nome da opção nos tipos antes de depender da forma explícita. O lado da Kunavo usa a API Messages, e os outros clientes que usam o mesmo roteamento estão no hub de integrações.