Claude Agent SDK

Pencarian opsi base_url di SDK tidak menemukan apa pun, dan ini bukan kekurangan dokumentasi—opsi tersebut memang tidak ada. SDK menjalankan CLI Claude Code sebagai subprocess, dan CLI-lah yang membaca ANTHROPIC_BASE_URL dan ANTHROPIC_AUTH_TOKEN. Tetapkan kedua variabel tersebut agar semua panggilan yang dilakukan agen diarahkan ke sana, tanpa perlu mengubah kode agen Anda.

# 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

Mengapa lingkungan diteruskan ke CLI

Bagian ini layak dijelaskan dalam satu paragraf, karena inilah perbedaan antara trik yang mungkin berhenti berfungsi dan perilaku terdokumentasi yang dapat Anda andalkan. Transport subprocess SDK Python membangun lingkungan proses anak dari os.environ milik induknya dengan menghapus satu kunci—CLAUDECODE, agar proses anak tidak mengira dirinya berjalan di dalam sesi Claude Code—lalu menggabungkan CLAUDE_CODE_ENTRYPOINT, kemudian ClaudeAgentOptions.env, lalu versi SDK.

Ada dua konsekuensinya, dan yang kedua sering disalahpahami. Semua yang ada di shell Anda diteruskan ke CLI, jadi mengekspor kedua variabel itu akan berfungsi. Lalu options.env digabungkan di atas lingkungan yang diwarisi, sehingga bentuk eksplisit mengungguli ekspor lama, bukan sebaliknya. Kodenya ada di subprocess_cli.py.

Bentuk eksplisit dan kapan harus menggunakannya

Variabel yang diekspor tidak masalah di komputer Anda sendiri, tetapi rentan di tempat lain: endpoint agen menjadi bergantung pada cara proses diluncurkan, dan ini akan gagal saat pertama kali dijalankan oleh penjadwal, di dalam kontainer, atau dalam tugas CI yang tidak memuat profil Anda. Meneruskan env melalui objek options menjadikan perutean bagian dari program.

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)

Langkah demi langkah

1. Buat key di /app/keys dan salin — key hanya ditampilkan sekali.
2. Tentukan tempat perutean diatur: variabel yang diekspor untuk pekerjaan lokal, ClaudeAgentOptions(env=…) untuk apa pun yang berjalan tanpa pengawasan.
3. Tetapkan ANTHROPIC_BASE_URL ke https://api.kunavo.com dan ANTHROPIC_AUTH_TOKEN ke kunci sk-kn-… Anda.
4. Tetapkan ANTHROPIC_MODEL, ANTHROPIC_DEFAULT_OPUS_MODEL, dan ANTHROPIC_DEFAULT_SONNET_MODEL ke ID yang disediakan: default bawaan CLI serta alias opus dan sonnet mengikuti model terbaru Anthropic, dan model yang tidak disediakan Kunavo — Sonnet 5.5, yang diminta oleh alias sonnet — mengembalikan 404.
5. Tetapkan juga ANTHROPIC_DEFAULT_HAIKU_MODEL ke claude-haiku-4-5: tanpa pengaturan ini, alias haiku pada CLI meminta ID model yang tidak disediakan Kunavo (Haiku 5.5 sejak v2.1.293), sehingga subagen dengan model: haiku menghasilkan 404. Baris yang sama menempatkan sub-tugas latar belakang yang dijalankan CLI sendiri pada tier termurah.
6. Jalankan program Anda. Tidak ada yang berubah pada kode agen.

Tingkat untuk setiap sub-tugas

Agen menjalankan banyak permintaan—satu hal yang Anda minta dapat menghasilkan banyak putaran bolak-balik yang dikenai biaya—jadi pemetaan tingkat lebih penting di sini daripada di aplikasi obrolan. Tarifnya dalam USD per 1M token, masukan / keluaran, dan dibaca langsung dari katalog.

Verifikasi sebelum menelusuri masalah SDK

Satu permintaan dapat memastikan apakah kegagalan disebabkan oleh kunci, endpoint, atau SDK. Jika responsnya 200, kredensial yang sama berfungsi untuk CLI yang dijalankan SDK, dan masalah yang tersisa terletak pada tempat variabel ditetapkan, bukan pada isinya.

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

Referensi

SDK ini bersifat sumber terbuka di anthropics/claude-agent-sdk-python. Perilaku lingkungan yang dijelaskan di sini berasal dari transport subprocess SDK itu sendiri, yang diperiksa pada 2026-09-04. SDK TypeScript memiliki arsitektur yang sama—SDK tersebut mengendalikan CLI alih-alih memanggil API—jadi CLI kembali membaca variabel perutean; README-nya tidak mendokumentasikan opsi ataupun perilaku tersebut, jadi pastikan nama opsinya di tipe SDK sebelum mengandalkan bentuk eksplisit di sana. Bagian Kunavo dijelaskan di Messages API, sementara klien lain yang menggunakan cara perutean serupa dibahas di pusat integrasi.