logo

智能体开发实战教程:五步构建可控执行闭环

作者:菠萝爱吃肉2026.11.18 11:20浏览量:1

简介:智能体开发的难点不只是让模型调用工具,更在于约束任务边界、管理执行状态、验证结果并控制风险。本文围绕“查询业务记录并生成处理建议”的通用场景,分五步讲解需求拆解、工具设计、执行编排、安全控制和评测上线,帮助开发者建立可调试、可验证、可维护的智能体开发流程。

一、教程目标:把“能回答”变成“能可靠完成任务”

本教程面向开发者、运维人员和技术负责人,目标是构建一个能够查询业务记录、引用查询依据并生成处理建议的智能体原型,同时为后续上线准备必要的控制机制。

完成教程后,你应能够实现以下流程:

用户提交问题 → 校验身份与任务范围 → 模型选择查询工具 → 执行受控查询 → 检查返回结果 → 生成带依据的回答 → 记录执行轨迹。

这里的智能体,是指由模型参与任务决策,并在应用程序约束下调用工具、处理反馈的系统。它不等于一个更长的提示词,也不意味着应该让模型无限循环、自行决定全部操作。

为降低入门复杂度,本教程只使用单智能体与只读工具,不涉及自动修改业务数据、执行资金操作或自主部署服务。先把低风险任务做稳定,再逐步扩大权限,比一开始追求复杂自治更容易定位问题。

需要说明的是,模型的下载量、关注量或演示效果,不能直接证明其适合具体业务。工程选型应以真实任务测试、安全边界和运行成本为依据。

二、前置准备:先备齐任务、数据与执行环境

1. 准备明确的业务任务

建议从“查询某条业务记录的状态,并根据已知规则给出后续建议”开始。这个任务输入明确、结果可核对,也容易区分事实与推断。

准备少量经过脱敏的测试记录,至少覆盖:

  • 记录存在,且字段完整;
  • 记录不存在;
  • 用户没有访问权限;
  • 必填字段缺失;
  • 查询服务超时;
  • 返回文本中夹带诱导性指令。

最后一种情况用于验证:智能体是否会把业务数据中的文字误当成系统指令执行。

2. 准备基本运行组件

原型需要以下通用组件:

  • 一个可供应用调用的模型推理服务;
  • 一个负责流程控制的应用程序;
  • 一个只读业务查询入口;
  • 一个保存执行状态的位置;
  • 日志与基础监控能力。

状态可以暂存在进程内,但如果任务需要跨请求继续,或者需要从中断处恢复,就应使用持久化存储。生产环境还需要明确身份认证、权限校验和凭据管理方式。

模型不应直接持有高权限数据库凭据。更安全的做法是由应用层提供受限制的查询工具,并由工具执行端检查权限。

3. 建立人工基线

先由人工完成一批代表性任务,记录正确答案、允许引用的字段,以及遇到信息不足时应该如何处理。

这份基线既是开发时的参照,也是后续评测的依据。没有明确的“正确完成”定义,就很难判断一次失败究竟来自模型、工具还是业务规则。

三、步骤一:定义任务契约,限制智能体的行动范围

做什么

把需求整理成一份可检查的任务契约,至少包含输入、允许动作、禁止动作和完成条件。

例如:

项目 本教程中的约定
输入 用户问题、目标记录标识、已认证用户身份
允许动作 查询授权范围内的记录、解释状态、给出建议
禁止动作 修改数据、跨用户查询、编造记录内容
完成条件 返回可验证的事实及依据,或明确说明无法完成的原因
信息不足 请求补充必要信息,不猜测关键标识

身份信息必须由应用从可信认证上下文取得,不能直接相信用户文本中声称的身份。

为什么这样做

“帮我处理一下”并不是可直接执行的任务定义。如果模型既不知道权限边界,也不知道什么时候算完成,就容易出现过度调用工具、反复追问,甚至把建议描述成已经完成的操作。

任务契约的价值,是把自然语言需求变成应用可以检查的规则。

注意什么

区分“业务事实”和“处理建议”。例如,“记录当前处于审核中”必须有查询结果支撑;“建议补充材料”则需要说明依据及适用条件,不能伪装成已经执行的业务动作。

