Claude Agent SDK

Cercare un’opzione base_url nell’SDK non restituisce nulla, e non si tratta di un’omissione nella documentazione: l’opzione non esiste. L’SDK esegue la CLI Claude Code come sottoprocesso, ed è la CLI a leggere ANTHROPIC_BASE_URL e ANTHROPIC_AUTH_TOKEN. Imposta queste due variabili e tutte le chiamate effettuate dall’agente vengono instradate senza dover modificare il codice dell’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

Perché l’ambiente viene passato alla CLI

Vale la pena dedicare un paragrafo a questo punto, perché distingue un espediente che potrebbe smettere di funzionare da una proprietà documentata su cui puoi fare affidamento. Il trasporto dei sottoprocessi dell’SDK Python crea l’ambiente del processo figlio a partire da os.environ del processo padre, rimuovendo una sola chiave: CLAUDECODE, affinché il processo figlio non creda di essere in esecuzione all’interno di una sessione di Claude Code; poi unisce CLAUDE_CODE_ENTRYPOINT, quindi ClaudeAgentOptions.env e infine la versione dell’SDK.

Ne conseguono due cose, e la seconda è quella che spesso viene fraintesa. Tutto ciò che è nella shell arriva alla CLI, quindi esportare le due variabili funziona. Inoltre, options.env viene unito in cima all’ambiente ereditato, quindi la forma esplicita prevale su un’esportazione obsoleta, anziché soccombervi. Il codice si trova in subprocess_cli.py.

La forma esplicita e quando usarla

Le variabili esportate vanno bene sul proprio computer, ma sono fragili in tutti gli altri ambienti: l’endpoint dell’agente dipende da come viene avviato il processo, e questo causa problemi la prima volta che viene eseguito da uno scheduler, in un container o in un job CI che non carica il tuo profilo. Passare env nell’oggetto delle opzioni rende l’instradamento parte del programma.

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 dopo passo

1. Crea una chiave su /app/keys e copiala: viene mostrata una sola volta.
2. Scegli dove definire l’instradamento: variabili esportate per il lavoro locale, ClaudeAgentOptions(env=…) per tutto ciò che viene eseguito senza supervisione.
3. Imposta ANTHROPIC_BASE_URL su https://api.kunavo.com e ANTHROPIC_AUTH_TOKEN sulla tua chiave sk-kn-….
4. Imposta ANTHROPIC_MODEL, ANTHROPIC_DEFAULT_OPUS_MODEL e ANTHROPIC_DEFAULT_SONNET_MODEL sugli ID serviti: il valore predefinito integrato nella CLI e i suoi alias opus e sonnet seguono i modelli più recenti di Anthropic, mentre un modello non servito da Kunavo — Sonnet 5.5, richiesto dall’alias sonnet — restituisce 404.
5. Imposta anche ANTHROPIC_DEFAULT_HAIKU_MODEL su claude-haiku-4-5: senza questa impostazione, l'alias haiku della CLI richiede un ID modello che Kunavo non offre (Haiku 5.5 dalla v2.1.293), quindi i subagenti definiti con model: haiku restituiscono 404. La stessa riga assegna al tier meno costoso le sottoattività in background avviate dalla CLI.
6. Esegui il programma. Non devi modificare il codice dell’agente.

Quale livello usare per ciascuna sottoattività

Un agente suddivide il lavoro: una singola richiesta può tradursi in molti scambi fatturati, quindi la scelta del livello è qui più importante che in un’app di chat. Le tariffe, in USD per 1M token, input / output, sono aggiornate in tempo reale dal catalogo.

Verifica prima di eseguire il debug dell’SDK

Una richiesta basta per capire se il problema riguarda la chiave, l’endpoint o l’SDK. Se restituisce 200, la stessa credenziale funziona per la CLI avviata dall’SDK; se qualcosa continua a non funzionare, il problema riguarda dove sono impostate le variabili, non i loro valori.

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

Riferimenti

L’SDK è open source su anthropics/claude-agent-sdk-python. Il comportamento dell’ambiente descritto qui deriva dal suo trasporto dei sottoprocessi, esaminato il 2026-09-04. L’SDK TypeScript ha la stessa architettura: controlla la CLI anziché chiamare l’API, quindi è ancora la CLI a leggere le variabili di instradamento. Il suo README non documenta né l’opzione né questo comportamento, quindi verifica il nome dell’opzione nei relativi tipi prima di affidarti alla forma esplicita. Il lato Kunavo è costituito dall’API Messages; gli altri client che usano lo stesso instradamento sono elencati nell’hub delle integrazioni.