Claude Agent SDK (Python)

What it does

• query() async-generator API — iterate the message stream (AssistantTextMessage / ToolUseBlock / ToolResultBlock / ResultMessage)
• ClaudeAgentOptions: allowed_tools / permission_mode / cwd / model / hooks / mcp_servers / max_turns / max_budget_usd / fallback_model
• MCP server wiring (stdio + HTTP/SSE) merged with project-level .mcp.json
• Hooks system — PreToolUse / PostToolUse / Stop / SubagentStop; structured JSON audit logging via async iteration
• Driven by the bundled Claude Code CLI — inherits all built-in tools, context management, and permission model

When to use it

Best for Python production agents — CI pipelines, triage bots, research assistants, multi-agent research with asyncio.gather(*queries, return_exceptions=True). Pairs with FastAPI for serving, any Python queue for background dispatch, and existing logging stacks for audit. The Python companion to the TypeScript SDK.

Getting started

pip install claude-agent-sdk
# or
uv add claude-agent-sdk

Requires Python 3.10+, the Claude Code CLI on PATH, and ANTHROPIC_API_KEY set. The SDK runs the CLI under the hood.

Things to know

Pin to a major version — the SDK's Pydantic models evolve between minor releases. Always set max_turns and max_budget_usd in production. For multi-agent fan-out, prefer asyncio.gather(*queries, return_exceptions=True) — using asyncio.as_completed directly on async generators will raise TypeError.