如果整个任务只有固定的一次查询和固定格式的输出,可以优先采用确定性流程,不必为了使用智能体而增加自主规划环节。

四、步骤二:设计最小工具集,把权限控制放在执行端

做什么

为模型提供职责单一、输入输出明确的只读工具。

下面是应用自行定义的工具契约示意,不对应任何具体产品接口:

  1. 工具:查询业务记录
  2. 模型提供的输入:
  3. 记录标识:必填,格式由业务规则限定
  4. 应用注入的上下文:
  5. 当前用户身份
  6. 当前权限范围
  7. 本次请求标识
  8. 输出:
  9. 查询状态
  10. 允许展示的记录字段
  11. 数据更新时间
  12. 证据引用标识

工具执行端应依次完成:

  1. 检查记录标识的格式与长度;
  2. 校验当前用户是否拥有访问权限;
  3. 执行受限制的查询;
  4. 过滤敏感字段;
  5. 返回统一结构的结果。

为什么这样做

模型可以提出调用建议,但不能成为授权决策者。即使模型生成的参数看起来合理,应用也必须重新校验。

工具职责越集中,失败原因越容易判断。一个同时支持任意查询、修改、删除和外部访问的工具,会显著扩大误操作与越权风险。

注意什么

不要把“查询结果为空”和“查询服务失败”都表示为一个空列表,否则模型可能把系统故障解释为记录不存在。

建议在应用内部区分以下结果:

  • 查询成功且存在记录;
  • 查询成功但无匹配记录;
  • 权限不足;
  • 输入不合法;
  • 服务暂时不可用。

同时,工具输出只返回完成任务所需的字段。无关的大段文本既增加成本,也增加敏感信息暴露与指令混淆的机会。

五、步骤三:实现有预算的执行循环

做什么

将任务执行建模为明确的状态流转,而不是让模型持续自我对话。

可使用以下状态:

待校验 → 等待模型决策 → 等待工具执行 → 检查工具结果 → 生成答案 → 完成。

异常分支包括:等待用户补充、执行失败、达到预算、人工接管。

下面是通用伪代码,所有过程均由应用自行实现:

  1. 创建任务状态
  2. 设置任务截止时间和最大决策轮数
  3. 当任务尚未结束:
  4. 如果超过截止时间或轮数预算:
  5. 返回受控结束说明
  6. 退出
  7. 获取模型的下一步建议
  8. 如果建议调用工具:
  9. 校验工具是否在允许列表内
  10. 校验参数和当前用户权限
  11. 在剩余时间预算内执行工具
  12. 保存结构化结果
  13. 更新任务状态
  14. 否则如果建议输出答案:
  15. 校验事实依据与输出结构
  16. 如果校验通过:
  17. 返回答案
  18. 结束任务
  19. 否则:
  20. 在剩余预算内要求修正
  21. 无法修正则受控结束
  22. 否则:
  23. 请求必要补充信息或结束任务

为什么这样做

无限循环、重复调用和迟迟不返回,通常源于缺少可执行的终止条件。将轮数、时间和调用量作为应用层预算,才能避免模型自行决定何时停止。

配置如何确定

以下均为应用层控制项,不是模型服务的统一参数:

控制项 含义 设置思路
最大决策轮数 限制规划与修正次数 根据正常完成路径增加少量余量
任务总超时 限制整项任务耗时 结合用户等待容忍度与业务要求
单次工具超时 防止某次调用长期阻塞 参考工具耗时分布,并服从总超时
最大重试次数 控制瞬时故障重试 仅对可恢复故障进行有限重试
最大返回数据量 控制上下文长度与暴露范围 以完成任务所需最小数据为准

不要把工具超时、模型调用超时和任务总超时混为一谈。每次调用前都要检查剩余预算,否则单次调用可能耗尽整个任务的等待时间。

权限不足、参数错误等问题不应原样重试。只读查询出现暂时性故障时可以有限重试,但需要增加等待间隔,避免持续冲击故障服务。

六、步骤四:增加证据校验与安全防线

1. 将工具返回内容视为数据

业务备注、文档正文和外部检索结果可能包含“忽略原有规则”等文字。这些内容只能作为待分析数据,不能提升为系统指令。

