Agent SDK로 마이그레이션하기(Migrate to Claude Agent SDK)

Agent SDK로 마이그레이션하기(Migrate to Claude Agent SDK)

Claude Code SDK가 Claude Agent SDK로 이름이 바뀌고 문서도 재구성됐어요. 이 변화는 SDK가 코딩 작업을 넘어 AI 에이전트를 만드는 더 넓은 기능을 담게 된 걸 반영해요. OpenAI Agents SDK에서 옮겨오는 경우라면 별도 레시피가 각 프리미티브를 예시 하나로 매핑해 줘요.

출처: 공식문서

본문

뭐가 바뀌었나

측면 이전 새 버전
패키지 이름(TS/JS) @anthropic-ai/claude-code @anthropic-ai/claude-agent-sdk
Python 패키지 claude-code-sdk claude-agent-sdk
문서 위치 Claude Code 문서 전용 Agent SDK 섹션

마이그레이션 단계

TypeScript/JavaScript 프로젝트

  1. 이전 패키지 제거: npm uninstall @anthropic-ai/claude-code
  2. 새 패키지 설치: npm install @anthropic-ai/claude-agent-sdk
  3. import 변경 — @anthropic-ai/claude-code → @anthropic-ai/claude-agent-sdk: 
    import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
  4. package.json의 @anthropic-ai/claude-code를 @anthropic-ai/claude-agent-sdk로 바꾸고 버전 범위도 업데이트(예: "^0.0.42" → "^0.3.0")
  5. 아래 breaking changes 검토 후 필요한 코드 수정

Python 프로젝트

  1. 이전 패키지 제거: pip uninstall -y claude-code-sdk. 이미 없으면 WARNING: Skipping claude-code-sdk as it is not installed.가 정상.
  2. 새 패키지 설치: pip install claude-agent-sdk. requirements.txt/pyproject.toml에 claude-code-sdk가 있으면 claude-agent-sdk로 교체.
  3. import 변경 — claude_code_sdk → claude_agent_sdk: 
    from claude_agent_sdk import query, ClaudeAgentOptions
  4. breaking changes 검토 후 코드 수정

Breaking changes

Claude Agent SDK v0.1.0은 Claude Code SDK에서 옮겨오는 사용자에게 분리·명시적 구성을 위해 breaking changes를 도입해요.

Python: ClaudeCodeOptions → ClaudeAgentOptions

# 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")

시스템 프롬프트 더 이상 기본 아님

v0.1.0부터 SDK는 기본적으로 Claude Code 시스템 프롬프트를 쓰지 않아요. 이전 동작을 원하면 claude_code 프리셋을 명시적으로 요청하거나 커스텀 프롬프트를 지정하세요.

// AFTER (v0.1.0) - Uses minimal system prompt by default
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"
  }
});

# AFTER (v0.1.0) - Uses minimal system prompt by default
async for message in query(
    prompt="Hello",
    options=ClaudeAgentOptions(
        system_prompt={"type": "preset", "preset": "claude_code"}  # Use the preset
    ),
):
    print(message)

설정 소스 기본값

설정 소스 기본은 v0.1.0에서 잠시 파일시스템 설정을 로드하지 않도록 바뀌었다가 되돌려졌어요. 현재 동작: query()에서 settingSources를 생략하면 CLI와 일치하게 사용자·프로젝트·로컬 파일시스템 설정(~/.claude/settings.json, .claude/settings.json, .claude/settings.local.json, CLAUDE.md, 커스텀 명령)을 로드해요. 파일시스템 설정에서 분리하려면 settingSources: [](Python setting_sources=[])를 넘기세요. CI/CD·배포 앱·테스트 환경·멀티테넌트 시스템에서 로컬 커스터마이징이 새지 않게 하는 데 특히 중요해요.

참고: Python SDK 0.1.59 이하는 빈 리스트를 옵션 생략과 동일하게 처리하므로 setting_sources=[]를 쓰려면 먼저 업그레이드하세요.

더 알아보기