SpyBara
Go Premium

agent-sdk/migration-guide.md 2026-09-08 20:00 UTC to 2026-09-09 22:58 UTC

This page contains 41 additions and 141 deletions.

2026
Wed 9 22:58

Migrasi ke Claude Agent SDK

Panduan untuk migrasi Claude Code TypeScript dan Python SDKs ke Claude Agent SDK

Ikhtisar

Claude Code SDK telah diubah namanya menjadi Claude Agent SDK dan dokumentasinya telah diorganisir ulang. Perubahan ini mencerminkan kemampuan SDK yang lebih luas untuk membangun agen AI di luar sekadar tugas pengkodean.

Bermigrasi dari OpenAI Agents SDK? Resep migrasi OpenAI Agents SDK memetakan setiap primitif ke Claude Agent SDK melalui satu contoh yang telah dikerjakan.

Apa yang Berubah

Aspek Lama Baru
Nama Paket (TS/JS) @anthropic-ai/claude-code @anthropic-ai/claude-agent-sdk
Paket Python claude-code-sdk claude-agent-sdk
Lokasi Dokumentasi Claude Code docs Claude Code docs → bagian Agent SDK yang didedikasikan

Langkah-Langkah Migrasi

Untuk Proyek TypeScript/JavaScript

1. Uninstall paket lama:

npm uninstall @anthropic-ai/claude-code

2. Install paket baru:

npm install @anthropic-ai/claude-agent-sdk

3. Perbarui impor Anda:

Ubah semua impor dari @anthropic-ai/claude-code ke @anthropic-ai/claude-agent-sdk:

// Sebelumnya
import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-code";

// Sesudahnya
import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";

4. Perbarui package.json:

Jika @anthropic-ai/claude-code masih tercantum dalam package.json Anda, gantikan dengan @anthropic-ai/claude-agent-sdk dan perbarui juga rentang versinya, misalnya dari "^0.0.42" menjadi "^0.3.0".

5. Tinjau perubahan yang merusak

Buat perubahan kode apa pun yang diperlukan untuk menyelesaikan migrasi.

Untuk Proyek Python

1. Uninstall paket lama:

pip uninstall -y claude-code-sdk

Jika paket lama tidak terinstal, pip mencetak WARNING: Skipping claude-code-sdk as it is not installed. Itu adalah hal yang diharapkan dan Anda dapat melanjutkan ke langkah berikutnya.

2. Install paket baru:

pip install claude-agent-sdk

Jika claude-code-sdk tercantum dalam requirements.txt atau pyproject.toml Anda, gantikan dengan claude-agent-sdk.

3. Perbarui impor Anda:

Ubah semua impor dari claude_code_sdk ke claude_agent_sdk:

# Sebelumnya
from claude_code_sdk import query, ClaudeCodeOptions

# Sesudahnya
from claude_agent_sdk import query, ClaudeAgentOptions

4. Tinjau perubahan yang merusak

Buat perubahan kode apa pun yang diperlukan untuk menyelesaikan migrasi.

Perubahan yang merusak kompatibilitas

Python: ClaudeCodeOptions diganti nama menjadi ClaudeAgentOptions

Apa yang berubah: Tipe SDK Python ClaudeCodeOptions telah diganti nama menjadi ClaudeAgentOptions.

Migrasi:

# SEBELUMNYA (claude-code-sdk)
from claude_code_sdk import query, ClaudeCodeOptions

options = ClaudeCodeOptions(model="claude-opus-4-7", permission_mode="acceptEdits")

# SESUDAHNYA (claude-agent-sdk)
from claude_agent_sdk import query, ClaudeAgentOptions

options = ClaudeAgentOptions(model="claude-opus-4-7", permission_mode="acceptEdits")

System prompt tidak lagi default

Apa yang berubah: SDK tidak lagi menggunakan system prompt Claude Code secara default.

Migrasi:

import { query } from "@anthropic-ai/claude-agent-sdk";

// SEBELUMNYA (v0.0.x) - Menggunakan system prompt Claude Code secara default
const before = query({ prompt: "Hello" });

// SESUDAHNYA (v0.1.0) - Menggunakan system prompt minimal secara default
// Untuk mendapatkan perilaku lama, secara eksplisit minta preset Claude Code:
const presetResult = query({
prompt: "Hello",
options: {
systemPrompt: { type: "preset", preset: "claude_code" }
}
});

// Atau gunakan system prompt kustom:
const customResult = query({
prompt: "Hello",
options: {
systemPrompt: "You are a helpful coding assistant"
}
});

Default sumber pengaturan

Default ini secara singkat diubah di v0.1.0 untuk tidak memuat pengaturan filesystem dan kemudian dikembalikan, jadi tidak ada tindakan migrasi yang diperlukan.

Perilaku saat ini: Menghilangkan settingSources pada query() memuat pengaturan pengguna, proyek, dan filesystem lokal, sesuai dengan CLI. Ini mencakup ~/.claude/settings.json, .claude/settings.json, .claude/settings.local.json, file CLAUDE.md, dan perintah kustom.

Untuk menjalankan terisolasi dari pengaturan filesystem, teruskan settingSources: [], atau setting_sources=[] di Python. Lihat Control filesystem settings with settingSources untuk mengetahui apa yang dimuat setiap sumber.

Isolasi sangat penting untuk pipeline CI/CD, aplikasi yang diterapkan, lingkungan pengujian, dan sistem multi-tenant di mana kustomisasi lokal tidak boleh bocor.

Langkah Berikutnya