如何构建 AI Agent：从任务契约到故障恢复

构建 AI Agent，核心并不是把提示词写得更长，而是搭出一套可控的执行系统：定义结果，让模型在权限边界内使用工具和状态，再用评估、追踪与恢复机制约束每一次行动。

本文按真实工程生命周期展开，不绑定某个模型或框架，也不会一开始就画多 Agent 架构图。Anthropic 在构建有效 Agent 的官方工程总结中建议先使用能够解决问题的最简单方案，因为自治能力会用更高的成本、延迟与不确定性换取灵活性。

核验日期：2026 年 10 月 13 日。 框架 API 与模型名称变化很快，下面的构建顺序有意保持厂商中立；具体工具、Tracing 与部署语法应以所选框架的当前文档为准。

先确认你要构建的真是 Agent

Agent 由模型在循环中选择并调用工具，从环境获取结果、调整计划，直到完成目标或碰到控制边界。若每一步都由代码预先规定，它更接近工作流。

支持工具调用，不等于必须上 Agent。先用评估证明单次调用或固定工作流达不到质量目标，再增加自治。若你还在判断一项重复工作是否值得自动化，可先看如何为重复工作构建 AI Agent；本文从“确实需要 Agent”之后开始。

第一步：写任务契约

选模型之前，先写一页纸：

• **触发方式：**谁或什么启动任务？
• **输入：**必须提供哪些字段、文件和身份？
• **结果：**什么成果或外部状态变化才算完成？
• **允许读取：**可以访问哪些系统和资料？
• **允许行动：**可以调用哪些工具，权限范围多大？
• **证据：**结果必须附带哪些来源或运行证据？
• **审批：**哪些操作必须由人确认？
• **停止条件：**成功、阻塞、轮数、时长与预算上限分别是什么？
• **非目标：**哪些要求必须拒绝或升级给人？

“研究这家公司”无法验收；“仅使用指定的五个资料库生成带来源的风险备忘录，不得联系外部人员；每项结论必须有出处或标为未知”才是可测试的任务。

同时定义成功单位，例如备忘录被审核接受、代码补丁通过测试，或 CRM 草稿无需修改即可批准。不要拿回答长度、工具调用次数一类替代指标当成结果。

第二步：先设计执行循环，再选框架

最小循环并不复杂：

1. 读取任务、政策与当前状态；
2. 让模型返回结构化结果或工具请求；
3. 按数据结构和政策校验请求；
4. 在正确的执行环境里调用工具；
5. 写入观察结果和状态变化；
6. 完成、暂停审批，或在上限内继续。

确定性的工作应留在代码里：身份认证、权限判断、结构校验、计算、重试、幂等和政策执行，都不该让模型临场决定。模型更适合处理解释、规划、检索策略、分类和综合判断。

框架可以提供持久化执行、流式事件、检查点和人工中断。例如 LangGraph 将持久化执行与人在环中列为核心编排能力。但框架不会替你定义任务，也不会把危险工具自动变安全。提示词、工具结构、政策和评估应保持可检查、可迁移。

第三步：用评估选模型，不看排行榜下结论

建立基线时可以先用能力较强的模型，再让更小、更快的模型跑同一批案例。测试与你任务直接相关的能力：工具选择与参数、冲突指令遵循、长上下文检索、来源标注、工具报错恢复、结构化输出，以及每个被接受结果的延迟和完整成本。

只有当路由规则本身可评估时，才按任务难度切换模型。每增加一层路由，也增加一个故障点。供应商支持时应固定模型版本；每次运行记录实际版本；升级前重跑回归案例。

第四步：把工具当作安全与可靠性接口

工具名称、描述和参数就是 Agent 与计算机之间的接口。每个工具应只完成一项明确工作，使用收窄的数据结构，返回可预测的错误，并提供下一步判断需要的事实。

例如，用 search_orders(customer_id, date_range)，不要直接开放任意数据库查询；早期上线只提供 create_email_draft(...)，不要直接开放发送；退款先生成提案，再由审批步骤实际执行。

三个窄工具能完成任务时，不要开放通用 Shell、完整浏览器会话或权限宽泛的云凭证。网页、邮件、上传文件和工具返回值都属于不可信数据，其中可能夹带与系统政策冲突的指令。

第五步：分开管理上下文、状态与记忆

• 上下文是模型为当前决策看到的内容：指令、近期消息、检索资料和工具结果。
• 状态是机器认可的权威记录：任务阶段、已完成步骤、审批、外部 ID、重试和检查点。
• 记忆是有意保留、准备影响未来运行的信息：偏好、历史结果或可复用事实。

不要把聊天记录当成状态数据库。事实存入结构化字段，成果放入持久存储，大型资料用稳定标识引用，只在当前步骤需要时检索。Anthropic 的上下文工程指南强调用文件路径、查询和链接等轻量引用进行即时检索，而不是预先把所有内容塞入上下文。

