Claude Code SDK
Bangun agen AI kustom dengan Claude Code SDK
Mengapa menggunakan Claude Code SDK?
Claude Code SDK menyediakan semua blok bangunan yang Anda butuhkan untuk membangun agen siap produksi:
- Integrasi Claude yang dioptimalkan: Caching prompt otomatis dan optimisasi performa
- Ekosistem tool yang kaya: Operasi file, eksekusi kode, pencarian web, dan ekstensibilitas MCP
- Izin lanjutan: Kontrol granular atas kemampuan agen
- Esensi produksi: Penanganan error bawaan, manajemen sesi, dan monitoring
Apa yang bisa Anda bangun dengan SDK?
Berikut adalah beberapa contoh jenis agen yang dapat Anda buat:
Agen coding:
- Agen SRE yang mendiagnosis dan memperbaiki masalah produksi
- Bot review keamanan yang mengaudit kode untuk kerentanan
- Asisten engineering oncall yang melakukan triase insiden
- Agen review kode yang menegakkan gaya dan praktik terbaik
Agen bisnis:
- Asisten hukum yang meninjau kontrak dan kepatuhan
- Penasihat keuangan yang menganalisis laporan dan prakiraan
- Agen dukungan pelanggan yang menyelesaikan masalah teknis
- Asisten pembuatan konten untuk tim pemasaran
SDK saat ini tersedia dalam TypeScript dan Python, dengan antarmuka baris perintah (CLI) untuk prototyping cepat.
Quick start
Jalankan agen pertama Anda dalam waktu kurang dari 5 menit:
Install SDK
Install @anthropic-ai/claude-code
dari NPM:
Install @anthropic-ai/claude-code
dari NPM:
Install @anthropic-ai/claude-code
dari NPM:
Install claude-code-sdk
dari PyPI dan @anthropic-ai/claude-code
dari NPM:
(Opsional) Install IPython untuk pengembangan interaktif:
Set API key Anda
Dapatkan API key Anda dari Anthropic Console dan set variabel environment ANTHROPIC_API_KEY
:
Buat agen pertama Anda
Buat salah satu dari contoh agen ini:
Jalankan agen
Salin dan tempel perintah di atas langsung ke terminal Anda.
Salin dan tempel perintah di atas langsung ke terminal Anda.
- Set up proyek:
-
Tambahkan
"type": "module"
ke package.json Anda -
Simpan kode di atas sebagai
legal-agent.ts
, lalu jalankan:
Simpan kode di atas sebagai legal-agent.py
, lalu jalankan:
Untuk notebook IPython/Jupyter, Anda dapat menjalankan kode langsung di sel:
Setiap contoh di atas membuat agen yang berfungsi yang akan:
- Menganalisis prompt menggunakan kemampuan penalaran Claude
- Merencanakan pendekatan multi-langkah untuk menyelesaikan masalah
- Menjalankan tindakan menggunakan tool seperti operasi file, perintah bash, dan pencarian web
- Memberikan rekomendasi yang dapat ditindaklanjuti berdasarkan analisis
Penggunaan inti
Gambaran umum
Claude Code SDK memungkinkan Anda berinteraksi dengan Claude Code dalam mode non-interaktif dari aplikasi Anda.
Prasyarat
- Node.js 18+
@anthropic-ai/claude-code
dari NPM
Penggunaan dasar
Antarmuka baris perintah utama ke Claude Code adalah perintah claude
. Gunakan flag --print
(atau -p
) untuk menjalankan dalam mode non-interaktif dan mencetak hasil akhir:
Konfigurasi
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 |
--append-system-prompt | Tambahkan ke system prompt (hanya dengan --print ) | claude --append-system-prompt "Instruksi kustom" |
--allowedTools | Daftar tool yang diizinkan dipisahkan spasi, atau string daftar tool yang diizinkan dipisahkan koma | claude --allowedTools mcp__slack mcp__filesystem claude --allowedTools "Bash(npm install),mcp__filesystem" |
--disallowedTools | Daftar tool yang ditolak dipisahkan spasi, atau string daftar tool 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 | Tool 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.
Prasyarat
- Node.js 18+
@anthropic-ai/claude-code
dari NPM
Penggunaan dasar
Antarmuka baris perintah utama ke Claude Code adalah perintah claude
. Gunakan flag --print
(atau -p
) untuk menjalankan dalam mode non-interaktif dan mencetak hasil akhir:
Konfigurasi
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 |
--append-system-prompt | Tambahkan ke system prompt (hanya dengan --print ) | claude --append-system-prompt "Instruksi kustom" |
--allowedTools | Daftar tool yang diizinkan dipisahkan spasi, atau string daftar tool yang diizinkan dipisahkan koma | claude --allowedTools mcp__slack mcp__filesystem claude --allowedTools "Bash(npm install),mcp__filesystem" |
--disallowedTools | Daftar tool yang ditolak dipisahkan spasi, atau string daftar tool 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 | Tool 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.
Prasyarat
- Node.js 18+
@anthropic-ai/claude-code
dari NPM
Untuk melihat kode sumber TypeScript SDK, kunjungi halaman @anthropic-ai/claude-code
di NPM.
Penggunaan dasar
Antarmuka utama melalui TypeScript SDK adalah fungsi query
, yang mengembalikan async iterator yang melakukan streaming pesan saat tiba:
Konfigurasi
TypeScript SDK menerima semua argumen yang didukung oleh command line, serta opsi tambahan berikut:
Argumen | Deskripsi | Default |
---|---|---|
abortController | Abort controller | new AbortController() |
cwd | Direktori kerja saat ini | process.cwd() |
executable | Runtime JavaScript mana yang digunakan | node saat menjalankan dengan Node.js, bun saat menjalankan dengan Bun |
executableArgs | Argumen untuk diteruskan ke executable | [] |
pathToClaudeCodeExecutable | Path ke executable Claude Code | Executable yang dikirim dengan @anthropic-ai/claude-code |
permissionMode | Mode izin untuk sesi | "default" (opsi: "default" , "acceptEdits" , "plan" , "bypassPermissions" ) |
Prasyarat
- Python 3.10+
claude-code-sdk
dari PyPI- Node.js 18+
@anthropic-ai/claude-code
dari NPM
Untuk melihat kode sumber Python SDK, lihat repo claude-code-sdk
.
Untuk pengembangan interaktif, gunakan IPython: pip install ipython
Penggunaan dasar
Python SDK menyediakan dua antarmuka utama:
- Kelas
ClaudeSDKClient
(Direkomendasikan)
Terbaik untuk streaming respons, percakapan multi-turn, dan aplikasi interaktif:
SDK juga mendukung passing pesan terstruktur dan input gambar:
Contoh Python di halaman ini menggunakan asyncio
, tetapi Anda juga dapat menggunakan anyio
.
- Fungsi
query
Untuk query sederhana, satu kali:
Konfigurasi
Karena Python SDK menerima semua argumen yang didukung oleh command line melalui kelas ClaudeCodeOptions
.
Autentikasi
API key Anthropic
Untuk autentikasi dasar, ambil API key Anthropic dari Anthropic Console dan set variabel environment ANTHROPIC_API_KEY
, seperti yang ditunjukkan dalam Quick start.
Kredensial API pihak ketiga
SDK juga mendukung autentikasi melalui penyedia API pihak ketiga:
- Amazon Bedrock: Set variabel environment
CLAUDE_CODE_USE_BEDROCK=1
dan konfigurasi kredensial AWS - Google Vertex AI: Set variabel environment
CLAUDE_CODE_USE_VERTEX=1
dan konfigurasi kredensial Google Cloud
Untuk instruksi konfigurasi detail untuk penyedia pihak ketiga, lihat dokumentasi Amazon Bedrock dan Google Vertex AI.
Percakapan multi-turn
Untuk percakapan multi-turn, Anda dapat melanjutkan percakapan atau melanjutkan dari sesi terbaru:
Menggunakan Plan Mode
Plan Mode memungkinkan Claude menganalisis kode tanpa membuat modifikasi, berguna untuk review kode dan merencanakan perubahan.
Plan Mode membatasi editing, pembuatan file, dan eksekusi perintah. Lihat mode izin untuk detail.
System prompt kustom
System prompt mendefinisikan peran, keahlian, dan perilaku agen Anda. Di sinilah Anda menentukan jenis agen apa yang sedang Anda bangun:
Penggunaan Lanjutan
Tool kustom melalui MCP
Model Context Protocol (MCP) memungkinkan Anda memberikan tool dan kemampuan kustom kepada agen Anda. Ini sangat penting untuk membangun agen khusus yang membutuhkan integrasi spesifik domain.
Contoh konfigurasi tool agen:
Contoh penggunaan:
Saat menggunakan tool MCP, Anda harus secara eksplisit mengizinkannya menggunakan flag --allowedTools
. Nama tool MCP mengikuti pola mcp__<serverName>__<toolName>
di mana:
serverName
adalah kunci dari file konfigurasi MCP AndatoolName
adalah tool spesifik yang disediakan oleh server tersebut
Langkah keamanan ini memastikan bahwa tool MCP hanya digunakan ketika secara eksplisit diizinkan.
Jika Anda hanya menentukan nama server (yaitu, mcp__<serverName>
), semua tool dari server tersebut akan diizinkan.
Pola glob (misalnya, mcp__go*
) tidak didukung.
Tool prompt izin kustom
Secara opsional, gunakan --permission-prompt-tool
untuk memasukkan tool MCP yang akan kami gunakan untuk memeriksa apakah pengguna memberikan izin kepada model untuk memanggil tool tertentu. Ketika model memanggil tool, 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 tool, kami melanjutkan dengan panggilan tool - Jika tidak, kami memanggil tool MCP yang Anda berikan di
--permission-prompt-tool
Tool MCP --permission-prompt-tool
diteruskan nama tool dan input, dan harus mengembalikan payload yang di-JSON-stringify dengan hasilnya. Payload harus salah satu dari:
Contoh implementasi:
Catatan penggunaan:
- Gunakan
updatedInput
untuk memberi tahu model bahwa prompt izin memutasi inputnya; jika tidak, setupdatedInput
ke input asli, seperti dalam contoh di atas. Misalnya, jika tool menunjukkan diff edit file kepada pengguna dan memungkinkan mereka mengedit diff secara manual, tool prompt izin harus mengembalikan edit yang diperbarui tersebut. - Payload harus di-JSON-stringify
Format output
SDK mendukung beberapa format output:
Output teks (default)
Output JSON
Mengembalikan data terstruktur termasuk metadata:
Format respons:
Output JSON streaming
Melakukan 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 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)
Input JSON streaming
Stream pesan yang disediakan melalui stdin
di mana setiap pesan mewakili turn pengguna. Ini memungkinkan beberapa turn percakapan tanpa meluncurkan ulang binary claude
dan memungkinkan memberikan panduan kepada model s aat sedang memproses permintaan.
Setiap pesan adalah objek JSON ‘User message’, mengikuti format yang sama dengan skema pesan output. Pesan diformat menggunakan format jsonl di mana 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 agen
Bot respons insiden SRE
Review keamanan otomatis
Asisten hukum multi-turn
Praktik Terbaik Khusus Python
Pola Kunci
Tips IPython/Jupyter
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 rate limit saat membuat beberapa permintaan dengan menambahkan delay antar panggilan
Sumber daya terkait
- Penggunaan dan kontrol CLI - Dokumentasi CLI lengkap
- Integrasi GitHub Actions - Otomatisasi workflow GitHub Anda dengan Claude
- Workflow umum - Panduan langkah demi langkah untuk kasus penggunaan umum