Claude Agent SDK로 마이그레이션

개요

Claude Code SDK는 Claude Agent SDK로 이름이 변경되었으며 문서가 재구성되었습니다. 이 변경은 단순한 코딩 작업을 넘어 AI 에이전트를 구축하기 위한 SDK의 더 넓은 기능을 반영합니다.

변경 사항

마이그레이션 단계

TypeScript/JavaScript 프로젝트의 경우

1. 이전 패키지 제거:

npm uninstall @anthropic-ai/claude-code

2. 새 패키지 설치:

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

3. import 업데이트:

모든 import를 @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 의존성 업데이트:

package.json에 패키지가 나열되어 있다면 업데이트합니다:

// 이전
{
  "dependencies": {
    "@anthropic-ai/claude-code": "^1.0.0"
  }
}

// 이후
{
  "dependencies": {
    "@anthropic-ai/claude-agent-sdk": "^0.1.0"
  }
}

이것으로 끝입니다! 다른 코드 변경은 필요하지 않습니다.

Python 프로젝트의 경우

1. 이전 패키지 제거:

pip uninstall claude-code-sdk

2. 새 패키지 설치:

pip install claude-agent-sdk

3. import 업데이트:

모든 import를 claude_code_sdk에서 claude_agent_sdk로 변경합니다:

# 이전
from claude_code_sdk import query, ClaudeCodeOptions

# 이후
from claude_agent_sdk import query, ClaudeAgentOptions

4. 타입 이름 업데이트:

ClaudeCodeOptions를 ClaudeAgentOptions로 변경합니다:

# 이전
from claude_agent_sdk import query, ClaudeCodeOptions

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

# 이후
from claude_agent_sdk import query, ClaudeAgentOptions

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

5. 주요 변경 사항 검토

마이그레이션을 완료하는 데 필요한 코드 변경을 수행합니다.

주요 변경 사항

Python: ClaudeCodeOptions가 ClaudeAgentOptions로 이름 변경

변경 사항: Python SDK 타입 ClaudeCodeOptions가 ClaudeAgentOptions로 이름이 변경되었습니다.

마이그레이션:

# 이전 (v0.0.x)
from claude_agent_sdk import query, ClaudeCodeOptions

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

# 이후 (v0.1.0)
from claude_agent_sdk import query, ClaudeAgentOptions

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

변경 이유: 타입 이름이 이제 "Claude Agent SDK" 브랜딩과 일치하며 SDK의 명명 규칙 전반에 걸쳐 일관성을 제공합니다.

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

변경 사항: SDK가 더 이상 기본적으로 Claude Code의 시스템 프롬프트를 사용하지 않습니다.

마이그레이션:

// 이전 (v0.0.x) - 기본적으로 Claude Code의 시스템 프롬프트를 사용
const result = query({ prompt: "Hello" });

// 이후 (v0.1.0) - 기본적으로 최소한의 시스템 프롬프트를 사용
// 이전 동작을 유지하려면 Claude Code의 프리셋을 명시적으로 요청:
const result = query({
  prompt: "Hello",
  options: {
    systemPrompt: { type: "preset", preset: "claude_code" }
  }
});

// 또는 커스텀 시스템 프롬프트를 사용:
const result = query({
  prompt: "Hello",
  options: {
    systemPrompt: "You are a helpful coding assistant"
  }
});

변경 이유: SDK 애플리케이션에 대한 더 나은 제어와 격리를 제공합니다. 이제 Claude Code의 CLI 중심 지침을 상속받지 않고 커스텀 동작으로 에이전트를 구축할 수 있습니다.

설정 소스가 더 이상 기본적으로 로드되지 않음

변경 사항: SDK가 더 이상 기본적으로 파일 시스템 설정(CLAUDE.md, settings.json, 슬래시 명령 등)을 읽지 않습니다.

마이그레이션:

// 이전 (v0.0.x) - 모든 설정을 자동으로 로드
const result = query({ prompt: "Hello" });
// 다음에서 읽음:
// - ~/.claude/settings.json (사용자)
// - .claude/settings.json (프로젝트)
// - .claude/settings.local.json (로컬)
// - CLAUDE.md 파일
// - 커스텀 슬래시 명령

// 이후 (v0.1.0) - 기본적으로 설정이 로드되지 않음
// 이전 동작을 유지하려면:
const result = query({
  prompt: "Hello",
  options: {
    settingSources: ["user", "project", "local"]
  }
});

// 또는 특정 소스만 로드:
const result = query({
  prompt: "Hello",
  options: {
    settingSources: ["project"]  // 프로젝트 설정만
  }
});

변경 이유: SDK 애플리케이션이 로컬 파일 시스템 구성과 독립적으로 예측 가능한 동작을 보장합니다. 이는 특히 다음에 중요합니다:

• CI/CD 환경 - 로컬 커스터마이징 없이 일관된 동작
• 배포된 애플리케이션 - 파일 시스템 설정에 대한 의존성 없음
• 테스트 - 격리된 테스트 환경
• 멀티 테넌트 시스템 - 사용자 간 설정 누출 방지

이름 변경 이유

Claude Code SDK는 원래 코딩 작업을 위해 설계되었지만, 모든 유형의 AI 에이전트를 구축하기 위한 강력한 프레임워크로 발전했습니다. 새로운 이름 "Claude Agent SDK"는 그 기능을 더 잘 반영합니다:

• 비즈니스 에이전트 구축 (법률 어시스턴트, 금융 어드바이저, 고객 지원)
• 전문 코딩 에이전트 생성 (SRE 봇, 보안 리뷰어, 코드 리뷰 에이전트)
• 도구 사용, MCP 통합 등을 통한 모든 도메인의 커스텀 에이전트 개발

도움 받기

마이그레이션 중 문제가 발생하면:

TypeScript/JavaScript의 경우:

1. 모든 import가 @anthropic-ai/claude-agent-sdk를 사용하도록 업데이트되었는지 확인
2. package.json에 새 패키지 이름이 있는지 확인
3. npm install을 실행하여 의존성이 업데이트되었는지 확인

Python의 경우:

1. 모든 import가 claude_agent_sdk를 사용하도록 업데이트되었는지 확인
2. requirements.txt 또는 pyproject.toml에 새 패키지 이름이 있는지 확인
3. pip install claude-agent-sdk를 실행하여 패키지가 설치되었는지 확인

다음 단계

• Agent SDK 개요를 탐색하여 사용 가능한 기능에 대해 알아보기
• TypeScript SDK 레퍼런스에서 상세한 API 문서 확인
• Python SDK 레퍼런스에서 Python 관련 문서 검토
• 커스텀 도구 및 MCP 통합에 대해 알아보기