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:

1

Install SDK

Install @anthropic-ai/claude-code dari NPM:

npm install -g @anthropic-ai/claude-code
2

Set API key Anda

Dapatkan API key Anda dari Anthropic Console dan set variabel environment ANTHROPIC_API_KEY:

export ANTHROPIC_API_KEY="your-api-key-here"
3

Buat agen pertama Anda

Buat salah satu dari contoh agen ini:

# Buat asisten hukum sederhana
claude -p "Review klausul kontrak ini untuk masalah potensial: 'Pihak setuju untuk tanggung jawab tak terbatas...'" \
  --append-system-prompt "Anda adalah asisten hukum. Identifikasi risiko dan sarankan perbaikan."
4

Jalankan agen

Salin dan tempel perintah di atas langsung ke terminal Anda.

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:

claude -p "Analisis performa sistem" \
  --append-system-prompt "Anda adalah insinyur performa" \
  --allowedTools "Bash,Read,WebSearch" \
  --permission-mode acceptEdits \
  --cwd /path/to/project

Konfigurasi

SDK memanfaatkan semua opsi CLI yang tersedia di Claude Code. Berikut adalah yang utama untuk penggunaan SDK:

FlagDeskripsiContoh
--print, -pJalankan dalam mode non-interaktifclaude -p "query"
--output-formatTentukan format output (text, json, stream-json)claude -p --output-format json
--resume, -rLanjutkan percakapan berdasarkan ID sesiclaude --resume abc123
--continue, -cLanjutkan percakapan terbaruclaude --continue
--verboseAktifkan logging verboseclaude --verbose
--append-system-promptTambahkan ke system prompt (hanya dengan --print)claude --append-system-prompt "Instruksi kustom"
--allowedToolsDaftar 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"
--disallowedToolsDaftar 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-configMuat server MCP dari file JSONclaude --mcp-config servers.json
--permission-prompt-toolTool 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.

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:

# Lanjutkan percakapan terbaru
claude --continue "Sekarang refactor ini untuk performa yang lebih baik"

# Lanjutkan percakapan spesifik berdasarkan ID sesi
claude --resume 550e8400-e29b-41d4-a716-446655440000 "Update test-nya"

# Lanjutkan dalam mode non-interaktif
claude --resume 550e8400-e29b-41d4-a716-446655440000 "Perbaiki semua masalah linting" --no-interactive

Menggunakan Plan Mode

Plan Mode memungkinkan Claude menganalisis kode tanpa membuat modifikasi, berguna untuk review kode dan merencanakan perubahan.

claude -p "Review kode ini" --permission-mode plan

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:

# Agen respons insiden SRE
claude -p "API down, investigasi" \
  --append-system-prompt "Anda adalah ahli SRE. Diagnosis masalah secara sistematis dan berikan solusi yang dapat ditindaklanjuti."

# Agen review dokumen hukum  
claude -p "Review kontrak ini" \
  --append-system-prompt "Anda adalah pengacara korporat. Identifikasi risiko, sarankan perbaikan, dan pastikan kepatuhan."

# Tambahkan ke system prompt default
claude -p "Refactor fungsi ini" \
  --append-system-prompt "Selalu sertakan penanganan error yang komprehensif dan unit test."

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:

{
  "mcpServers": {
    "slack": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "env": {"SLACK_TOKEN": "your-slack-token"}
    },
    "jira": {
      "command": "npx", 
      "args": ["-y", "@modelcontextprotocol/server-jira"],
      "env": {"JIRA_TOKEN": "your-jira-token"}
    },
    "database": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {"DB_CONNECTION_STRING": "your-db-url"}
    }
  }
}

Contoh penggunaan:

# Agen SRE dengan tool monitoring
claude -p "Investigasi gangguan layanan pembayaran" \
  --mcp-config sre-tools.json \
  --allowedTools "mcp__datadog,mcp__pagerduty,mcp__kubernetes" \
  --append-system-prompt "Anda adalah SRE. Gunakan data monitoring untuk mendiagnosis masalah."

