คู่มือ Migration ไปยัง Claude Agent SDK

คู่มือสำหรับการ migrate Claude Code TypeScript และ Python SDKs ไปยัง Claude Agent SDK

ภาพรวม

Claude Code SDK ถูกเปลี่ยนชื่อเป็น Claude Agent SDK และเอกสารถูกจัดระเบียบใหม่ การเปลี่ยนแปลงนี้สะท้อนถึงความสามารถที่กว้างขึ้นของ SDK สำหรับการสร้าง AI agents นอกเหนือจาก coding tasks

สิ่งที่เปลี่ยนแปลง

ด้าน	เดิม	ใหม่
Package Name (TS/JS)	@anthropic-ai/claude-code	@anthropic-ai/claude-agent-sdk
Python Package	claude-code-sdk	claude-agent-sdk
ตำแหน่งเอกสาร	Claude Code docs	API Guide → Agent SDK section

note

การเปลี่ยนแปลงเอกสาร: เอกสาร Agent SDK ได้ย้ายจาก Claude Code docs ไปยัง API Guide ภายใต้ section Agent SDK เฉพาะ Claude Code docs ตอนนี้มุ่งเน้นที่ CLI tool และ automation features

ขั้นตอน Migration

สำหรับ TypeScript/JavaScript Projects

1. Uninstall package เดิม:

npm uninstall @anthropic-ai/claude-code

2. Install package ใหม่:

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

3. อัปเดต imports:

เปลี่ยน imports ทั้งหมดจาก @anthropic-ai/claude-code เป็น @anthropic-ai/claude-agent-sdk:

// ก่อน
import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-code";

// หลัง
import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";

4. อัปเดต package.json dependencies:

ก่อน:

{
  "dependencies": {
    "@anthropic-ai/claude-code": "^0.0.42"
  }
}

หลัง:

{
  "dependencies": {
    "@anthropic-ai/claude-agent-sdk": "^0.2.0"
  }
}

5. ตรวจสอบ breaking changes

สำหรับ Python Projects

1. Uninstall package เดิม:

pip uninstall claude-code-sdk

2. Install package ใหม่:

pip install claude-agent-sdk

3. อัปเดต imports:

เปลี่ยน imports ทั้งหมดจาก claude_code_sdk เป็น claude_agent_sdk:

# ก่อน
from claude_code_sdk import query, ClaudeCodeOptions

# หลัง
from claude_agent_sdk import query, ClaudeAgentOptions

4. อัปเดตชื่อ type:

เปลี่ยน ClaudeCodeOptions เป็น ClaudeAgentOptions:

# ก่อน
from claude_code_sdk import query, ClaudeCodeOptions

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

# หลัง
from claude_agent_sdk import query, ClaudeAgentOptions

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

5. ตรวจสอบ breaking changes

Breaking Changes

warning

เพื่อปรับปรุง isolation และ explicit configuration Claude Agent SDK v0.1.0 แนะนำ breaking changes สำหรับผู้ใช้ที่ migrate จาก Claude Code SDK ตรวจสอบ section นี้อย่างระมัดระวังก่อน migrate

Python: ClaudeCodeOptions เปลี่ยนชื่อเป็น ClaudeAgentOptions

สิ่งที่เปลี่ยน: type ClaudeCodeOptions ใน Python SDK ถูกเปลี่ยนชื่อเป็น ClaudeAgentOptions

Migration:

# ก่อน (claude-code-sdk)
from claude_code_sdk import query, ClaudeCodeOptions

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

# หลัง (claude-agent-sdk)
from claude_agent_sdk import query, ClaudeAgentOptions

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

ทำไมถึงเปลี่ยน: ชื่อ type ตอนนี้ตรงกับ branding "Claude Agent SDK" และให้ความสอดคล้องกันใน naming conventions ของ SDK

System prompt ไม่ใช่ default อีกต่อไป

สิ่งที่เปลี่ยน: SDK ไม่ใช้ system prompt ของ Claude Code โดย default อีกต่อไป

Migration:

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

// ก่อน (v0.0.x) - ใช้ system prompt ของ Claude Code โดย default
const before = query({ prompt: "Hello" });

