通过创建一个自动查找并修复代码 Bug 的 Agent，演示从安装 SDK、配置 API Key，到编写并运行 Agent 的完整流程。核心用法是调用 query() 函数并传入 prompt 和选项，SDK 自动驱动 Agent 循环完成任务。
核心机制
query() 函数：主入口，返回 async iterator，通过 async for 流式接收消息。每条消息可能是 Claude 的推理文本、工具调用、工具结果或最终结果。
三个关键参数：
prompt：任务描述，Claude 据此决定使用哪些工具allowed_tools：预批准的工具列表，列出的工具无需用户确认permission_mode：控制未预批准工具的处理方式
Permission Mode 对照：
| 模式 | 行为 | 适用场景 |
|---|---|---|
acceptEdits | 自动批准文件编辑和常见文件系统命令 | 受信任的开发工作流 |
dontAsk | 拒绝 allowedTools 之外的所有工具 | 锁定的无头 Agent |
bypassPermissions | 运行所有工具无需提示 | 沙箱 CI 环境 |
default | 未匹配工具触发 canUseTool 回调 | 自定义审批流程 |
关键细节
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage
async for message in query(
prompt="Review utils.py for bugs that would cause crashes. Fix any issues you find.",
options=ClaudeAgentOptions(
allowed_tools=["Read", "Edit", "Glob"],
permission_mode="acceptEdits",
),
):
if isinstance(message, AssistantMessage):
for block in message.content:
if hasattr(block, "text"):
print(block.text)
elif isinstance(message, ResultMessage):
print(f"Done: {message.subtype}")工具组合参考：
- 只读分析：
["Read", "Glob", "Grep"] - 分析+修改：
["Read", "Edit", "Glob"] - 完整自动化：
["Read", "Edit", "Bash", "Glob", "Grep"]
常见错误：thinking.type.enabled 不支持 Opus 4.7，需升级 SDK 到 v0.2.111+。
与其他概念的关联
- overview - SDK 整体架构
- agent-loop - 消息流和循环机制
- permissions - 权限控制详解
- sessions - 多轮对话管理
实践要点
- TypeScript SDK 内置 Claude Code 二进制，无需单独安装 CLI
- 第三方 API 提供商（Bedrock/Vertex/Azure）通过环境变量切换，代码无需修改
- 不需要实时输出时（如 CI 管道），可收集所有消息后统一处理，参考 streaming-vs-single-mode
system_prompt可注入角色指令，max_turns可限制循环轮次防止失控