Migrate từ Claude Code SDK sang Claude Agent SDK

Chú ý

Nội dung migration guide có thể thay đổi theo các phiên bản SDK mới. Kiểm tra trang gốc để có thông tin mới nhất.

Tổng quan

Claude Code SDK đã được đổi tên thành Claude Agent SDK và tài liệu của nó đã được tổ chức lại. Thay đổi này phản ánh khả năng rộng hơn của SDK trong việc xây dựng AI agent, không chỉ giới hạn ở các tác vụ coding.

Những gì đã thay đổi

Khía cạnh	Cũ	Mới
Tên package (TS/JS)	@anthropic-ai/claude-code	@anthropic-ai/claude-agent-sdk
Package Python	claude-code-sdk	claude-agent-sdk
Vị trí tài liệu	Tài liệu Claude Code	API Guide → mục Agent SDK

Ghi chú

Thay đổi về tài liệu: Tài liệu Agent SDK đã chuyển từ tài liệu Claude Code sang API Guide, dưới một mục Agent SDK riêng. Tài liệu Claude Code giờ tập trung vào công cụ CLI và các tính năng tự động hoá.

Các bước migrate

Với dự án TypeScript/JavaScript

1. Gỡ package cũ:

npm uninstall @anthropic-ai/claude-code

2. Cài package mới:

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

3. Cập nhật import:

Đổi mọi import từ @anthropic-ai/claude-code sang @anthropic-ai/claude-agent-sdk:

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

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

4. Cập nhật dependency trong package.json:

Nếu bạn có package này trong package.json, cập nhật nó:

Trước:

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

Sau:

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

5. Xem lại breaking change

Thực hiện các thay đổi code cần thiết để hoàn tất việc migrate.

Với dự án Python

1. Gỡ package cũ:

pip uninstall -y claude-code-sdk

Nếu package cũ chưa được cài, pip sẽ in WARNING: Skipping claude-code-sdk as it is not installed. Đó là điều bình thường, bạn có thể tiếp tục bước tiếp theo.

2. Cài package mới:

pip install claude-agent-sdk

3. Cập nhật import:

Đổi mọi import từ claude_code_sdk sang claude_agent_sdk:

# Before
from claude_code_sdk import query, ClaudeCodeOptions

# After
from claude_agent_sdk import query, ClaudeAgentOptions

4. Cập nhật tên type:

Đổi ClaudeCodeOptions thành ClaudeAgentOptions:

# Before
from claude_code_sdk import query, ClaudeCodeOptions

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

# After
from claude_agent_sdk import query, ClaudeAgentOptions

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

5. Xem lại breaking change

Thực hiện các thay đổi code cần thiết để hoàn tất việc migrate.

Breaking change

Chú ý

Để cải thiện tính cô lập và cấu hình tường minh, Claude Agent SDK v0.1.0 đưa vào các breaking change cho người dùng migrate từ Claude Code SDK. Đọc kỹ phần này trước khi migrate.

Python: ClaudeCodeOptions đổi tên thành ClaudeAgentOptions

Thay đổi: Type ClaudeCodeOptions của Python SDK đã được đổi tên thành ClaudeAgentOptions.

Cách migrate:

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

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

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

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

Lý do thay đổi: Tên type giờ khớp với thương hiệu “Claude Agent SDK” và mang lại sự nhất quán trong quy ước đặt tên của SDK.

System prompt không còn là mặc định

Thay đổi: SDK không còn dùng system prompt của Claude Code làm mặc định.

Cách migrate:

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

// BEFORE (v0.0.x) - Used Claude Code's system prompt by default
const before = query({ prompt: "Hello" });

// AFTER (v0.1.0) - Uses minimal system prompt by default
// To get the old behavior, explicitly request Claude Code's preset:
const presetResult = query({
  prompt: "Hello",
  options: {
    systemPrompt: { type: "preset", preset: "claude_code" }
  }
});

// Or use a custom system prompt:
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():
    # BEFORE (v0.0.x) - Used Claude Code's system prompt by default
    async for message in query(prompt="Hello"):
        print(message)

    # AFTER (v0.1.0) - Uses minimal system prompt by default
    # To get the old behavior, explicitly request Claude Code's preset:
    async for message in query(
        prompt="Hello",
        options=ClaudeAgentOptions(
            system_prompt={"type": "preset", "preset": "claude_code"}  # Use the preset
        ),
    ):
        print(message)

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