// หลัง (v0.1.0) - ใช้ minimal system prompt โดย default
// เพื่อให้ได้พฤติกรรมเดิม ให้ขอ Claude Code's preset อย่างชัดเจน:
const presetResult = query({
  prompt: "Hello",
  options: {
    systemPrompt: { type: "preset", preset: "claude_code" }
  }
});

// หรือใช้ custom system prompt:
const customResult = query({
  prompt: "Hello",
  options: {
    systemPrompt: "You are a helpful coding assistant"
  }
});

# ก่อน (v0.0.x) - ใช้ system prompt ของ Claude Code โดย default
async for message in query(prompt="Hello"):
    print(message)

# หลัง (v0.1.0) - ใช้ minimal system prompt โดย default
# เพื่อให้ได้พฤติกรรมเดิม ให้ขอ Claude Code's preset อย่างชัดเจน:
from claude_agent_sdk import query, ClaudeAgentOptions

async for message in query(
    prompt="Hello",
    options=ClaudeAgentOptions(
        system_prompt={"type": "preset", "preset": "claude_code"}
    ),
):
    print(message)

# หรือใช้ custom system prompt:
async for message in query(
    prompt="Hello",
    options=ClaudeAgentOptions(system_prompt="You are a helpful coding assistant"),
):
    print(message)

ทำไมถึงเปลี่ยน: ให้การควบคุมและ isolation ที่ดีกว่าสำหรับ SDK applications คุณสามารถสร้าง agents ที่มีพฤติกรรม custom โดยไม่ต้อง inherit instructions ที่มุ่งเน้น CLI ของ Claude Code

Settings sources default

Default นี้ถูกเปลี่ยนแปลงชั่วคราวใน v0.1.0 จากนั้น reverted ดังนั้นไม่จำเป็นต้องดำเนินการ migrate

พฤติกรรมปัจจุบัน: การละเว้น settingSources บน query() จะโหลด user, project, และ local filesystem settings ตรงกับ CLI

เพื่อรันแบบ isolated จาก filesystem settings ส่ง empty array:

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

const isolatedResult = query({
  prompt: "Hello",
  options: {
    settingSources: [] // ไม่มี filesystem settings โหลด
  }
});

from claude_agent_sdk import query, ClaudeAgentOptions

async for message in query(
    prompt="Hello",
    options=ClaudeAgentOptions(setting_sources=[]),  # ไม่มี filesystem settings โหลด
):
    print(message)

Isolation มีความสำคัญอย่างยิ่งสำหรับ CI/CD pipelines, deployed applications, test environments, และ multi-tenant systems

ทำไมถึงเปลี่ยนชื่อ?

Claude Code SDK ถูกออกแบบดั้งเดิมสำหรับ coding tasks แต่ได้พัฒนาเป็น framework ที่ทรงพลังสำหรับการสร้าง AI agents ทุกประเภท ชื่อใหม่ "Claude Agent SDK" สะท้อนความสามารถของมันได้ดีกว่า:

• สร้าง business agents (legal assistants, finance advisors, customer support)
• สร้าง specialized coding agents (SRE bots, security reviewers, code review agents)
• พัฒนา custom agents สำหรับ domain ใดก็ได้ด้วย tool use, MCP integration, และอื่นๆ

ขอความช่วยเหลือ

หากคุณพบปัญหาระหว่าง migration:

สำหรับ TypeScript/JavaScript:

1. ตรวจสอบว่า imports ทั้งหมดถูกอัปเดตให้ใช้ @anthropic-ai/claude-agent-sdk
2. ตรวจสอบว่า package.json มีชื่อ package ใหม่
3. รัน npm install เพื่อให้แน่ใจว่า dependencies อัปเดตแล้ว

สำหรับ Python:

1. ตรวจสอบว่า imports ทั้งหมดถูกอัปเดตให้ใช้ claude_agent_sdk
2. ตรวจสอบว่า requirements.txt หรือ pyproject.toml มีชื่อ package ใหม่
3. รัน pip install claude-agent-sdk เพื่อให้แน่ใจว่า package ถูก install

ขั้นตอนถัดไป

• ดู Agent SDK Overview เพื่อเรียนรู้เกี่ยวกับ features ที่ใช้ได้
• ดู TypeScript SDK Reference สำหรับ API documentation โดยละเอียด
• ดู Python SDK Reference สำหรับ Python-specific documentation
• เรียนรู้เกี่ยวกับ Custom Tools และ MCP Integration