Claude Agent SDK (Python)

它做什么

• query() 异步生成器 API——迭代消息流（AssistantTextMessage / ToolUseBlock / ToolResultBlock / ResultMessage）
• ClaudeAgentOptions 全字段：allowed_tools / permission_mode / cwd / model / hooks / mcp_servers / max_turns / max_budget_usd / fallback_model
• MCP server 接入（stdio + HTTP/SSE），与项目级 .mcp.json 自动合并
• hooks 系统——PreToolUse / PostToolUse / Stop / SubagentStop；配合 async 迭代做结构化 JSON 审计
• 由内置 Claude Code CLI 驱动——继承所有内置工具、上下文管理、权限模型

什么时候用

Python 生态生产级 agent 首选——CI 流水线、分流 bot、研究助手，用 asyncio.gather(*queries, return_exceptions=True) 跑多 agent 调研。与 FastAPI 配合做服务化，配任意 Python 队列做后台分发，现有 logging 栈接审计。TypeScript SDK 的 Python 对位。

如何上手

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

依赖 Python 3.10+、PATH 上的 Claude Code CLI、以及设好的 ANTHROPIC_API_KEY。SDK 内部驱动 CLI。

注意事项

生产请 pin 到 major 版本——SDK 的 Pydantic 模型在 minor 版本之间会变。生产务必设 max_turns 和 max_budget_usd。多 agent 扇出请用 asyncio.gather(*queries, return_exceptions=True)——直接对 asyncio.as_completed 用 async generator 会抛 TypeError。