asyncio.run(main())

Lý do thay đổi: Mang lại khả năng kiểm soát và cô lập tốt hơn cho ứng dụng SDK. Giờ bạn có thể xây dựng agent với hành vi tuỳ biến mà không kế thừa các chỉ dẫn tập trung vào CLI của Claude Code.

Mặc định của settings sources

Mặc định này đã bị đổi trong thời gian ngắn ở v0.1.0 rồi được revert lại, nên không cần hành động migrate gì.

Hành vi hiện tại: Bỏ qua settingSources trên query() sẽ tải settings ở cấp user, project, và local từ filesystem, khớp với CLI. Bao gồm ~/.claude/settings.json, .claude/settings.json, .claude/settings.local.json, các file CLAUDE.md, và custom command.

Để chạy cô lập khỏi settings trên filesystem, truyền một mảng rỗng:

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

const isolatedResult = query({
  prompt: "Hello",
  options: {
    settingSources: [] // No filesystem settings loaded
  }
});

// Or load only specific sources:
const projectOnlyResult = query({
  prompt: "Hello",
  options: {
    settingSources: ["project"] // Only project settings
  }
});

from claude_agent_sdk import query, ClaudeAgentOptions
import asyncio


async def main():
    async for message in query(
        prompt="Hello",
        options=ClaudeAgentOptions(setting_sources=[]),  # No filesystem settings loaded
    ):
        print(message)

    # Or load only specific sources:
    async for message in query(
        prompt="Hello",
        options=ClaudeAgentOptions(
            setting_sources=["project"]  # Only project settings
        ),
    ):
        print(message)


asyncio.run(main())

Tính cô lập này đặc biệt quan trọng cho pipeline CI/CD, ứng dụng deployed, môi trường test, và hệ thống multi-tenant nơi các tuỳ biến cục bộ không nên bị rò rỉ vào.

Ghi chú

SDK v0.1.0 từng mặc định không tải settings nào trong thời gian ngắn; điều này đã được revert ở các bản phát hành sau. Python SDK 0.1.59 trở về trước xử lý một danh sách rỗng giống hệt như bỏ qua option, nên hãy upgrade trước khi dựa vào setting_sources=[]. Xem What settingSources does not control để biết những input vẫn được đọc kể cả khi settingSources là [].

Vì sao đổi tên?

Claude Code SDK ban đầu được thiết kế cho các tác vụ coding, nhưng nó đã phát triển thành một framework mạnh mẽ để xây dựng mọi loại AI agent. Tên mới “Claude Agent SDK” phản ánh tốt hơn khả năng của nó:

• Xây dựng agent nghiệp vụ (trợ lý pháp lý, tư vấn tài chính, hỗ trợ khách hàng)
• Tạo agent coding chuyên biệt (bot SRE, security reviewer, agent review code)
• Phát triển agent tuỳ biến cho bất kỳ lĩnh vực nào với tool use, tích hợp MCP, và nhiều hơn nữa

Cần hỗ trợ?

Nếu bạn gặp vấn đề trong quá trình migrate:

Với TypeScript/JavaScript:

1. Kiểm tra mọi import đã được cập nhật để dùng @anthropic-ai/claude-agent-sdk
2. Xác nhận package.json có tên package mới
3. Chạy npm install để đảm bảo dependency đã được cập nhật

Với Python:

1. Kiểm tra mọi import đã được cập nhật để dùng claude_agent_sdk
2. Xác nhận requirements.txt hoặc pyproject.toml có tên package mới
3. Chạy pip install claude-agent-sdk để đảm bảo package đã được cài

Bước tiếp theo

• Khám phá Tổng quan Agent SDK để tìm hiểu các tính năng khả dụng
• Xem Hướng dẫn bắt đầu nhanh để có tài liệu API chi tiết
• Tìm hiểu về Custom Tools và tích hợp MCP

Nguồn

Dịch và biên soạn từ Migrate to Claude Agent SDK.