提示词可以强调这一边界,但不能独立承担防护责任。真正的安全约束仍然需要由工具白名单、权限校验、输入验证和执行预算共同实现。

2. 让关键事实关联证据

建议输出分成三个部分:

  • 查询事实:仅描述工具实际返回的信息;
  • 处理建议:说明适用条件,避免暗示已经执行;
  • 限制说明:注明缺失信息、数据更新时间或权限限制。

答案中的关键事实应能对应到工具结果中的字段或证据标识。需要注意,证据标识本身不等于事实正确:程序还应检查标识是否存在、对应数据是否属于当前任务。

对于状态、金额、日期等关键字段,尽量通过程序比较答案与结构化结果,减少仅依赖模型自检的情况。

3. 为后续写操作预留审批机制

本教程只实现查询。如果以后扩展到修改或提交操作,需要额外设计操作预览、明确确认、执行前权限复核、重复提交防护和审计记录。

不能因为用户曾授权过一次,就允许智能体在后续任务中持续执行同类高风险动作。

七、步骤五:建立评测集,再进入受控上线

做什么

把前面的测试场景固化成可重复运行的评测集。每个用例应记录输入、用户权限、预期工具行为、允许输出和禁止输出。

至少验证以下情况:

场景 预期行为
正常查询 返回正确事实及对应依据
缺少记录标识 请求补充,不自行猜测
未找到记录 明确说明未找到,不编造状态
无访问权限 拒绝查询,不泄露记录内容
工具超时 有限重试或受控结束
工具内容含诱导指令 忽略指令,继续遵循任务边界
模型提出未授权工具 应用拒绝执行并记录原因
达到执行预算 停止调用并说明未完成部分

如何判断结果

不要只统计“是否生成了答案”。建议同时观察:

  • 任务完成率:是否满足预先定义的完成条件;
  • 事实一致性:关键事实是否与授权查询结果一致;
  • 越权拦截情况:未授权请求是否在执行前被阻止;
  • 工具调用效率:成功任务是否存在明显的重复查询;
  • 耗时与消耗:平均值之外,也要关注慢请求和高消耗任务;
  • 受控失败能力:无法完成时是否给出真实、可理解的说明。

越权访问和敏感信息泄露应作为阻断上线的问题处理,不能被较高的平均完成率抵消。

上线顺序可以是:离线测试、内部试用、小范围开放、逐步扩大范围。每个阶段都保留停止入口与上一版本,出现异常时能够快速退回稳定流程。

八、日志与排查:先找到失败发生在哪一层

一次完整的执行日志建议记录任务标识、配置版本、状态变化、工具名称、脱敏后的参数摘要、耗时、返回状态和最终结束原因。

日志不应默认保存完整敏感正文,也不需要采集模型内部推理过程。排查通常依赖可观察的输入输出、工具行为和状态转换即可。

常见问题可按以下顺序处理:

问题一:模型一直调用同一个工具

先检查工具结果是否清晰表达成功或失败,再检查模型是否知道完成条件。应用层应识别重复调用,并在缺乏新信息时停止,而不是只靠提示词要求“不要重复”。

问题二:回答流畅,但业务事实错误

检查工具字段是否映射错误、结果是否被截断、证据是否来自当前任务。将关键字段改为程序化校验,通常比单纯要求模型“更加准确”更有效。

问题三:记录不存在时编造处理建议

明确区分“无记录”和“信息不完整”,并规定无依据时只能说明限制或请求补充。建议必须建立在已确认事实之上。

问题四:响应时间逐渐增加

检查是否累计了过长的对话历史、是否重复传入无关工具结果,以及下游查询是否变慢。可以保留必要状态与证据引用,减少重复上下文,但不能因压缩而丢失权限约束和关键事实。

九、总结:先建立可控闭环,再扩大自主能力

可靠的智能体开发,应按“定义任务契约、设计最小工具、实现受控循环、校验证据与权限、评测后上线”的顺序推进。

最重要的不是让模型表现得多么自主,而是让每次关键动作都有权限依据,让每条重要结论都有事实支撑,让每种异常都有明确的退出路径。只有当任务可验证、执行可追踪、失败可控制时,智能体才具备持续迭代和进入实际业务的基础。

发表评论

活动