# Agen dukungan pelanggan dengan akses CRM
claude -p "Bantu selesaikan tiket pelanggan #12345" \
  --mcp-config support-tools.json \
  --allowedTools "mcp__zendesk,mcp__stripe,mcp__user_db" \
  --append-system-prompt "Anda adalah spesialis dukungan teknis."

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 Anda
  • toolName 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:

  1. 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
  2. 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:

// panggilan tool diizinkan
{
  "behavior": "allow",
  "updatedInput": {...}, // input yang diperbarui, atau cukup kembalikan input asli
}

// panggilan tool ditolak
{
  "behavior": "deny",
  "message": "..." // string yang dapat dibaca manusia menjelaskan mengapa izin ditolak
}

Contoh implementasi:

# Gunakan dengan konfigurasi server MCP Anda
claude -p "Analisis dan perbaiki masalah keamanan" \
  --permission-prompt-tool mcp__security__approval_prompt \
  --mcp-config security-tools.json \
  --allowedTools "Read,Grep" \
  --disallowedTools "Bash(rm*),Write"

# Dengan aturan izin kustom
claude -p "Refactor codebase" \
  --permission-prompt-tool mcp__custom__permission_check \
  --mcp-config custom-config.json \
  --output-format json

Catatan penggunaan:

  • Gunakan updatedInput untuk memberi tahu model bahwa prompt izin memutasi inputnya; jika tidak, set updatedInput 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)

claude -p "Jelaskan file src/components/Header.tsx"
# Output: Ini adalah komponen React yang menunjukkan...

Output JSON

Mengembalikan data terstruktur termasuk metadata:

claude -p "Bagaimana cara kerja data layer?" --output-format json

Format respons:

{
  "type": "result",
  "subtype": "success",
  "total_cost_usd": 0.003,
  "is_error": false,
  "duration_ms": 1234,
  "duration_api_ms": 800,
  "num_turns": 6,
  "result": "Teks respons di sini...",
  "session_id": "abc123"
}

Output JSON streaming

Melakukan streaming setiap pesan saat diterima:

$ claude -p "Bangun aplikasi" --output-format stream-json

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:

type SDKMessage =
  // Pesan asisten
  | {
      type: "assistant";
      message: Message; // dari Anthropic SDK
      session_id: string;
    }

  // Pesan pengguna
  | {
      type: "user";
      message: MessageParam; // dari Anthropic SDK
      session_id: string;
    }

  // Dipancarkan sebagai pesan terakhir
  | {
      type: "result";
      subtype: "success";
      duration_ms: float;
      duration_api_ms: float;
      is_error: boolean;
      num_turns: int;
      result: string;
      session_id: string;
      total_cost_usd: float;
    }

  // Dipancarkan sebagai pesan terakhir, ketika kami telah mencapai jumlah maksimum turn
  | {
      type: "result";
      subtype: "error_max_turns" | "error_during_execution";
      duration_ms: float;
      duration_api_ms: float;
      is_error: boolean;
      num_turns: int;
      session_id: string;
      total_cost_usd: float;
    }

  // Dipancarkan sebagai pesan pertama di awal percakapan
  | {
      type: "system";
      subtype: "init";
      apiKeySource: string;
      cwd: string;
      session_id: string;
      tools: string[];
      mcp_servers: {
        name: string;
        status: string;
      }[];
      model: string;
      permissionMode: "default" | "acceptEdits" | "bypassPermissions" | "plan";
    };

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)

# Argumen langsung
claude -p "Jelaskan kode ini"

# Dari stdin
echo "Jelaskan kode ini" | claude -p

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.

$ echo '{"type":"user","message":{"role":"user","content":[{"type":"text","text":"Jelaskan kode ini"}]}}' | claude -p --output-format=stream-json --input-format=stream-json --verbose

Contoh integrasi agen

Bot respons insiden SRE

#!/bin/bash

# Agen respons insiden otomatis
investigate_incident() {
    local incident_description="$1"
    local severity="${2:-medium}"
    
    claude -p "Insiden: $incident_description (Tingkat keparahan: $severity)" \
      --append-system-prompt "Anda adalah ahli SRE. Diagnosis masalah, nilai dampak, dan berikan item tindakan segera." \
      --output-format json \
      --allowedTools "Bash,Read,WebSearch,mcp__datadog" \
      --mcp-config monitoring-tools.json
}

