Claude Agent SDK로 마이그레이션
공식 기준: https://code.claude.com/docs/en/agent-sdk/migration-guide
기준일: 2026-07-26 · CLI 기준 2.1.220
개요
Claude Code SDK가 Claude Agent SDK로 이름이 바뀌고 문서가 API Guide의 Agent SDK 섹션으로 재배치되었습니다. 코딩 외 일반 에이전트 구축 능력을 반영한 변경입니다.
| 항목 | 이전 | 이후 |
|---|---|---|
| TS/JS 패키지 | @anthropic-ai/claude-code |
@anthropic-ai/claude-agent-sdk |
| Python 패키지 | claude-code-sdk |
claude-agent-sdk |
| 문서 위치 | Claude Code docs | API Guide → Agent SDK |
핵심 개념
- 패키지·import 경로 교체
- Python
ClaudeCodeOptions→ClaudeAgentOptions - 시스템 프롬프트가 더 이상 Claude Code 기본값이 아님 → 필요 시
claude_codepreset 명시 settingSources생략 시 CLI와 같이 filesystem 설정 로드; 격리는[]
상세
TypeScript/JavaScript
npm uninstall @anthropic-ai/claude-code
npm install @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";
package.json 의존성도 새 패키지명(^0.3.0 등)으로 갱신합니다.
Python
pip uninstall -y claude-code-sdk
pip install claude-agent-sdk
# 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")
Breaking changes
1) ClaudeCodeOptions → ClaudeAgentOptions
타입 이름만 변경. 필드 의미는 동일 패턴을 유지합니다.
2) System prompt 기본값 제거
v0.1.0+ 기본은 minimal system prompt입니다. 이전 CLI형 동작:
const presetResult = query({
prompt: "Hello",
options: {
systemPrompt: { type: "preset", preset: "claude_code" }
}
});
options=ClaudeAgentOptions(
system_prompt={"type": "preset", "preset": "claude_code"}
)
또는 문자열 커스텀 프롬프트. 이유: SDK 앱이 CLI 중심 지침을 상속하지 않도록 격리·명시 제어.
3) Settings sources
현재: settingSources 생략 시 user/project/local 로드 (CLI 동일). 격리:
options: { settingSources: [] }
ClaudeAgentOptions(setting_sources=[])
CI/CD·멀티테넌트에서 로컬 커스텀 누수 방지에 중요합니다. Python SDK 0.1.59 이하는 빈 리스트를 생략과 동일 취급할 수 있어 업그레이드 후 []를 신뢰하세요. managed policy 등은 []여도 읽힐 수 있습니다.
이름 변경 이유
비즈니스 에이전트, 전문 코딩 봇, 도메인 에이전트 등 도구 사용·MCP 기반 일반 에이전트 프레임워크로 확장되었기 때문입니다.
체크리스트
- 패키지 uninstall/install 완료
- 모든 import·타입명 교체
-
claude_codepreset 또는 커스텀 system prompt 명시 - CI에서는
settingSources: []검토 -
npm install/pip install후 스모크 테스트