Claude Agent SDK

Rechercher une option base_url dans le SDK ne donne aucun résultat, et ce n’est pas un oubli de la documentation : l’option n’existe pas. Le SDK exécute la CLI Claude Code en tant que sous-processus, et c’est la CLI qui lit ANTHROPIC_BASE_URL et ANTHROPIC_AUTH_TOKEN. Définissez ces deux variables et tous les appels de l’agent seront acheminés, sans modifier le code de votre agent.

# 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

Pourquoi l’environnement est transmis à la CLI

Cela mérite un paragraphe, car c’est ce qui distingue une astuce susceptible de cesser de fonctionner d’une propriété documentée sur laquelle vous pouvez vous appuyer. Le transport par sous-processus du SDK Python construit l’environnement enfant à partir de os.environ du parent, en supprimant une seule clé — CLAUDECODE — pour que l’enfant ne pense pas s’exécuter dans une session Claude Code ; il fusionne ensuite CLAUDE_CODE_ENTRYPOINT, puis ClaudeAgentOptions.env, puis la version du SDK.

Deux conséquences en découlent, et la seconde est celle que l’on comprend souvent mal. Tout ce qui se trouve dans votre shell parvient à la CLI, donc l’exportation des deux variables fonctionne. Et options.env est fusionné par-dessus l’environnement hérité : la forme explicite prend donc le dessus sur une ancienne exportation au lieu de céder devant elle. Le code se trouve dans subprocess_cli.py.

La forme explicite et les cas où il faut l’exiger

Les variables exportées conviennent sur votre propre machine et deviennent fragiles partout ailleurs : le point de terminaison de l’agent dépend alors du mode de lancement du processus, et cela échoue dès qu’il s’exécute sous un planificateur, dans un conteneur ou dans une tâche CI qui ne charge pas votre profil. Transmettre env dans l’objet options fait du routage une propriété du programme.

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)

Étape par étape

1. Créez une clé sur /app/keys et copiez-la — elle n’est affichée qu’une seule fois.
2. Choisissez où définir le routage : variables exportées pour le travail local, ClaudeAgentOptions(env=…) pour toute exécution sans surveillance.
3. Définissez ANTHROPIC_BASE_URL sur https://api.kunavo.com et ANTHROPIC_AUTH_TOKEN sur votre clé sk-kn-….
4. Définissez ANTHROPIC_MODEL, ANTHROPIC_DEFAULT_OPUS_MODEL et ANTHROPIC_DEFAULT_SONNET_MODEL sur des identifiants servis : la valeur par défaut intégrée à la CLI ainsi que ses alias opus et sonnet suivent les modèles les plus récents d’Anthropic, et un modèle non servi par Kunavo — Sonnet 5.5, demandé par l’alias sonnet — renvoie 404.
5. Définissez éventuellement ANTHROPIC_DEFAULT_HAIKU_MODEL pour que les sous-tâches exécutées en arrière-plan par la CLI utilisent le niveau le moins cher.
6. Exécutez votre programme. Rien ne change dans le code de l’agent.

Quel niveau pour quelle sous-tâche

Un agent répartit le travail : une seule demande peut entraîner de nombreux allers-retours facturés. La correspondance entre les niveaux importe donc davantage ici que dans une application de discussion. Les tarifs sont exprimés en USD par 1M de jetons, entrée / sortie, et proviennent du catalogue en temps réel.

Vérifiez avant de déboguer le SDK

Une requête suffit à déterminer si l’échec vient de la clé, du point de terminaison ou du SDK. Si elle renvoie 200, le même identifiant fonctionne pour la CLI lancée par le SDK, et tout problème qui persiste concerne l’endroit où les variables sont définies, pas leur contenu.

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

Références

Le SDK est open source sur anthropics/claude-agent-sdk-python. Le comportement de l’environnement décrit ici provient de son propre transport par sous-processus, consulté le 2026-09-04. Le SDK TypeScript a la même architecture : il pilote la CLI au lieu d’appeler l’API, et c’est donc encore la CLI qui lit les variables de routage. Son README ne documente ni l’option ni ce comportement ; vérifiez donc le nom de l’option dans ses types avant de vous fier à la forme explicite. Côté Kunavo, il s’agit de l’API Messages ; les autres clients qui utilisent le même routage sont répertoriés sur le hub des intégrations.