# Penggunaan
investigate_incident "Payment API mengembalikan error 500" "high"

Review keamanan otomatis

# Agen audit keamanan untuk pull request
audit_pr() {
    local pr_number="$1"
    
    gh pr diff "$pr_number" | claude -p \
      --append-system-prompt "Anda adalah insinyur keamanan. Review PR ini untuk kerentanan, pola tidak aman, dan masalah kepatuhan." \
      --output-format json \
      --allowedTools "Read,Grep,WebSearch"
}

# Penggunaan dan simpan ke file
audit_pr 123 > security-report.json

Asisten hukum multi-turn

# Review dokumen hukum dengan persistensi sesi
session_id=$(claude -p "Mulai sesi review hukum" --output-format json | jq -r '.session_id')

# Review kontrak dalam beberapa langkah
claude -p --resume "$session_id" "Review contract.pdf untuk klausul tanggung jawab"
claude -p --resume "$session_id" "Periksa kepatuhan dengan persyaratan GDPR" 
claude -p --resume "$session_id" "Generate ringkasan eksekutif risiko"

Praktik Terbaik Khusus Python

Pola Kunci

import asyncio
from claude_code_sdk import ClaudeSDKClient, ClaudeCodeOptions

# Selalu gunakan context manager
async with ClaudeSDKClient() as client:
    await client.query("Analisis kode ini")
    async for msg in client.receive_response():
        # Proses pesan streaming
        pass

# Jalankan beberapa agen secara bersamaan
async with ClaudeSDKClient() as reviewer, ClaudeSDKClient() as tester:
    await asyncio.gather(
        reviewer.query("Review main.py"),
        tester.query("Tulis test untuk main.py")
    )

# Penanganan error
from claude_code_sdk import CLINotFoundError, ProcessError

try:
    async with ClaudeSDKClient() as client:
        # Kode Anda di sini
        pass
except CLINotFoundError:
    print("Install CLI: npm install -g @anthropic-ai/claude-code")
except ProcessError as e:
    print(f"Process error: {e}")

# Kumpulkan respons lengkap dengan metadata
async def get_response(client, prompt):
    await client.query(prompt)
    text = []
    async for msg in client.receive_response():
        if hasattr(msg, 'content'):
            for block in msg.content:
                if hasattr(block, 'text'):
                    text.append(block.text)
        if type(msg).__name__ == "ResultMessage":
            return {'text': ''.join(text), 'cost': msg.total_cost_usd}

Tips IPython/Jupyter

# Di Jupyter, gunakan await langsung di sel
client = ClaudeSDKClient()
await client.connect()
await client.query("Analisis data.csv")
async for msg in client.receive_response():
    print(msg)
await client.disconnect()

# Buat fungsi helper yang dapat digunakan kembali
async def stream_print(client, prompt):
    await client.query(prompt)
    async for msg in client.receive_response():
        if hasattr(msg, 'content'):
            for block in msg.content:
                if hasattr(block, 'text'):
                    print(block.text, end='', flush=True)

Praktik terbaik

  • Gunakan format output JSON untuk parsing programatis respons:

    # Parse respons JSON dengan jq
    result=$(claude -p "Generate kode" --output-format json)
    code=$(echo "$result" | jq -r '.result')
    cost=$(echo "$result" | jq -r '.cost_usd')
    
  • Tangani error dengan baik - periksa kode keluar dan stderr:

    if ! claude -p "$prompt" 2>error.log; then
        echo "Error terjadi:" >&2
        cat error.log >&2
        exit 1
    fi
    
  • Gunakan manajemen sesi untuk mempertahankan konteks dalam percakapan multi-turn

  • Pertimbangkan timeout untuk operasi yang berjalan lama:

    timeout 300 claude -p "$complex_prompt" || echo "Timeout setelah 5 menit"
    
  • Hormati rate limit saat membuat beberapa permintaan dengan menambahkan delay antar panggilan

Sumber daya terkait