How anthropics/claude-code-sdk-python works
This is a Python SDK for running Claude Agent through the bundled or configured Claude Code CLI. The main workflow accepts a prompt through either the one-shot query API or an interactive client, configures the session, exchanges streaming messages over a transport, and yields parsed responses. Additional capabilities include in-process MCP tools, hooks and permission callbacks, plus session listing, mutation, import, resume, and pluggable storage. Edges reflect README statements or relationships named in the SOURCE INDEX; unsampled implementation details are not inferred.
Main entry points: _internal/client.py Query orchestration · query.py Query protocol · session_store.py Session store · claude_agent_sdk/client.py Interactive client
Components 21
SDK interfaces
- Public API
src/claude_agent_sdk/__init__.py - One-shot query
src/claude_agent_sdk/query.py - Interactive client
src/claude_agent_sdk/client.py
Agent runtime
- Query protocol
src/claude_agent_sdk/_internal/query.py - Query orchestration
src/claude_agent_sdk/_internal/client.py - Transport interface
src/claude_agent_sdk/_internal/transport/__init__.py - CLI subprocess
src/claude_agent_sdk/_internal/transport/subprocess_cli.py - Message parser
src/claude_agent_sdk/_internal/message_parser.py - SDK MCP bridge
src/claude_agent_sdk/_internal/sdk_mcp_bridge.py
Session lifecycle
- Session operations
src/claude_agent_sdk/_internal/sessions.py - Session import
src/claude_agent_sdk/_internal/session_import.py - Session mutations
src/claude_agent_sdk/_internal/session_mutations.py - Session resume
src/claude_agent_sdk/_internal/session_resume.py - Session store
src/claude_agent_sdk/_internal/session_store.py - Store validation
src/claude_agent_sdk/_internal/session_store_validation.py - Session summaries
src/claude_agent_sdk/_internal/session_summary.py - Transcript batcher
src/claude_agent_sdk/_internal/transcript_mirror_batcher.py
Types and errors
- SDK types
src/claude_agent_sdk/types.py - Error types
src/claude_agent_sdk/_errors.py
Other components
- SDK application
- Claude Code CLI
Connections 29
- SDK application → One-shot query: submits prompt
README.md - SDK application → Interactive client: starts conversation
README.md - Public API → One-shot query: exports
src/claude_agent_sdk/__init__.py - One-shot query → Query orchestration: delegates to
src/claude_agent_sdk/query.py - Interactive client → Query protocol: initializes
src/claude_agent_sdk/client.py - Interactive client → Session resume: uses for resume
src/claude_agent_sdk/client.py - Query orchestration → Query protocol: orchestrates
src/claude_agent_sdk/_internal/client.py - Query orchestration → Store validation: validates options
src/claude_agent_sdk/_internal/client.py - Query orchestration → Transport interface: selects transport
src/claude_agent_sdk/_internal/client.py - Query orchestration → Session resume: prepares resume
src/claude_agent_sdk/_internal/client.py - Query protocol → Transport interface: uses protocol
src/claude_agent_sdk/_internal/query.py - Query protocol → SDK MCP bridge: dispatches tools
src/claude_agent_sdk/_internal/query.py - Transport interface → CLI subprocess: implemented by
src/claude_agent_sdk/_internal/transport/subprocess_cli.py - CLI subprocess → Claude Code CLI: exchanges stream
src/claude_agent_sdk/_internal/transport/subprocess_cli.py - Interactive client → Message parser: uses parser
src/claude_agent_sdk/client.py - Session operations → Session store: loads sessions
src/claude_agent_sdk/_internal/sessions.py - Session operations → Session summaries: uses summaries
src/claude_agent_sdk/_internal/sessions.py - Session import → Session operations: uses session helpers
src/claude_agent_sdk/_internal/session_import.py - Session import → Transcript batcher: uses batcher
src/claude_agent_sdk/_internal/session_import.py - Session mutations → Session operations: uses session helpers
src/claude_agent_sdk/_internal/session_mutations.py - Session mutations → Store validation: checks store
src/claude_agent_sdk/_internal/session_mutations.py - Session resume → Session store: loads transcript
src/claude_agent_sdk/_internal/session_resume.py - Session resume → Transcript batcher: uses batcher
src/claude_agent_sdk/_internal/session_resume.py - Session store → Session summaries: derives metadata
src/claude_agent_sdk/_internal/session_store.py - Transcript batcher → Session store: writes batches
src/claude_agent_sdk/_internal/transcript_mirror_batcher.py - Public API → SDK types: exports types
src/claude_agent_sdk/__init__.py - Public API → Error types: exports errors
src/claude_agent_sdk/__init__.py - Session store → SDK types: implements contract
src/claude_agent_sdk/types.py - Query protocol → Error types: raises errors
src/claude_agent_sdk/_internal/query.py