定制 AI Agent 开发：从需求、架构到验收交付

定制 AI Agent 开发不是“给应用接一个模型”，而是设计一套能够理解任务、选择工具、读取或修改状态，并在明确边界内决定下一步的软件系统。模型很重要，身份、权限、工具契约、评测、可观测性和故障恢复同样重要。

因此，采购问题也要换一种问法。在讨论框架和模型之前，先判断这项工作是否真的需要由模型自主选择动作；然后把业务流程写成可以测试的需求合同。一个合格的定制 Agent，不靠演示时有多惊艳来定义，而靠它能完成哪些工作、不能执行哪些动作、失败如何暴露，以及交接时所有者真正拿到什么来定义。

开发前先明确产品与工程规格：需要构建什么，以及怎样判断已经可以交付。如果你正在比较开发公司、自由职业者、合同结构或付费试点，请看配套的 AI Agent 开发服务采购指南。

先判断这项工作是否需要 Agent

Anthropic 区分了两类系统：工作流由代码预先决定执行路径；Agent由模型动态决定处理过程和工具使用。其建议很克制：先采用能够解决问题的最简单方案，因为 Agent 的灵活性通常会增加成本和延迟（Anthropic《Building effective agents》）。

以下情况更适合确定性工作流：

• 输入和有效状态已知；
• 路由可以用规则描述；
• 异常有限且能够枚举；
• 每次都应按相同步骤运行；
• 脚本、表单或自动化已经能生成所需结果。

以下情况才值得考虑 Agent：

• 请求以多种非结构化形式到达；
• 系统需要先检查证据，再选择工具或下一步；
• 工具返回结果会改变计划；
• 无法以合理成本把异常写成决策树；
• 停止、追问或升级给人本身就是正确行为。

使用 LLM 不代表系统就是 Agent。把支持工单分类并返回标签，可能需要模型，但不需要自主选工具；调查问题、读取账号历史、选择处理办法、起草回复，并在修改记录前请求批准，则是 Agent 式工作。

最有用的开工前问题是：**这里有什么决策必须交给模型，而不应该交给普通软件？**如果回答不清楚，先做工作流原型，不要直接采购生产级 Agent。

写需求合同，不要写功能愿望清单

“做一个处理客户运营的 Agent”无法直接实施。一份合格的需求合同，应让业务负责人、工程师、安全审查者和评测人员看到的是同一套系统。

描述结果，而不是描述界面动作。“打开 CRM 更新商机”是一段操作过程；“经过批准的商机记录包含已核验的会议结论，留下可归因的审计记录，且没有修改账单字段”才是可以测试的结果。

还要写负面要求：Agent 不得编造缺失字段，不得执行不可信文档中的指令，不得未经批准外发，不得无限重试写操作。这些约束随后会变成硬策略和评测用例。

生产架构不只有一个模型

架构评审至少应展示八层：

1. 任务入口：请求从哪里进入，如何确认身份。
2. 编排器或 Harness：提供上下文、路由工具调用、限制循环并返回结果。
3. 模型策略：模型选择、提示词、推理强度、降级和版本控制。
4. 工具层：搜索、检索、计算与动作的窄接口。
5. 状态层：运行状态、业务记录、经批准的长期记忆和检查点。
6. 策略层：认证、授权、输入验证、审批和硬性禁止。
7. 评测与可观测性：轨迹、结果检查、成本、延迟、告警和复核队列。
8. 执行边界：沙箱、网络规则、密钥、部署环境和恢复方式。

框架可以提供部分 Harness，但框架名称不是架构。需要问清框架下面哪些资产仍然可见、可导出：提示词、工具 schema、运行轨迹、评测夹具、状态和策略决策。Anthropic 指出，框架可以加速搭建，也可能用抽象层遮住提示词和响应，使错误假设更难调试（Anthropic 架构建议）。

默认先做单 Agent。只有评测证明增加专用 Agent 确实改善结果，才引入多 Agent。更多 Agent 会带来更多交接、重复上下文、协调失败、延迟和需要解释的轨迹。

工具是契约，不只是连接器

Agent 只能通过获得的接口行动。每个工具都需要：

• 单一、清晰的用途和精确输入 schema；
• 完成任务所需的最少数据与动作；
• 与服务身份或用户身份绑定的认证；
• 服务端对危险参数的校验；
• 超时、限流和重试行为；
• 对可能重复的写操作提供幂等性；
• 明确的结果结构，包括部分失败；
• 用于评测的测试替身或沙箱。

读取工具和写入工具必须分开。“CRM 权限”过于宽泛；读取账号、起草备注、应用已批准备注、改变负责人、发放退款应该是不同能力。退款上限、允许的收件域名、禁止访问的目录等硬限制，应由应用代码执行，而不是依赖自然语言提示词。

工具描述本身也会影响 Agent 表现。Anthropic 的工具工程指南建议测试 Agent 是否理解每个工具的用途和正确用法，而不能只验证底层 API 能否调用（Anthropic《Writing effective tools for agents》）。

分开运行状态、业务状态和记忆

“Agent 需要记忆”不足以指导设计。

• 运行状态记录单次任务的进度：已完成步骤、工具结果、审批和检查点。
• 业务状态存在于事实来源系统：工单、订单、文档或代码分支。
• 长期记忆跨运行保存经过选择的信息：偏好、已确认约定或学到的事实。

三者的所有者与保留周期不同。运行状态应支持恢复而不重复副作用；业务状态只能通过经过验证的工具改变；长期记忆需要来源、纠错、删除和过期规则。运行记录适合审计和调试，但不能悄悄变成可信记忆。

