Claude Agent SDK

Buscar una opción base_url en el SDK no da resultado, y no se trata de una omisión en la documentación: la opción no existe. El SDK ejecuta la CLI de Claude Code como subproceso, y es la CLI la que lee ANTHROPIC_BASE_URL y ANTHROPIC_AUTH_TOKEN. Define esas dos variables y se enrutarán todas las llamadas que realice el agente, sin modificar el código de este.

# 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 qué el entorno llega a la CLI

Vale la pena dedicarle un párrafo, porque esta es la diferencia entre un truco que podría dejar de funcionar y una propiedad documentada en la que puedes basarte. El transporte de subprocesos del SDK de Python construye el entorno del proceso hijo a partir de os.environ del proceso padre, eliminando una sola clave: CLAUDECODE, para que el hijo no crea que se ejecuta dentro de una sesión de Claude Code; después combina CLAUDE_CODE_ENTRYPOINT, luego ClaudeAgentOptions.env y, por último, la versión del SDK.

De ahí se desprenden dos cosas; la segunda es la que suele entenderse mal. Todo lo que esté en tu shell llega a la CLI, así que exportar las dos variables funciona. Además, options.env se combina por encima del entorno heredado, por lo que la forma explícita prevalece sobre una variable exportada obsoleta en lugar de quedar subordinada a ella. El código está en subprocess_cli.py.

La forma explícita y cuándo exigirla

Las variables exportadas funcionan bien en tu propio equipo y son frágiles en cualquier otro entorno: el endpoint del agente pasa a depender de cómo se inició el proceso, lo cual falla la primera vez que se ejecuta mediante un programador, en un contenedor o en un trabajo de CI que no carga tu perfil. Pasar env en el objeto de opciones integra el enrutamiento en el 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)

Paso a paso

1. Cree una clave en /app/keys y cópiela: se muestra una sola vez.
2. Decide dónde se define el enrutamiento: variables exportadas para el trabajo local, ClaudeAgentOptions(env=…) para todo lo que se ejecute sin supervisión.
3. Define ANTHROPIC_BASE_URL como https://api.kunavo.com y ANTHROPIC_AUTH_TOKEN como tu clave sk-kn-….
4. Configura ANTHROPIC_MODEL, ANTHROPIC_DEFAULT_OPUS_MODEL y ANTHROPIC_DEFAULT_SONNET_MODEL con identificadores disponibles: el valor predeterminado integrado de la CLI y sus alias opus y sonnet siguen los modelos más recientes de Anthropic, y un modelo que Kunavo no ofrece —Sonnet 5.5, solicitado por el alias sonnet— devuelve 404.
5. Opcionalmente, define ANTHROPIC_DEFAULT_HAIKU_MODEL para que las subtareas en segundo plano que inicia la CLI usen el nivel de menor costo.
6. Ejecuta el programa. No cambia nada en el código del agente.

Qué nivel usar para cada subtarea

Un agente distribuye el trabajo: una sola petición tuya se convierte en muchos viajes de ida y vuelta facturables, por lo que la asignación de niveles importa más aquí que en una aplicación de chat. Las tarifas son USD por 1M de tokens, entrada / salida, y se obtienen en tiempo real del catálogo.

Verifica antes de depurar el SDK

Una solicitud basta para determinar si el problema está en la clave, el endpoint o el SDK. Si devuelve 200, la misma credencial funciona para la CLI que inicia el SDK, y cualquier problema restante estará en cómo se definen las variables, no en sus valores.

# 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"}]}'

Referencia

El SDK es de código abierto en anthropics/claude-agent-sdk-python. El comportamiento del entorno que se describe aquí corresponde a su propio transporte de subprocesos; se consultó el 2026-09-04. El SDK de TypeScript tiene la misma arquitectura: controla la CLI en lugar de llamar a la API, así que la CLI vuelve a leer las variables de enrutamiento. Su README no documenta ni la opción ni el comportamiento, así que confirma el nombre de la opción en sus tipos antes de confiar allí en la forma explícita. El servicio de Kunavo es la API de Messages; encontrarás otros clientes que usan el mismo tipo de enrutamiento en el centro de integraciones.