记忆还需要写入政策：允许保存什么、谁能查看和删除、何时过期、事实冲突时如何处理。向量数据库只是检索机制，不是真相数据库。

第六步：让运行时负责权限和审批

不要询问模型“你是否有权执行”。权限必须由运行时判断。

OpenAI 官方的 Agent 安全指南把不可信输入和工具调用视为重要控制点。护栏不能替代认证、授权和常规软件安全。

审批界面必须展示具体操作、目标、参数、依据和预期副作用。只放一个“同意”按钮不叫有效监督。审批结果要进入持久状态，恢复运行后不能被重新解释。

第七步：在扩大部署前建立评估集

Agent 评估不能只看最终回答，还要检查完整执行轨迹。Anthropic 的Agent 评估工程指南建议对多轮系统同时验证结果与过程。

初始数据集至少包含四类：正常任务；输入缺失、过期或冲突的边界案例；提示词注入、越权请求等对抗案例；以及超时、工具返回格式错误、事件重复、凭证过期等恢复案例。

评估结果正确性、证据质量、禁止操作率、工具选择与参数准确性、多余步骤、延迟、成本、停止与升级行为，以及恢复时能否避免重复副作用。

能用确定性检查就不要交给主观判断，例如结构校验、数据库断言、测试套件、差异检查和政策谓词。无法规则化的质量再交给人工或经过校准的模型评分。分数变化时必须查看轨迹，因为正确结果也可能由危险过程产生。

第八步：让每次运行都可观测

一条生产追踪应串起任务与用户身份，模型、提示词、政策和工具版本，检索来源，模型回复与工具请求，脱敏后的工具输入输出，状态变化、审批、重试、检查点，token、延迟、成本、最终状态，以及外部副作用的唯一 ID。

日志中不要保存密钥或无必要的个人数据。使用结构化事件、关联 ID、访问控制和保留期限。告警应覆盖循环触顶、工具连续报错、审批积压、政策拒绝、成本异常和任务成功率下降，而不只是 HTTP 错误。

值班人员必须能够回答：Agent 当时知道什么？尝试了什么？外部状态改变了吗？现在能安全重试吗？

第九步：分阶段部署

按风险逐级开放：

1. **离线评估：**使用模拟工具或沙箱。
2. **历史回放：**用旧任务和冻结的外部状态运行。
3. **影子模式：**接收真实输入，但不执行外部写入。
4. **草稿模式：**所有成果必须经人审核。
5. **有限写入：**只对小范围用户开放可逆操作。
6. **扩大运行：**质量门槛和回滚演练通过后再放量。

对轮数、耗时、模型费用、工具调用、检索数据量和并发运行设置硬上限。开发、测试、生产凭证必须分离。通过功能开关和总开关停止新任务，同时保留恢复所需证据。

部署还必须明确责任人：谁处理告警、批准变更、轮换凭证、审查评估结果，以及决定何时停用 Agent？

第十步：在故障发生前设计恢复

Agent 经常停在半完成状态：消息可能已发送，但调用方超时；付款接口可能成功，但检查点还没写入；审批通过后，提案可能在真正执行前已经过期。

恢复机制包括持久检查点、为有副作用的工具设置幂等键、按错误类型制定重试与退避、与外部事实源对账、为可逆变更提供补偿操作、把无法自动处理的任务放入阻塞队列，以及恢复时保留原始政策和审批上下文。

在每一次写入前后主动中断运行，测试系统能否判断副作用是否已经发生。做不到这一点，就不适合无人值守执行。

上线前检查清单

• 结果可测试吗？非目标是否写清？
• 更简单的工作流是否确实无法通过同一套评估？
• 工具是否收窄、校验、限制权限并支持幂等？
• 上下文、状态和记忆是否分开？
• 高影响操作是否需要知情审批？
• 评估集是否覆盖对抗与恢复案例？
• 运维人员能否追踪来源、决策、审批和副作用？
• 运行能否安全暂停、恢复、重试、对账和终止？
• 模型、提示词、政策和工具变更是否有版本与回归测试？
• 是否明确责任人、预算、回滚方案和总开关？

如果多项答案是否定的，下一步不是再改一版提示词，而是补齐模型外部的控制系统。

构建你真正能运营的最小 Agent

Agent 的核心代码可能只是一个短循环，真正让它进入生产的是周围的任务契约、窄工具、持久状态、最小权限、评估、追踪、分阶段部署和恢复机制。

先做单 Agent、单一明确成果。只有评估证明路由、多 Agent 或长期记忆能提高可接受结果时，才增加复杂度。若你正在代码和可视化工具之间选择，可参考无代码 AI Agent 构建器指南；若任务更适合放在持续工作的项目环境中，可继续比较工作流构建器与 AI 工作区。