Skip to main content
Sesi Agent SDK membaca konfigurasi dari file pengaturan, variabel lingkungan, dan objek options yang Anda berikan saat memulainya. Halaman ini menunjukkan cara menyusun objek options dan apa file pengaturan serta variabel lingkungan yang mengontrolnya. Untuk setiap tipe opsi dan default, lihat referensi Options (TypeScript) dan ClaudeAgentOptions (Python).

Berikan opsi ke sesi

Setiap panggilan query() menerima objek opsi: Options di TypeScript, ClaudeAgentOptions di Python. Setiap bidang bersifat opsional, dan sesi yang dimulai tanpa opsi berjalan dengan default SDK. Contoh di bawah mengonfigurasi sesi baca-saja yang merangkum TODO terbuka proyek. Pasangan dibaca sebagai TypeScript / Python di mana ejaan berbeda:
  • model: memilih model
  • allowedTools / allowed_tools: pra-menyetujui daftar alat baca-saja
  • maxTurns / max_turns: membatasi jumlah giliran
  • cwd: menetapkan direktori kerja
Arahkan cwd ke salah satu proyek Anda sendiri dan jalankan contohnya. Ringkasan TODO terbuka proyek tersebut akan dicetak saat pesan hasil tiba. allowedTools (TypeScript) atau allowed_tools (Python) pra-menyetujui alat yang terdaftar, sehingga panggilan ke alat tersebut berjalan tanpa menunggu persetujuan. Alat di luar daftar tetap tersedia. Ketika Claude memanggil alat yang tidak terdaftar, mode izin menentukan apakah panggilan berjalan. Untuk informasi lebih lanjut, lihat Aturan izin dan penolakan.

Muat file pengaturan

File pengaturan menyediakan konfigurasi di luar objek opsi. Dua opsi mengontrol cara memuatnya:
  • settingSources / setting_sources: mengontrol sumber sistem file mana yang dimuat: pengguna, proyek, dan lokal. File pengaturan dan file CLAUDE.md tiba melalui sumber ini.
  • settings: memuat jalur file pengaturan atau string JSON sebaris dalam bahasa apa pun, dan TypeScript juga menerima objek pengaturan. Bentuk apa pun yang Anda berikan menggantikan pengaturan sistem file pengguna, proyek, dan lokal; hanya pengaturan kebijakan terkelola yang lebih tinggi. Referensi mendokumentasikan urutan preseden lengkap di bawah Preseden pengaturan untuk TypeScript dan Preseden pengaturan untuk Python.
Berikan [] untuk menonaktifkan pengaturan pengguna, proyek, dan lokal. Untuk informasi lebih lanjut, lihat Gunakan fitur Claude Code di SDK.

Pilih model

Kecuali opsi model, pengaturan Anda, atau lingkungan Anda memilih model, sesi baru dimulai pada model default Claude Code. Untuk urutan sumber tersebut, lihat Atur model Anda. Atur model untuk menetapkan model tertentu, atau untuk memilih model yang lebih kecil untuk agen yang lebih cepat dan lebih murah. Nilai mengambil alias model atau nama model lengkap; alias dan versi yang mereka selesaikan terdaftar di bawah Alias model. Atur fallbackModel (TypeScript) atau fallback_model (Python) untuk menamai model cadangan. Ketika model utama kelebihan beban atau tidak tersedia, sesi beralih ke cadangan. Model utama dicoba ulang di awal setiap giliran pengguna, sehingga sesi kembali ke model utama setelah pemadaman berlalu. Di kedua bahasa, opsi menerima model tunggal atau daftar cadangan yang dipisahkan koma. Untuk urutan dan batas rantai, lihat Rantai model fallback. Di TypeScript, fallback yang sama dengan model melempar kesalahan saat startup. Contoh di bawah menunjukkan daftar fallback di TypeScript dan fallback tunggal di Python:
Parameter permintaan Messages API Messages API temperature, top_p, dan max_tokens tidak memiliki bidang pada objek opsi di kedua bahasa. Atur tingkat upaya atau batas pengeluaran sebagai gantinya, atau panggil Messages API ketika Anda memerlukan parameter tersebut secara langsung.

Atur variabel lingkungan

Opsi env menetapkan variabel lingkungan untuk proses Claude Code yang menjalankan sesi Anda. Apakah nilai Anda menggantikan lingkungan yang diwariskan atau menggabungkannya berbeda menurut bahasa:
  • TypeScript: env menggantikan lingkungan subproses
  • Python: SDK menggabungkan nilai Anda di atas lingkungan yang diwariskan, dan nilai Anda menggantikan nilai yang diwariskan
Di TypeScript, sebarkan process.env ke dalam env untuk menyimpan variabel yang diwariskan seperti PATH, HOME, dan ANTHROPIC_API_KEY. Ketika Anda membiarkan env tidak diatur, subproses mewarisi lingkungan Anda di kedua bahasa. Contoh merutekan lalu lintas API melalui gateway dengan menetapkan ANTHROPIC_BASE_URL.
Variabel yang Anda berikan juga dapat mengonfigurasi Claude Code itu sendiri. Untuk variabel yang dibaca proses Claude Code, lihat Variabel lingkungan. Untuk menyetel waktu tunggu API dan deteksi macet dengan cara ini, ikuti bagian Tangani respons API yang lambat atau macet di referensi TypeScript atau referensi Python.

