Claude Code SDK
Pelajari tentang integrasi Claude Code secara programatis ke dalam aplikasi Anda dengan Claude Code SDK.
Claude Code SDK memungkinkan menjalankan Claude Code sebagai subprocess, menyediakan cara untuk membangun asisten coding bertenaga AI dan alat yang memanfaatkan kemampuan Claude.
SDK tersedia untuk penggunaan command line, TypeScript, dan Python.
Autentikasi
Claude Code SDK mendukung beberapa metode autentikasi:
Kunci API Anthropic
Untuk menggunakan Claude Code SDK secara langsung dengan API Anthropic, kami merekomendasikan membuat kunci API khusus:
- Buat kunci API Anthropic di Anthropic Console
- Kemudian, atur variabel environment
ANTHROPIC_API_KEY
. Kami merekomendasikan menyimpan kunci ini dengan aman (misalnya, menggunakan Github secret)
Kredensial API pihak ketiga
SDK juga mendukung penyedia API pihak ketiga:
- Amazon Bedrock: Atur variabel environment
CLAUDE_CODE_USE_BEDROCK=1
dan konfigurasikan kredensial AWS - Google Vertex AI: Atur variabel environment
CLAUDE_CODE_USE_VERTEX=1
dan konfigurasikan kredensial Google Cloud
Untuk instruksi konfigurasi terperinci untuk penyedia pihak ketiga, lihat dokumentasi Amazon Bedrock dan Google Vertex AI.
Penggunaan dasar SDK
Claude Code SDK memungkinkan Anda menggunakan Claude Code dalam mode non-interaktif dari aplikasi Anda.
Command line
Berikut adalah beberapa contoh dasar untuk SDK command line:
TypeScript
SDK TypeScript disertakan dalam paket utama @anthropic-ai/claude-code
di NPM:
SDK TypeScript menerima semua argumen yang didukung oleh SDK command line, serta:
Argumen | Deskripsi | Default |
---|---|---|
abortController | Abort controller | new AbortController() |
cwd | Direktori kerja saat ini | process.cwd() |
executable | Runtime JavaScript mana yang akan digunakan | node saat berjalan dengan Node.js, bun saat berjalan dengan Bun |
executableArgs | Argumen untuk diteruskan ke executable | [] |
pathToClaudeCodeExecutable | Path ke executable Claude Code | Executable yang dikirim dengan @anthropic-ai/claude-code |
Python
SDK Python tersedia sebagai claude-code-sdk
di PyPI:
Prasyarat:
- Python 3.10+
- Node.js
- Claude Code CLI:
npm install -g @anthropic-ai/claude-code
Penggunaan dasar:
SDK Python menerima semua argumen yang didukung oleh SDK command line melalui kelas ClaudeCodeOptions
:
Penggunaan lanjutan
Dokumentasi di bawah ini menggunakan SDK command line sebagai contoh, tetapi juga dapat digunakan dengan SDK TypeScript dan Python.
Percakapan multi-turn
Untuk percakapan multi-turn, Anda dapat melanjutkan percakapan atau melanjutkan dari sesi terbaru:
System prompt kustom
Anda dapat menyediakan system prompt kustom untuk memandu perilaku Claude:
Anda juga dapat menambahkan instruksi ke system prompt default:
Konfigurasi MCP
Model Context Protocol (MCP) memungkinkan Anda memperluas Claude Code dengan alat dan sumber daya tambahan dari server eksternal. Menggunakan flag --mcp-config
, Anda dapat memuat server MCP yang menyediakan kemampuan khusus seperti akses database, integrasi API, atau tooling kustom.
Buat file konfigurasi JSON dengan server MCP Anda:
Kemudian gunakan dengan Claude Code:
Saat menggunakan alat MCP, Anda harus secara eksplisit mengizinkannya menggunakan flag --allowedTools
. Nama alat MCP mengikuti pola mcp__<serverName>__<toolName>
dimana:
serverName
adalah kunci dari file konfigurasi MCP AndatoolName
adalah alat spesifik yang disediakan oleh server tersebut
Langkah keamanan ini memastikan bahwa alat MCP hanya digunakan ketika secara eksplisit diizinkan.
Jika Anda hanya menentukan nama server (yaitu, mcp__<serverName>
), semua alat dari server tersebut akan diizinkan.
Pola glob (misalnya, mcp__go*
) tidak didukung.
Alat prompt izin kustom
Secara opsional, gunakan --permission-prompt-tool
untuk memasukkan alat MCP yang akan kami gunakan untuk memeriksa apakah pengguna memberikan izin kepada model untuk memanggil alat tertentu. Ketika model memanggil alat, hal berikut terjadi:
- Kami pertama memeriksa pengaturan izin: semua file settings.json, serta
--allowedTools
dan--disallowedTools
yang diteruskan ke SDK; jika salah satu dari ini mengizinkan atau menolak panggilan alat, kami melanjutkan dengan panggilan alat - Jika tidak, kami memanggil alat MCP yang Anda berikan dalam
--permission-prompt-tool
Alat MCP --permission-prompt-tool
diberikan nama alat dan input, dan harus mengembalikan payload yang di-JSON-stringify dengan hasilnya. Payload harus berupa salah satu dari:
Misalnya, implementasi alat prompt izin MCP TypeScript mungkin terlihat seperti ini:
Untuk menggunakan alat ini, tambahkan server MCP Anda (misalnya dengan --mcp-config
), kemudian panggil SDK seperti ini:
Catatan penggunaan:
- Gunakan
updatedInput
untuk memberi tahu model bahwa prompt izin mengubah inputnya; jika tidak, aturupdatedInput
ke input asli, seperti dalam contoh di atas. Misalnya, jika alat menunjukkan diff edit file kepada pengguna dan memungkinkan mereka mengedit diff secara manual, alat prompt izin harus mengembalikan edit yang diperbarui tersebut. - Payload harus di-JSON-stringify
Opsi CLI yang tersedia
SDK memanfaatkan semua opsi CLI yang tersedia di Claude Code. Berikut adalah yang utama untuk penggunaan SDK:
Flag | Deskripsi | Contoh |
---|---|---|
--print , -p | Jalankan dalam mode non-interaktif | claude -p "query" |
--output-format | Tentukan format output (text , json , stream-json ) | claude -p --output-format json |
--resume , -r | Lanjutkan percakapan berdasarkan ID sesi | claude --resume abc123 |
--continue , -c | Lanjutkan percakapan terbaru | claude --continue |
--verbose | Aktifkan logging verbose | claude --verbose |
--max-turns | Batasi turn agentik dalam mode non-interaktif | claude --max-turns 3 |
--system-prompt | Override system prompt (hanya dengan --print ) | claude --system-prompt "Custom instruction" |
--append-system-prompt | Tambahkan ke system prompt (hanya dengan --print ) | claude --append-system-prompt "Custom instruction" |
--allowedTools | Daftar alat yang diizinkan dipisahkan spasi, atau string daftar alat yang diizinkan dipisahkan koma | claude --allowedTools mcp__slack mcp__filesystem claude --allowedTools "Bash(npm install),mcp__filesystem" |
--disallowedTools | Daftar alat yang ditolak dipisahkan spasi, atau string daftar alat yang ditolak dipisahkan koma | claude --disallowedTools mcp__splunk mcp__github claude --disallowedTools "Bash(git commit),mcp__github" |
--mcp-config | Muat server MCP dari file JSON | claude --mcp-config servers.json |
--permission-prompt-tool | Alat MCP untuk menangani prompt izin (hanya dengan --print ) | claude --permission-prompt-tool mcp__auth__prompt |
Untuk daftar lengkap opsi CLI dan fitur, lihat dokumentasi referensi CLI.
Format output
SDK mendukung beberapa format output:
Output teks (default)
Mengembalikan hanya teks respons:
Output JSON
Mengembalikan data terstruktur termasuk metadata:
Format respons:
Output JSON streaming
Streaming setiap pesan saat diterima:
Setiap percakapan dimulai dengan pesan sistem init
awal, diikuti oleh daftar pesan pengguna dan asisten, diikuti oleh pesan sistem result
akhir dengan statistik. Setiap pesan dipancarkan sebagai objek JSON terpisah.
Skema pesan
Pesan yang dikembalikan dari JSON API diketik secara ketat sesuai dengan skema berikut:
Kami akan segera menerbitkan tipe-tipe ini dalam format yang kompatibel dengan JSONSchema. Kami menggunakan semantic versioning untuk paket Claude Code utama untuk mengkomunikasikan perubahan breaking pada format ini.
Tipe Message
dan MessageParam
tersedia di SDK Anthropic. Misalnya, lihat SDK Anthropic TypeScript dan Python.
Format input
SDK mendukung beberapa format input:
Input teks (default)
Teks input dapat diberikan sebagai argumen:
Atau teks input dapat di-pipe melalui stdin:
Input JSON streaming
Stream pesan yang disediakan melalui stdin
dimana setiap pesan mewakili turn pengguna. Ini memungkinkan beberapa turn percakapan tanpa meluncurkan ulang binary claude
dan memungkinkan memberikan panduan kepada model saat sedang memproses permintaan.
Setiap pesan adalah objek JSON ‘User message’, mengikuti format yang sama dengan skema pesan output. Pesan diformat menggunakan format jsonl dimana setiap baris input adalah objek JSON lengkap. Input JSON streaming memerlukan -p
dan --output-format stream-json
.
Saat ini ini terbatas pada pesan pengguna khusus teks.
Contoh
Integrasi script sederhana
Memproses file dengan Claude
Manajemen sesi
Praktik terbaik
-
Gunakan format output JSON untuk parsing programatis respons:
-
Tangani error dengan baik - periksa kode keluar dan stderr:
-
Gunakan manajemen sesi untuk mempertahankan konteks dalam percakapan multi-turn
-
Pertimbangkan timeout untuk operasi yang berjalan lama:
-
Hormati batas rate saat membuat beberapa permintaan dengan menambahkan delay antara panggilan
Aplikasi dunia nyata
Claude Code SDK memungkinkan integrasi yang kuat dengan alur kerja pengembangan Anda. Salah satu contoh yang menonjol adalah Claude Code GitHub Actions, yang menggunakan SDK untuk menyediakan review kode otomatis, pembuatan PR, dan kemampuan triase issue langsung dalam alur kerja GitHub Anda.
Sumber daya terkait
- Penggunaan dan kontrol CLI - Dokumentasi CLI lengkap
- Integrasi GitHub Actions - Otomatisasi alur kerja GitHub Anda dengan Claude
- Alur kerja umum - Panduan langkah demi langkah untuk kasus penggunaan umum