Agent SDK Python 레퍼런스

공식 기준: https://code.claude.com/docs/en/agent-sdk/python

기준일: 2026-07-26 · CLI 기준 2.1.220

개요

Python Agent SDK의 함수·클래스·타입 레퍼런스입니다. 시스템 Python에 직접 pip install하면 externally-managed-environment 오류가 날 수 있으므로 venv를 사용하세요.

python3 -m venv .venv
source .venv/bin/activate
pip install claude-agent-sdk

서명 블록과 bare async for/async with는 예시입니다. async def main() + asyncio.run(main())으로 감싸 실행하세요.

핵심 개념

방식	query()	ClaudeSDKClient
세션	기본 새 세션	동일 세션 재사용
대화	단일 교환	다중 교환
연결	자동 관리	수동 제어
Streaming input	지원	지원
Interrupts	미지원	지원
Hooks / Custom tools	지원	지원
이어가기	continue_conversation/resume 수동	자동
용도	일회 작업	연속 대화·REPL

상세

query()

일회성/독립 작업용 async 이터레이터. prompt와 ClaudeAgentOptions를 받습니다.

tool()

커스텀 도구 정의 데코레이터/헬퍼. JSON schema와 핸들러를 묶어 MCP/SDK 도구로 노출합니다.

create_sdk_mcp_server()

프로세스 내 MCP 서버를 만들어 mcp_servers에 연결합니다.

세션 유틸

함수	역할
list_sessions()	저장된 세션 목록
get_session_messages()	세션 메시지 (compaction 이후 체인)
get_session_info()	메타데이터
rename_session() / tag_session()	이름·태그

ClaudeSDKClient

컨텍스트 매니저로 연결을 열고 query() / receive_response() / interrupt / rewind_files 등 연속 제어를 제공합니다. 대화 유지·응답 분기 로직·명시적 수명 관리에 적합합니다.

주요 타입

ClaudeAgentOptions

자주 쓰는 필드(개념):

• model, permission_mode, allowed_tools / tools
• system_prompt (문자열 | preset | file)
• setting_sources: "user" | "project" | "local" | []
• mcp_servers, plugins, agents, hooks
• cwd, resume, continue_conversation
• enable_file_checkpointing, extra_args
• env, max_turns, thinking/effort/budget 관련 설정

권한

• PermissionMode
• CanUseTool 콜백
• PermissionResult / Allow / Deny
• PermissionUpdate, PermissionRuleValue

MCP / 플러그인

• McpServerConfig, McpSdkServerConfig, status 타입
• SdkPluginConfig: { type: "local", path }

메시지

Message 유니온: Assistant, User, Result, System 등. 블록에 text / tool_use / tool_result가 포함됩니다.

기타

• SettingSource, AgentDefinition
• EffortLevel, ThinkingConfig, TaskBudget, SdkBeta
• OutputFormat, SystemPromptPreset, SystemPromptFile
• Transport 추상(커스텀 전송 시)

setting_sources 패턴

# 완전 프로그램 구성
ClaudeAgentOptions(setting_sources=[])

# 프로젝트 CLAUDE.md/skills만
ClaudeAgentOptions(setting_sources=["project"])

# CI에서 local 제외
ClaudeAgentOptions(setting_sources=["user", "project"])

managed policy·auto memory 등은 별도 제어가 필요합니다.

체크리스트

• venv에 claude-agent-sdk 설치
• 일회 vs 연속 대화에 맞는 API 선택
• 코딩 에이전트면 system_prompt preset 명시
• 멀티테넌트면 setting_sources=[] + env 격리
• 타입·메시지 유니온을 isinstance로 분기

다음 단계

• TypeScript 레퍼런스
• 마이그레이션
• 스트리밍 입력
• SDK 훅
• 전체 시그니처: https://code.claude.com/docs/en/agent-sdk/python