Atur direktori kerja

Atur cwd untuk menjalankan sesi di direktori tertentu. Ketika Anda membiarkan cwd tidak diatur, sesi berjalan di direktori kerja proses Anda. Tidak ada SDK yang memiliki setter untuk cwd. Untuk menjalankan di direktori berbeda, mulai sesi lain dengan cwd tersebut. Claude Code membaca direktori kerja untuk menentukan: Untuk membiarkan alat menjangkau file di luar direktori kerja, tambahkan jalur dengan additionalDirectories (TypeScript) atau add_dirs (Python). Untuk cakupan hibah tersebut, lihat Direktori tambahan memberikan akses file, bukan konfigurasi.

Batasi giliran dan pengeluaran

Batasi giliran dan pengeluaran dengan maxTurns / max_turns dan maxBudgetUsd / max_budget_usd. Kedua batas dimatikan saat tidak diatur. Ketika sesi mencapai batas, jalankan berakhir dengan pesan hasil yang subtipe-nya menamai batas, error_max_turns atau error_max_budget_usd. Apa yang terjadi selanjutnya berbeda menurut mode input:
  • query() sekali jalan: SDK menghasilkan hasil batas dan kemudian melempar, jadi bungkus loop dalam blok try untuk melanjutkan melewati kesalahan
  • Input streaming: sesi tetap hidup melewati hasil batas, dan hitungan giliran maksimal dimulai ulang untuk setiap pesan antrian. Total anggaran terakumulasi di seluruh pesan, dan setelah pengeluaran mencapai batas, pesan nanti dalam percakapan yang sama berakhir dengan hasil anggaran yang sama. /clear memulai anggaran dari awal
Kedua batas memperlakukan 0 secara berbeda:
  • maxTurns / max_turns: 0 menjalankan sesi tanpa batas giliran, sama dengan membiarkan opsi tidak diatur
  • maxBudgetUsd / max_budget_usd: CLI menolak 0 sebagai jumlah yang tidak valid saat startup, dan sesi tidak pernah berjalan
Untuk informasi lebih lanjut tentang kedua batas, termasuk pengeluaran subagen, lihat Giliran dan anggaran.

Ubah konfigurasi di tengah sesi

Ketika Anda memulai sesi dengan input streaming, Anda dapat mengganti model dan mode izinnya saat berjalan. Tempat Anda memanggil setter berbeda menurut bahasa:
  • TypeScript: metode pada objek yang query() kembalikan
  • Python: metode pada ClaudeSDKClient, karena query() mengembalikan iterator biasa tanpa metode kontrol
Kedua bahasa memiliki setter yang sama:
  • setModel() / set_model(): mengganti model. Panggilnya tanpa model untuk beralih ke model default Claude Code daripada model yang Anda berikan dalam opsi.
  • setPermissionMode() / set_permission_mode(): mengganti mode izin
TypeScript juga memiliki applyFlagSettings() dan updateSettings():
  • applyFlagSettings(): menerapkan pengaturan saat runtime, seperti dalam await session.applyFlagSettings({ effortLevel: "high" }). Metode mengambil kunci file pengaturan daripada bidang opsi, jadi periksa referensi applyFlagSettings() untuk skema dan untuk kunci mana yang berlaku di tengah sesi.
  • updateSettings(): menulis set kunci yang diizinkan ke file pengaturan lokal proyek, seperti dalam await session.updateSettings("localSettings", { outputStyle: "Explanatory" }). Kunci yang ditulis berlaku pada permintaan sesi berikutnya dan bertahan untuk sesi nanti yang memuat pengaturan local. Baris metode dalam tabel metode menamai kunci yang diizinkan dan lantai versi.
Contoh di bawah menjalankan sesi dua giliran, mengubah konfigurasi di antara giliran, dan mencetak model yang menjawab setiap giliran. Di TypeScript, aliran prompt menyimpan pesan kedua sampai setter telah berjalan, dan giliran kedua berjalan pada model baru.
Pada Claude API, program mencetak First turn model: claude-sonnet-5, kemudian Second turn model: claude-opus-5 setelah pengalihan.
Setiap model memiliki cache prompt-nya sendiri, jadi setelah pengalihan di tengah sesi, permintaan berikutnya menghitung ulang percakapan lengkap tanpa cache pada tarif model baru. Untuk informasi lebih lanjut, lihat Mengganti model.

Konfigurasi fitur spesifik

Tabel di bawah memetakan setiap opsi ke fitur yang dikonfigurasinya. Untuk opsi yang tidak dicakup halaman ini, lihat referensi TypeScript dan Python. Jika Anda tahu tujuan Anda tetapi tidak tahu opsi mana yang melayaninya, mulai dari Pilih fitur yang tepat.

Langkah berikutnya

Untuk melihat konfigurasi yang disusun menjadi agen yang berfungsi:
  • Quickstart: bangun dan jalankan agen pertama dari awal hingga akhir
  • Contoh: temukan proyek lengkap yang dapat dijalankan atau resep Claude Cookbook yang dipandu yang cocok dengan apa yang ingin Anda bangun
  • Isolasi multi-penyewa: isolasi pengaturan dan memori setiap penyewa dengan settingSources / setting_sources, env, dan cwd