Claude Code SDK
Claude Code SDK로 맞춤형 AI 에이전트 구축하기
Claude Code SDK를 사용하는 이유는?
Claude Code SDK는 프로덕션 준비 에이전트를 구축하는 데 필요한 모든 구성 요소를 제공합니다:
- 최적화된 Claude 통합: 자동 프롬프트 캐싱 및 성능 최적화
- 풍부한 도구 생태계: 파일 작업, 코드 실행, 웹 검색 및 MCP 확장성
- 고급 권한: 에이전트 기능에 대한 세밀한 제어
- 프로덕션 필수 요소: 내장된 오류 처리, 세션 관리 및 모니터링
SDK로 무엇을 구축할 수 있나요?
다음은 생성할 수 있는 에이전트 유형의 예시입니다:
코딩 에이전트:
- 프로덕션 문제를 진단하고 수정하는 SRE 에이전트
- 코드의 취약점을 감사하는 보안 검토 봇
- 인시던트를 분류하는 온콜 엔지니어링 어시스턴트
- 스타일과 모범 사례를 적용하는 코드 검토 에이전트
비즈니스 에이전트:
- 계약서와 규정 준수를 검토하는 법무 어시스턴트
- 보고서와 예측을 분석하는 재무 어드바이저
- 기술적 문제를 해결하는 고객 지원 에이전트
- 마케팅 팀을 위한 콘텐츠 제작 어시스턴트
SDK는 현재 TypeScript와 Python에서 사용할 수 있으며, 빠른 프로토타이핑을 위한 명령줄 인터페이스(CLI)를 제공합니다.
빠른 시작
5분 안에 첫 번째 에이전트를 실행해보세요:
SDK 설치
NPM에서 @anthropic-ai/claude-code
를 설치하세요:
NPM에서 @anthropic-ai/claude-code
를 설치하세요:
NPM에서 @anthropic-ai/claude-code
를 설치하세요:
PyPI에서 claude-code-sdk
와 NPM에서 @anthropic-ai/claude-code
를 설치하세요:
(선택사항) 대화형 개발을 위해 IPython을 설치하세요:
API 키 설정
Anthropic Console에서 API 키를 받고 ANTHROPIC_API_KEY
환경 변수를 설정하세요:
첫 번째 에이전트 생성
다음 예시 에이전트 중 하나를 생성하세요:
에이전트 실행
위의 명령을 터미널에 직접 복사하여 붙여넣으세요.
위의 명령을 터미널에 직접 복사하여 붙여넣으세요.
- 프로젝트 설정:
-
package.json에
"type": "module"
을 추가하세요 -
위의 코드를
legal-agent.ts
로 저장한 후 실행하세요:
위의 각 예시는 다음과 같은 작업을 수행하는 작동하는 에이전트를 생성합니다:
- Claude의 추론 능력을 사용하여 프롬프트 분석
- 문제를 해결하기 위한 다단계 접근법 계획
- 파일 작업, bash 명령, 웹 검색과 같은 도구를 사용하여 작업 실행
- 분석을 바탕으로 실행 가능한 권장 사항 제공
핵심 사용법
개요
Claude Code SDK를 사용하면 애플리케이션에서 비대화형 모드로 Claude Code와 인터페이스할 수 있습니다.
전제 조건
- Node.js 18+
- NPM의
@anthropic-ai/claude-code
기본 사용법
Claude Code의 주요 명령줄 인터페이스는 claude
명령입니다. --print
(또는 -p
) 플래그를 사용하여 비대화형 모드로 실행하고 최종 결과를 출력하세요:
구성
SDK는 Claude Code에서 사용할 수 있는 모든 CLI 옵션을 활용합니다. SDK 사용을 위한 주요 옵션은 다음과 같습니다:
플래그 | 설명 | 예시 |
---|---|---|
--print , -p | 비대화형 모드로 실행 | claude -p "쿼리" |
--output-format | 출력 형식 지정 (text , json , stream-json ) | claude -p --output-format json |
--resume , -r | 세션 ID로 대화 재개 | claude --resume abc123 |
--continue , -c | 가장 최근 대화 계속 | claude --continue |
--verbose | 자세한 로깅 활성화 | claude --verbose |
--append-system-prompt | 시스템 프롬프트에 추가 (--print 와 함께만 사용) | claude --append-system-prompt "사용자 지정 지침" |
--allowedTools | 허용된 도구의 공백으로 구분된 목록, 또는 쉼표로 구분된 허용된 도구의 문자열 목록 | claude --allowedTools mcp__slack mcp__filesystem claude --allowedTools "Bash(npm install),mcp__filesystem" |
--disallowedTools | 거부된 도구의 공백으로 구분된 목록, 또는 쉼표로 구분된 거부된 도구의 문자열 목록 | claude --disallowedTools mcp__splunk mcp__github claude --disallowedTools "Bash(git commit),mcp__github" |
--mcp-config | JSON 파일에서 MCP 서버 로드 | claude --mcp-config servers.json |
--permission-prompt-tool | 권한 프롬프트 처리를 위한 MCP 도구 (--print 와 함께만 사용) | claude --permission-prompt-tool mcp__auth__prompt |
CLI 옵션과 기능의 전체 목록은 CLI 참조 문서를 참조하세요.
전제 조건
- Node.js 18+
- NPM의
@anthropic-ai/claude-code
기본 사용법
Claude Code의 주요 명령줄 인터페이스는 claude
명령입니다. --print
(또는 -p
) 플래그를 사용하여 비대화형 모드로 실행하고 최종 결과를 출력하세요:
구성
SDK는 Claude Code에서 사용할 수 있는 모든 CLI 옵션을 활용합니다. SDK 사용을 위한 주요 옵션은 다음과 같습니다:
플래그 | 설명 | 예시 |
---|---|---|
--print , -p | 비대화형 모드로 실행 | claude -p "쿼리" |
--output-format | 출력 형식 지정 (text , json , stream-json ) | claude -p --output-format json |
--resume , -r | 세션 ID로 대화 재개 | claude --resume abc123 |
--continue , -c | 가장 최근 대화 계속 | claude --continue |
--verbose | 자세한 로깅 활성화 | claude --verbose |
--append-system-prompt | 시스템 프롬프트에 추가 (--print 와 함께만 사용) | claude --append-system-prompt "사용자 지정 지침" |
--allowedTools | 허용된 도구의 공백으로 구분된 목록, 또는 쉼표로 구분된 허용된 도구의 문자열 목록 | claude --allowedTools mcp__slack mcp__filesystem claude --allowedTools "Bash(npm install),mcp__filesystem" |
--disallowedTools | 거부된 도구의 공백으로 구분된 목록, 또는 쉼표로 구분된 거부된 도구의 문자열 목록 | claude --disallowedTools mcp__splunk mcp__github claude --disallowedTools "Bash(git commit),mcp__github" |
--mcp-config | JSON 파일에서 MCP 서버 로드 | claude --mcp-config servers.json |
--permission-prompt-tool | 권한 프롬프트 처리를 위한 MCP 도구 (--print 와 함께만 사용) | claude --permission-prompt-tool mcp__auth__prompt |
CLI 옵션과 기능의 전체 목록은 CLI 참조 문서를 참조하세요.
전제 조건
- Node.js 18+
- NPM의
@anthropic-ai/claude-code
TypeScript SDK 소스 코드를 보려면 NPM의 @anthropic-ai/claude-code
페이지를 방문하세요.
기본 사용법
TypeScript SDK를 통한 주요 인터페이스는 query
함수로, 메시지가 도착하는 대로 스트리밍하는 비동기 반복자를 반환합니다:
구성
TypeScript SDK는 명령줄에서 지원하는 모든 인수와 다음 추가 옵션을 허용합니다:
인수 | 설명 | 기본값 |
---|---|---|
abortController | 중단 컨트롤러 | new AbortController() |
cwd | 현재 작업 디렉토리 | process.cwd() |
executable | 사용할 JavaScript 런타임 | Node.js로 실행할 때 node , Bun으로 실행할 때 bun |
executableArgs | 실행 파일에 전달할 인수 | [] |
pathToClaudeCodeExecutable | Claude Code 실행 파일 경로 | @anthropic-ai/claude-code 와 함께 제공되는 실행 파일 |
permissionMode | 세션의 권한 모드 | "default" (옵션: "default" , "acceptEdits" , "plan" , "bypassPermissions" ) |
전제 조건
- Python 3.10+
- PyPI의
claude-code-sdk
- Node.js 18+
- NPM의
@anthropic-ai/claude-code
Python SDK 소스 코드를 보려면 claude-code-sdk
저장소를 참조하세요.
대화형 개발을 위해 IPython을 사용하세요: pip install ipython
기본 사용법
Python SDK는 두 가지 주요 인터페이스를 제공합니다:
ClaudeSDKClient
클래스 (권장)
스트리밍 응답, 다중 턴 대화 및 대화형 애플리케이션에 최적:
SDK는 구조화된 메시지와 이미지 입력 전달도 지원합니다:
이 페이지의 Python 예시는 asyncio
를 사용하지만 anyio
도 사용할 수 있습니다.
query
함수
간단한 일회성 쿼리용:
구성
Python SDK는 ClaudeCodeOptions
클래스를 통해 명령줄에서 지원하는 모든 인수를 허용합니다.
인증
Anthropic API 키
기본 인증의 경우 Anthropic Console에서 Anthropic API 키를 검색하고 빠른 시작에서 설명한 대로 ANTHROPIC_API_KEY
환경 변수를 설정하세요.
타사 API 자격 증명
SDK는 타사 API 제공업체를 통한 인증도 지원합니다:
- Amazon Bedrock:
CLAUDE_CODE_USE_BEDROCK=1
환경 변수를 설정하고 AWS 자격 증명을 구성하세요 - Google Vertex AI:
CLAUDE_CODE_USE_VERTEX=1
환경 변수를 설정하고 Google Cloud 자격 증명을 구성하세요
타사 제공업체에 대한 자세한 구성 지침은 Amazon Bedrock 및 Google Vertex AI 문서를 참조하세요.
다중 턴 대화
다중 턴 대화의 경우 대화를 재개하거나 가장 최근 세션에서 계속할 수 있습니다:
계획 모드 사용
계획 모드를 사용하면 Claude가 수정 없이 코드를 분석할 수 있어 코드 검토 및 변경 계획에 유용합니다.
계획 모드는 편집, 파일 생성 및 명령 실행을 제한합니다. 자세한 내용은 권한 모드를 참조하세요.
사용자 정의 시스템 프롬프트
시스템 프롬프트는 에이전트의 역할, 전문성 및 행동을 정의합니다. 여기서 구축하고 있는 에이전트의 종류를 지정합니다:
고급 사용법
MCP를 통한 사용자 정의 도구
Model Context Protocol(MCP)을 사용하면 에이전트에게 사용자 정의 도구와 기능을 제공할 수 있습니다. 이는 도메인별 통합이 필요한 전문 에이전트를 구축하는 데 중요합니다.
예시 에이전트 도구 구성:
사용 예시:
MCP 도구를 사용할 때는 --allowedTools
플래그를 사용하여 명시적으로 허용해야 합니다. MCP 도구 이름은 mcp__<serverName>__<toolName>
패턴을 따릅니다. 여기서:
serverName
은 MCP 구성 파일의 키입니다toolName
은 해당 서버에서 제공하는 특정 도구입니다
이 보안 조치는 MCP 도구가 명시적으로 허용된 경우에만 사용되도록 보장합니다.
서버 이름만 지정하면(즉, mcp__<serverName>
), 해당 서버의 모든 도구가 허용됩니다.
글로브 패턴(예: mcp__go*
)은 지원되지 않습니다.
사용자 정의 권한 프롬프트 도구
선택적으로 --permission-prompt-tool
을 사용하여 사용자가 모델에 특정 도구 호출 권한을 부여하는지 확인하는 데 사용할 MCP 도구를 전달할 수 있습니다. 모델이 도구를 호출할 때 다음과 같은 일이 발생합니다:
- 먼저 권한 설정을 확인합니다: 모든 settings.json 파일과 SDK에 전달된
--allowedTools
및--disallowedTools
; 이 중 하나가 도구 호출을 허용하거나 거부하면 도구 호출을 진행합니다 - 그렇지 않으면
--permission-prompt-tool
에서 제공한 MCP 도구를 호출합니다
--permission-prompt-tool
MCP 도구는 도구 이름과 입력을 전달받고 결과와 함께 JSON 문자열화된 페이로드를 반환해야 합니다. 페이로드는 다음 중 하나여야 합니다:
구현 예시:
사용 참고사항:
updatedInput
을 사용하여 권한 프롬프트가 입력을 변경했음을 모델에 알리세요. 그렇지 않으면 위 예시와 같이updatedInput
을 원래 입력으로 설정하세요. 예를 들어, 도구가 사용자에게 파일 편집 차이를 보여주고 사용자가 차이를 수동으로 편집할 수 있게 하는 경우, 권한 프롬프트 도구는 업데이트된 편집을 반환해야 합니다.- 페이로드는 JSON 문자열화되어야 합니다
출력 형식
SDK는 여러 출력 형식을 지원합니다:
텍스트 출력 (기본값)
JSON 출력
메타데이터를 포함한 구조화된 데이터를 반환합니다:
응답 형식:
스트리밍 JSON 출력
수신되는 각 메시지를 스트리밍합니다:
각 대화는 초기 init
시스템 메시지로 시작하고, 사용자 및 어시스턴트 메시지 목록이 이어지며, 통계가 포함된 최종 result
시스템 메시지로 끝납니다. 각 메시지는 별도의 JSON 객체로 방출됩니다.
메시지 스키마
JSON API에서 반환되는 메시지는 다음 스키마에 따라 엄격하게 타입이 지정됩니다:
곧 이러한 타입을 JSONSchema 호환 형식으로 게시할 예정입니다. 이 형식에 대한 주요 변경 사항을 전달하기 위해 주요 Claude Code 패키지에 대해 시맨틱 버전 관리를 사용합니다.
Message
및 MessageParam
타입은 Anthropic SDK에서 사용할 수 있습니다. 예를 들어, Anthropic TypeScript 및 Python SDK를 참조하세요.
입력 형식
SDK는 여러 입력 형식을 지원합니다:
텍스트 입력 (기본값)
스트리밍 JSON 입력
각 메시지가 사용자 턴을 나타내는 stdin
을 통해 제공되는 메시지 스트림입니다. 이를 통해 claude
바이너리를 다시 실행하지 않고도 대화의 여러 턴을 수행할 수 있으며, 모델이 요청을 처리하는 동안 지침을 제공할 수 있습니다.
각 메시지는 출력 메시지 스키마와 동일한 형식을 따르는 JSON ‘사용자 메시지’ 객체입니다. 메시지는 각 입력 줄이 완전한 JSON 객체인 jsonl 형식을 사용하여 형식화됩니다. 스트리밍 JSON 입력에는 -p
와 --output-format stream-json
이 필요합니다.
현재 이는 텍스트 전용 사용자 메시지로 제한됩니다.
에이전트 통합 예시
SRE 인시던트 대응 봇
자동화된 보안 검토
다중 턴 법무 어시스턴트
Python 전용 모범 사례
주요 패턴
IPython/Jupyter 팁
모범 사례
-
프로그래밍 방식의 응답 파싱을 위해 JSON 출력 형식 사용:
-
오류를 우아하게 처리 - 종료 코드와 stderr 확인:
-
다중 턴 대화에서 컨텍스트를 유지하기 위해 세션 관리 사용
-
장시간 실행되는 작업에 대해 타임아웃 고려:
-
여러 요청을 할 때 호출 사이에 지연을 추가하여 속도 제한 준수
관련 리소스
- CLI 사용법 및 제어 - 완전한 CLI 문서
- GitHub Actions 통합 - Claude로 GitHub 워크플로우 자동화
- 일반적인 워크플로우 - 일반적인 사용 사례에 대한 단계별 가이드