​
개요

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

​
변경 사항

측면이전새로운
패키지 이름 (TS/JS)@anthropic-ai/claude-code@anthropic-ai/claude-agent-sdk
Python 패키지claude-code-sdkclaude-agent-sdk
문서 위치Claude Code 문서 → SDK 섹션API 가이드 → Agent SDK 섹션
문서 변경사항: Agent SDK 문서는 Claude Code 문서에서 API 가이드의 전용 Agent SDK 섹션으로 이동했습니다. Claude Code 문서는 이제 CLI 도구와 자동화 기능에 중점을 둡니다.

​
마이그레이션 단계

​
TypeScript/JavaScript 프로젝트의 경우

1. 기존 패키지 제거: 
npm uninstall @anthropic-ai/claude-code
2. 새 패키지 설치: 
npm install @anthropic-ai/claude-agent-sdk
3. 임포트 업데이트: 모든 임포트를 @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. 임포트 업데이트: 모든 임포트를 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-sonnet-4-5"
)

# 이후
from claude_agent_sdk import query, ClaudeAgentOptions

options = ClaudeAgentOptions(
    model="claude-sonnet-4-5"
)
5. 주요 변경사항 검토 마이그레이션을 완료하기 위해 필요한 코드 변경사항을 적용하세요.

​
주요 변경사항

격리성과 명시적 구성을 개선하기 위해 Claude Agent SDK v0.1.0은 Claude Code SDK에서 마이그레이션하는 사용자에게 주요 변경사항을 도입합니다. 마이그레이션하기 전에 이 섹션을 주의 깊게 검토하세요.

​
Python: ClaudeCodeOptions가 ClaudeAgentOptions로 이름 변경

변경 내용: Python SDK 타입 ClaudeCodeOptions가 ClaudeAgentOptions로 이름이 변경되었습니다. 마이그레이션: 
# 이전 (v0.0.x)
from claude_agent_sdk import query, ClaudeCodeOptions

options = ClaudeCodeOptions(
    model="claude-sonnet-4-5",
    permission_mode="acceptEdits"
)

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

options = ClaudeAgentOptions(
    model="claude-sonnet-4-5",
    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.md 지침 등)에 의존했다면 옵션에 settingSources: ['user', 'project', 'local']을 추가하세요.

​
이름 변경 이유

Claude Code SDK는 원래 코딩 작업을 위해 설계되었지만, 모든 유형의 AI 에이전트를 구축하기 위한 강력한 프레임워크로 발전했습니다. 새로운 이름 “Claude Agent SDK”는 다음과 같은 기능을 더 잘 반영합니다:
  • 비즈니스 에이전트 구축(법률 어시스턴트, 금융 어드바이저, 고객 지원)
  • 전문 코딩 에이전트 생성(SRE 봇, 보안 검토자, 코드 리뷰 에이전트)
  • 도구 사용, MCP 통합 등을 통한 모든 도메인의 사용자 정의 에이전트 개발

​
도움 받기

마이그레이션 중 문제가 발생하면: TypeScript/JavaScript의 경우:
  1. 모든 임포트가 @anthropic-ai/claude-agent-sdk를 사용하도록 업데이트되었는지 확인
  2. package.json에 새 패키지 이름이 있는지 확인
  3. npm install을 실행하여 의존성이 업데이트되었는지 확인
Python의 경우:
  1. 모든 임포트가 claude_agent_sdk를 사용하도록 업데이트되었는지 확인
  2. requirements.txt 또는 pyproject.toml에 새 패키지 이름이 있는지 확인
  3. pip install claude-agent-sdk를 실행하여 패키지가 설치되었는지 확인
일반적인 문제는 문제 해결 가이드를 참조하세요.

​
다음 단계