Migrasi ke Claude Agent SDK

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

Ikhtisar

Claude Code SDK telah diganti namanya menjadi Claude Agent SDK dan dokumentasinya telah ditata ulang. Perubahan ini mencerminkan kemampuan SDK yang lebih luas untuk membangun agent AI di luar tugas-tugas pemrograman.

Apakah Anda justru bermigrasi dari OpenAI Agents SDK? Resep migrasi OpenAI Agents SDK memetakan setiap primitif ke Claude Agent SDK melalui satu contoh yang dikerjakan secara lengkap.

Apa yang Berubah

Langkah-Langkah Migrasi

Migrasi proyek TypeScript atau 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.

Migrasi 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

[!WARNING]

Untuk meningkatkan isolasi dan konfigurasi eksplisit, Claude Agent SDK v0.1.0 memperkenalkan perubahan yang merusak kompatibilitas bagi pengguna yang bermigrasi dari Claude Code SDK.

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"
  }
});

from claude_agent_sdk import query, ClaudeAgentOptions
import asyncio


async def main():
    # SEBELUMNYA (v0.0.x) - Menggunakan system prompt Claude Code secara default
    async for message in query(prompt="Hello"):
        print(message)

    # SESUDAHNYA (v0.1.0) - Menggunakan system prompt minimal secara default
    # Untuk mendapatkan perilaku lama, secara eksplisit minta preset Claude Code:
    async for message in query(
        prompt="Hello",
        options=ClaudeAgentOptions(
            system_prompt={"type": "preset", "preset": "claude_code"}  # Gunakan preset
        ),
    ):
        print(message)

    # Atau gunakan system prompt kustom:
    async for message in query(
        prompt="Hello",
        options=ClaudeAgentOptions(system_prompt="You are a helpful coding assistant"),
    ):
        print(message)


asyncio.run(main())

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 Kontrol pengaturan filesystem dengan 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.

[!NOTE]

Python SDK 0.1.59 dan lebih awal memperlakukan daftar kosong sama dengan menghilangkan opsi, jadi tingkatkan sebelum mengandalkan setting_sources=[]. Lihat Apa yang tidak dikontrol settingSources untuk input yang dibaca bahkan ketika settingSources adalah [].

Langkah Berikutnya

• Jelajahi Ringkasan Agent SDK untuk mempelajari fitur yang tersedia
• Lihat Referensi SDK TypeScript untuk dokumentasi API terperinci
• Tinjau Referensi SDK Python untuk dokumentasi khusus Python
• Pelajari tentang Custom Tools dan Integrasi MCP