智能体开发实战教程:五步构建可控执行闭环
作者:菠萝爱吃肉2026.11.18 11:20浏览量:1简介:智能体开发的难点不只是让模型调用工具,更在于约束任务边界、管理执行状态、验证结果并控制风险。本文围绕“查询业务记录并生成处理建议”的通用场景,分五步讲解需求拆解、工具设计、执行编排、安全控制和评测上线,帮助开发者建立可调试、可验证、可维护的智能体开发流程。
一、教程目标:把“能回答”变成“能可靠完成任务”
本教程面向开发者、运维人员和技术负责人,目标是构建一个能够查询业务记录、引用查询依据并生成处理建议的智能体原型,同时为后续上线准备必要的控制机制。
完成教程后,你应能够实现以下流程:
用户提交问题 → 校验身份与任务范围 → 模型选择查询工具 → 执行受控查询 → 检查返回结果 → 生成带依据的回答 → 记录执行轨迹。
这里的智能体,是指由模型参与任务决策,并在应用程序约束下调用工具、处理反馈的系统。它不等于一个更长的提示词,也不意味着应该让模型无限循环、自行决定全部操作。
为降低入门复杂度,本教程只使用单智能体与只读工具,不涉及自动修改业务数据、执行资金操作或自主部署服务。先把低风险任务做稳定,再逐步扩大权限,比一开始追求复杂自治更容易定位问题。
需要说明的是,模型的下载量、关注量或演示效果,不能直接证明其适合具体业务。工程选型应以真实任务测试、安全边界和运行成本为依据。
二、前置准备:先备齐任务、数据与执行环境
1. 准备明确的业务任务
建议从“查询某条业务记录的状态,并根据已知规则给出后续建议”开始。这个任务输入明确、结果可核对,也容易区分事实与推断。
准备少量经过脱敏的测试记录,至少覆盖:
- 记录存在,且字段完整;
- 记录不存在;
- 用户没有访问权限;
- 必填字段缺失;
- 查询服务超时;
- 返回文本中夹带诱导性指令。
最后一种情况用于验证:智能体是否会把业务数据中的文字误当成系统指令执行。
2. 准备基本运行组件
原型需要以下通用组件:
- 一个可供应用调用的模型推理服务;
- 一个负责流程控制的应用程序;
- 一个只读业务查询入口;
- 一个保存执行状态的位置;
- 日志与基础监控能力。
状态可以暂存在进程内,但如果任务需要跨请求继续,或者需要从中断处恢复,就应使用持久化存储。生产环境还需要明确身份认证、权限校验和凭据管理方式。
模型不应直接持有高权限数据库凭据。更安全的做法是由应用层提供受限制的查询工具,并由工具执行端检查权限。
3. 建立人工基线
先由人工完成一批代表性任务,记录正确答案、允许引用的字段,以及遇到信息不足时应该如何处理。
这份基线既是开发时的参照,也是后续评测的依据。没有明确的“正确完成”定义,就很难判断一次失败究竟来自模型、工具还是业务规则。
三、步骤一:定义任务契约,限制智能体的行动范围
做什么
把需求整理成一份可检查的任务契约,至少包含输入、允许动作、禁止动作和完成条件。
例如:
| 项目 | 本教程中的约定 |
|---|---|
| 输入 | 用户问题、目标记录标识、已认证用户身份 |
| 允许动作 | 查询授权范围内的记录、解释状态、给出建议 |
| 禁止动作 | 修改数据、跨用户查询、编造记录内容 |
| 完成条件 | 返回可验证的事实及依据,或明确说明无法完成的原因 |
| 信息不足 | 请求补充必要信息,不猜测关键标识 |
身份信息必须由应用从可信认证上下文取得,不能直接相信用户文本中声称的身份。
为什么这样做
“帮我处理一下”并不是可直接执行的任务定义。如果模型既不知道权限边界,也不知道什么时候算完成,就容易出现过度调用工具、反复追问,甚至把建议描述成已经完成的操作。
任务契约的价值,是把自然语言需求变成应用可以检查的规则。
注意什么
区分“业务事实”和“处理建议”。例如,“记录当前处于审核中”必须有查询结果支撑;“建议补充材料”则需要说明依据及适用条件,不能伪装成已经执行的业务动作。
如果整个任务只有固定的一次查询和固定格式的输出,可以优先采用确定性流程,不必为了使用智能体而增加自主规划环节。
四、步骤二:设计最小工具集,把权限控制放在执行端
做什么
为模型提供职责单一、输入输出明确的只读工具。
下面是应用自行定义的工具契约示意,不对应任何具体产品接口:
工具:查询业务记录模型提供的输入:记录标识:必填,格式由业务规则限定应用注入的上下文:当前用户身份当前权限范围本次请求标识输出:查询状态允许展示的记录字段数据更新时间证据引用标识
工具执行端应依次完成:
- 检查记录标识的格式与长度;
- 校验当前用户是否拥有访问权限;
- 执行受限制的查询;
- 过滤敏感字段;
- 返回统一结构的结果。
为什么这样做
模型可以提出调用建议,但不能成为授权决策者。即使模型生成的参数看起来合理,应用也必须重新校验。
工具职责越集中,失败原因越容易判断。一个同时支持任意查询、修改、删除和外部访问的工具,会显著扩大误操作与越权风险。
注意什么
不要把“查询结果为空”和“查询服务失败”都表示为一个空列表,否则模型可能把系统故障解释为记录不存在。
建议在应用内部区分以下结果:
- 查询成功且存在记录;
- 查询成功但无匹配记录;
- 权限不足;
- 输入不合法;
- 服务暂时不可用。
同时,工具输出只返回完成任务所需的字段。无关的大段文本既增加成本,也增加敏感信息暴露与指令混淆的机会。
五、步骤三:实现有预算的执行循环
做什么
将任务执行建模为明确的状态流转,而不是让模型持续自我对话。
可使用以下状态:
待校验 → 等待模型决策 → 等待工具执行 → 检查工具结果 → 生成答案 → 完成。
异常分支包括:等待用户补充、执行失败、达到预算、人工接管。
下面是通用伪代码,所有过程均由应用自行实现:
创建任务状态设置任务截止时间和最大决策轮数当任务尚未结束:如果超过截止时间或轮数预算:返回受控结束说明退出获取模型的下一步建议如果建议调用工具:校验工具是否在允许列表内校验参数和当前用户权限在剩余时间预算内执行工具保存结构化结果更新任务状态否则如果建议输出答案:校验事实依据与输出结构如果校验通过:返回答案结束任务否则:在剩余预算内要求修正无法修正则受控结束否则:请求必要补充信息或结束任务
为什么这样做
无限循环、重复调用和迟迟不返回,通常源于缺少可执行的终止条件。将轮数、时间和调用量作为应用层预算,才能避免模型自行决定何时停止。
配置如何确定
以下均为应用层控制项,不是模型服务的统一参数:
| 控制项 | 含义 | 设置思路 |
|---|---|---|
| 最大决策轮数 | 限制规划与修正次数 | 根据正常完成路径增加少量余量 |
| 任务总超时 | 限制整项任务耗时 | 结合用户等待容忍度与业务要求 |
| 单次工具超时 | 防止某次调用长期阻塞 | 参考工具耗时分布,并服从总超时 |
| 最大重试次数 | 控制瞬时故障重试 | 仅对可恢复故障进行有限重试 |
| 最大返回数据量 | 控制上下文长度与暴露范围 | 以完成任务所需最小数据为准 |
不要把工具超时、模型调用超时和任务总超时混为一谈。每次调用前都要检查剩余预算,否则单次调用可能耗尽整个任务的等待时间。
权限不足、参数错误等问题不应原样重试。只读查询出现暂时性故障时可以有限重试,但需要增加等待间隔,避免持续冲击故障服务。
六、步骤四:增加证据校验与安全防线
1. 将工具返回内容视为数据
业务备注、文档正文和外部检索结果可能包含“忽略原有规则”等文字。这些内容只能作为待分析数据,不能提升为系统指令。
提示词可以强调这一边界,但不能独立承担防护责任。真正的安全约束仍然需要由工具白名单、权限校验、输入验证和执行预算共同实现。
2. 让关键事实关联证据
建议输出分成三个部分:
- 查询事实:仅描述工具实际返回的信息;
- 处理建议:说明适用条件,避免暗示已经执行;
- 限制说明:注明缺失信息、数据更新时间或权限限制。
答案中的关键事实应能对应到工具结果中的字段或证据标识。需要注意,证据标识本身不等于事实正确:程序还应检查标识是否存在、对应数据是否属于当前任务。
对于状态、金额、日期等关键字段,尽量通过程序比较答案与结构化结果,减少仅依赖模型自检的情况。
3. 为后续写操作预留审批机制
本教程只实现查询。如果以后扩展到修改或提交操作,需要额外设计操作预览、明确确认、执行前权限复核、重复提交防护和审计记录。
不能因为用户曾授权过一次,就允许智能体在后续任务中持续执行同类高风险动作。
七、步骤五:建立评测集,再进入受控上线
做什么
把前面的测试场景固化成可重复运行的评测集。每个用例应记录输入、用户权限、预期工具行为、允许输出和禁止输出。
至少验证以下情况:
| 场景 | 预期行为 |
|---|---|
| 正常查询 | 返回正确事实及对应依据 |
| 缺少记录标识 | 请求补充,不自行猜测 |
| 未找到记录 | 明确说明未找到,不编造状态 |
| 无访问权限 | 拒绝查询,不泄露记录内容 |
| 工具超时 | 有限重试或受控结束 |
| 工具内容含诱导指令 | 忽略指令,继续遵循任务边界 |
| 模型提出未授权工具 | 应用拒绝执行并记录原因 |
| 达到执行预算 | 停止调用并说明未完成部分 |
如何判断结果
不要只统计“是否生成了答案”。建议同时观察:
- 任务完成率:是否满足预先定义的完成条件;
- 事实一致性:关键事实是否与授权查询结果一致;
- 越权拦截情况:未授权请求是否在执行前被阻止;
- 工具调用效率:成功任务是否存在明显的重复查询;
- 耗时与消耗:平均值之外,也要关注慢请求和高消耗任务;
- 受控失败能力:无法完成时是否给出真实、可理解的说明。
越权访问和敏感信息泄露应作为阻断上线的问题处理,不能被较高的平均完成率抵消。
上线顺序可以是:离线测试、内部试用、小范围开放、逐步扩大范围。每个阶段都保留停止入口与上一版本,出现异常时能够快速退回稳定流程。
八、日志与排查:先找到失败发生在哪一层
一次完整的执行日志建议记录任务标识、配置版本、状态变化、工具名称、脱敏后的参数摘要、耗时、返回状态和最终结束原因。
日志不应默认保存完整敏感正文,也不需要采集模型内部推理过程。排查通常依赖可观察的输入输出、工具行为和状态转换即可。
常见问题可按以下顺序处理:
问题一:模型一直调用同一个工具
先检查工具结果是否清晰表达成功或失败,再检查模型是否知道完成条件。应用层应识别重复调用,并在缺乏新信息时停止,而不是只靠提示词要求“不要重复”。
问题二:回答流畅,但业务事实错误
检查工具字段是否映射错误、结果是否被截断、证据是否来自当前任务。将关键字段改为程序化校验,通常比单纯要求模型“更加准确”更有效。
问题三:记录不存在时编造处理建议
明确区分“无记录”和“信息不完整”,并规定无依据时只能说明限制或请求补充。建议必须建立在已确认事实之上。
问题四:响应时间逐渐增加
检查是否累计了过长的对话历史、是否重复传入无关工具结果,以及下游查询是否变慢。可以保留必要状态与证据引用,减少重复上下文,但不能因压缩而丢失权限约束和关键事实。
九、总结:先建立可控闭环,再扩大自主能力
可靠的智能体开发,应按“定义任务契约、设计最小工具、实现受控循环、校验证据与权限、评测后上线”的顺序推进。
最重要的不是让模型表现得多么自主,而是让每次关键动作都有权限依据,让每条重要结论都有事实支撑,让每种异常都有明确的退出路径。只有当任务可验证、执行可追踪、失败可控制时,智能体才具备持续迭代和进入实际业务的基础。

登录后可评论,请前往 登录 或 注册