Agent SDK 的价值在于它丰富的配置能力。ClaudeAgentOptions 是你定义 agent 行为、能力、安全限制和集成的地方——远超裸 Messages API 能提供的。
关键配置字段
system_prompt— 持久的行为指令。角色、语气、决策指导原则。它为 agent 的一切行为定调。allowed_tools— 可用工具的白名单。只有列出的工具对 agent 存在，其余在结构上不可用。permission_mode— 控制审批流程（default、acceptEdits、full、plan）。决定工具调用是否需要用户确认。max_turns— 限制推理-行动循环的最大次数。防止无限循环的安全机制。hooks— 工具调用和其他 agent 事件的事件处理器。mcp_servers— 外部 MCP server，提供额外的工具和数据源。
没有 auto_learn 字段。Agent 不会自己修改 prompt。改进需要开发者手动更新。
allowed_tools：白名单，不是黑名单
allowed_tools 是白名单机制：allowed_tools=["Read", "WebSearch"] 意味着这个 agent 只有 Read 和 WebSearch。Bash、Write、Edit——对这个 agent 都不存在。没有 blocked_tools 黑名单，没有逐工具的 tool_permissions 字典。你列出什么在里面，其余全在外面。
这是结构性约束。不管情况看起来多紧迫多巧妙，模型都无法使用不在列表上的工具。对比一下基于 prompt 的限制（“绝对不要用 Bash”），模型在某些条件下可能会忽略它。
allowed_tools vs permission_mode
它们控制不同的维度：
allowed_tools= 哪些工具存在（能力）。一个allowed_tools=["Read", "WebSearch"]的研究 agent，不管权限模式是什么都用不了 Bash。permission_mode= 工具调用怎么审批（监督）。一个全工具的 agent 配permission_mode="default"，有所有工具但每次使用都需要确认。
一个 agent 可以工具多但监督严（很多工具 + default 模式）。也可以工具少但无监督（少量工具 + full 模式）。两者是独立的控制。
实际配置
一个只该搜索和阅读的研究 agent：
options = ClaudeAgentOptions(
system_prompt="You are a research assistant...",
allowed_tools=["Read", "WebSearch"],
permission_mode="full",
max_turns=20
)这个 agent 可以自主搜索网页和读文件（full 模式），但不能执行 shell 命令或修改文件（不在 allowed_tools 里）。如果陷入循环，20 轮后停止。
一句话总结： ClaudeAgentOptions 通过 system_prompt 配置 agent 行为，通过白名单式的 allowed_tools 限制能力，通过 permission_mode 控制监督——工具访问的两个独立维度。