Claude Agent SDK

它做什么

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

什么时候用

最适合需要 Claude Code 循环以编程方式使用的生产级 agent——CI/CD 流水线、后台 worker、自定义应用、asyncio.gather 多 agent 编排。适合任何讲 async iterator 的 TypeScript 框架——SDK 是官方生产落点。

如何上手

npm install @anthropic-ai/claude-agent-sdk

依赖机器上 Claude Code CLI 在 PATH 中，且设好 ANTHROPIC_API_KEY（或等价 provider 环境变量）。SDK 内部驱动 CLI；两者缺一不可。

注意事项

生产请 pin 到 major 版本——SDK 的 TypeScript 类型在 minor 版本之间会变。长跑批量任务应用流式 async 迭代；sync 辅助会卡事件循环。生产环境务必设 max_turns 和 max_budget_usd。