优先从事实来源检索，而不是把所有事实复制到记忆库。如果权威值已经存在于 CRM 或政策库，就在任务运行时读取。只有明确知道由谁负责、为什么需要跨运行保存，才应持久化。

权限与安全本来就是产品功能

Agent 风险既取决于模型能推断什么，也取决于系统允许它做什么。NIST 的生成式 AI Profile 用 govern、map、measure、manage 组织全生命周期风险工作，适合用来指派负责人和记录控制（NIST AI 600-1）。

建立动作—权限矩阵：

OpenAI 的业务指南也建议限制数据源、现实动作前确认、拒绝高风险操作、抵抗恶意提示并保留审计轨迹（OpenAI Agent 业务指南）。

测试检索页面与文件中的提示注入、恶意工具返回、数据外泄、提权和绕过审批。环境和凭据要分离，密钥不能写进提示词或日志。涉及监管或敏感数据时，应由业务负责人、隐私、法务和安全团队共同批准部署边界，而不是只听开发供应商判断。

评测要在实现之前开始

Agent 可能声称任务已经完成，但所需状态根本没有出现。因此要同时评测最终结果、执行轨迹和运行成本。

Anthropic 把一次 Agent 试验定义为一项任务运行，完整轨迹包含输出、工具调用、中间结果和状态变化。其评测指南建议结合代码检查、模型评分和人工复核，并阅读真实轨迹，而不是只相信一个汇总分数（Anthropic《Demystifying evals for AI agents》）。

版本化测试集应包含：

• 正常成功案例；
• 模糊或缺失信息的请求；
• 工具超时、错误返回和限流；
• 重复事件与中断运行；
• 检索内容中的不可信指令；
• 必须审批的动作；
• 必须拒绝或升级的案例；
• 过去出现过的生产故障。

每项任务写清初始环境、允许工具、成功状态、禁止变化、最大资源预算和评分方式。结果存在随机性时要重复运行。指标包括任务成功率、越权动作率、升级质量、人工介入、延迟、token 与工具成本，以及恢复成功率。

验收门槛应按任务和风险等级设定，而不是追求一个通用“准确率”。一份可见的草稿允许人工发现错误；修改财务记录的 Agent 则不能使用同一标准。

开工前就定义完整交付包

只有源代码不算交接。生产级定制 Agent 至少应交付：

排除项也要写明。数据清洗、界面开发、合规认证、渗透测试、第三方订阅、模型用量和上线后支持，如果未明确写入，可能都不包含在交付中。

部署必须假设任务会部分失败

Agent 运行通常比普通请求更长、状态更多。浏览器界面会变，模型调用会超时，工具可能已经写入成功但响应丢失，人工审批也可能几小时后才返回。

生产设计应包括：

• 有上限并带退避的重试；
• 外部写入的幂等键；
• 关键动作前的持久检查点；
• 等待审批、阻塞、失败、完成等明确状态；
• 取消与超时行为；
• 死信或人工复核队列；
• 模型、提示词、工具和策略的版本记录；
• 软件回滚和业务变更的补偿动作方案；
• 基于任务结果与越权行为的告警，而不只是服务器在线率。

恢复能力必须实际测试。要求团队在写入后中断任务、恢复上一版本、轮换凭据、重放失败事件，并证明系统不会丢失工作，也不会重复执行动作。

自建、购买还是混合

“定制”不等于“全部从零”。混合路线可以保留身份、模型访问、Workspace、调度或可观测性等通用能力，只用自定义代码实现专有决策、工具或控制。只构建能产生差异化价值，或现成产品无法满足边界的那一层。

在选择不可逆架构之前先做原型。原型要回答风险最高的问题：模型能否做对关键决策，工具能否安全执行动作，或结果是否能够可靠评测。

怎样验收供应商交付的 Agent

本节把工程验收接到更广义的自建、购买或混合决策上。采购解决“找谁、怎样签约”；技术验收解决“交付的系统是否真正归你运营”。

签字前要求供应商现场证明：

1. 约定的评测套件能够针对候选版本完整运行；
2. 拒绝、升级和审批暂停行为正确；
3. 凭据范围受限，审计日志可归因；
4. 能从超时、重复事件、工具部分失败和模型不可用中恢复；
5. 代表性负载下的真实成本与延迟可见；
6. 提示词、模型、工具、策略和部署配置全部版本化；
7. 能按所有权条款导出轨迹、评测数据、状态和源代码；
8. 完成一次回滚演练，并由接手方独立执行 Runbook。

不要接受没有说明“谁、在哪个动作、看到什么证据、无人响应怎么办”的“human in the loop”。不要接受只展示服务器在线、却看不到任务失败的“监控”。不要用演示数据集代替生产验收集。

最后的实际判断

当一项经过验证的业务任务确实需要模型动态决策、现有产品无法满足集成或控制边界，并且所有者准备把它作为持续变化的软件系统来运营时，定制 AI Agent 开发才合理。

开发计划应该从需求合同和评测案例开始，而不是从框架选择开始。架构需要把工具、状态、权限和失败恢复暴露出来。最终交付必须包含更换模型、调试事故、恢复任务所需的证据和运维资产，不能永远依赖最初的开发者。

流程仍然模糊，就先配置或做原型；流程高度标准，就购买现成产品；只有一层专有，就选混合路线。只有当控制力与差异化价值足以支撑你长期拥有全部层级时，才构建完整的定制系统。