Claude Agent SDK

SDK'de base_url seçeneğini aradığınızda hiçbir şey bulamazsınız; bu, belgelerdeki bir eksiklik değildir — böyle bir seçenek yoktur. SDK, Claude Code CLI'yi alt süreç olarak çalıştırır ve ANTHROPIC_BASE_URL ile ANTHROPIC_AUTH_TOKEN değerlerini CLI okur. Bu iki değeri ayarladığınızda, aracı kodunuzda değişiklik yapmadan aracının yaptığı her çağrı yönlendirilir.

# 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

Ortam neden CLI'ye aktarılıyor?

Bu konuya bir paragraf ayırmakta fayda var; çünkü bu, bir gün çalışmayı bırakabilecek bir kestirme ile üzerine güvenle kurulum yapabileceğiniz belgelenmiş bir özellik arasındaki farktır. Python SDK'nın alt süreç aktarımı, alt sürecin ortamını üst sürecin os.environ değerinden oluşturur ve tek bir anahtarı kaldırır: CLAUDECODE. Böylece alt süreç kendisinin bir Claude Code oturumunda çalıştığını sanmaz. Ardından CLAUDE_CODE_ENTRYPOINT, ClaudeAgentOptions.env ve son olarak SDK sürümü birleştirilir.

Bunun iki sonucu vardır; ikincisi çoğu kişinin gözden kaçırdığı noktadır. Kabuğunuzdaki her şey CLI'ye ulaşır, dolayısıyla iki değişkeni dışa aktarmak işe yarar. Ayrıca options.env, devralınan ortamın üzerine eklenir; böylece açıkça belirtilen değer eski bir dışa aktarımın gerisinde kalmak yerine onun önüne geçer. Kod subprocess_cli.py konumundadır.

Açık biçim ve ne zaman mutlaka kullanılması gerektiği

Dışa aktarılan değişkenler kendi makinenizde uygundur, ancak başka ortamlarda güvenilmezdir: aracının uç noktası sürecin nasıl başlatıldığına bağlı hâle gelir ve profilinizi yüklemeyen bir zamanlayıcı, kapsayıcı veya CI işi altında ilk kez çalıştırıldığında sorun çıkarır. env değerini options nesnesine geçirmek, yönlendirmeyi programın bir parçası hâline getirir.

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)

Adım adım

1. /app/keys adresinde bir anahtar oluşturup kopyalayın — anahtar yalnızca bir kez gösterilir.
2. Yönlendirmenin nerede tanımlanacağına karar verin: yerel çalışmalar için dışa aktarılan değişkenleri, gözetimsiz çalışan her şey için ClaudeAgentOptions(env=…) kullanın.
3. ANTHROPIC_BASE_URL değerini https://api.kunavo.com, ANTHROPIC_AUTH_TOKEN değerini ise sk-kn-… anahtarınız olarak ayarlayın.
4. ANTHROPIC_MODEL, ANTHROPIC_DEFAULT_OPUS_MODEL ve ANTHROPIC_DEFAULT_SONNET_MODEL değerlerini sunulan kimliklere ayarlayın: CLI'nin yerleşik varsayılanı ile opus ve sonnet takma adları Anthropic'in en yeni modellerini izler; Kunavo'nun sunmadığı bir model — sonnet takma adının istediği Sonnet 5.5 — 404 döndürür.
5. ANTHROPIC_DEFAULT_HAIKU_MODEL ayarını da claude-haiku-4-5 olarak belirleyin: bu ayar olmadan CLI'nin haiku takma adı Kunavo'nun sunmadığı bir model kimliği ister (v2.1.293'ten itibaren Haiku 5.5); bu nedenle model: haiku ile tanımlanan alt ajanlar 404 hatası verir. Aynı satır, CLI'nin kendi başına başlattığı arka plan alt görevlerini de en ucuz katmanda çalıştırır.
6. Programınızı çalıştırın. Aracı kodunda hiçbir şeyi değiştirmeniz gerekmez.

Hangi alt görev için hangi katman?

Bir aracı, tek bir isteği birçok ücretlendirilen gidiş gelişe dönüştürür; bu nedenle katman eşlemesi burada sohbet uygulamasındakinden daha önemlidir. Fiyatlar, katalogdan canlı olarak alınan, 1M token başına USD cinsinden giriş / çıkış ücretleridir.

SDK'de hata ayıklamadan önce doğrulayın

Tek bir istek, sorunun anahtardan mı, uç noktadan mı, yoksa SDK'den mi kaynaklandığını ortaya çıkarır. Bu istek 200 döndürürse, aynı kimlik bilgisi SDK'nin başlattığı CLI'de de çalışır; geriye kalan sorun, değişkenlerin içeriklerinde değil ayarlandıkları yerdedir.

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

Kaynak

SDK'nin kaynak kodu anthropics/claude-agent-sdk-python adresinde açıktır. Burada açıklanan ortam davranışı, SDK'nin kendi alt süreç aktarımından alınmış ve 2026-09-04 tarihinde incelenmiştir. TypeScript SDK aynı mimariye sahiptir; API'yi çağırmak yerine CLI'yi çalıştırır ve dolayısıyla yönlendirme değişkenlerini yine CLI okur. README'sinde seçenek ya da davranış belgelenmediğinden, orada açık biçime güvenmeden önce seçenek adını tür tanımlarında doğrulayın. Kunavo tarafı Messages API'dir; aynı şekilde yönlendirme yapan diğer istemcilere entegrasyonlar merkezinden ulaşabilirsiniz.