agent 开发实践
用户:「帮我记一下,明天下午三点开评审会,两点半提醒我。」
用户接着说:「提醒改到下午两点四十,开会时间照旧。」
假设这两句话都发生在周四。第一句要创建一条周五 15:00 的待办,并安排 14:30 的提醒。第二句只有一个字段要改。两轮结束时,用户的清单里应该只有一场评审会,开始时间仍是 15:00,提醒时间变成 14:40。
这个小例子很适合讨论 Agent 开发。第二句话省略了任务名称,模型得借助上文理解它;哪一条任务属于这个用户、提醒究竟有没有改成,则要靠业务系统回答。更麻烦的是,哪怕数据库已经改对,用户也可能只看到一句让人误会的「已帮你把会议改到两点四十」。
待办助手的设计与部署
业务架构里的三个角色
会话编排把当前消息、用户时区和可见历史交给模型。模型可以提出查询或变更,也可以直接向用户补问。接着由编排层检查这次调用是否获准,再把请求交给待办领域。这里有两种对模型特别有用的工具。
| 能力 | 能回答的问题 | 在评审会例子里的用途 |
|---|---|---|
| 查询待办 | 当前有哪些任务?哪条记录的时间和名称符合描述? | 取得这场会的目标记录,核对开始时间和现有提醒 |
| 变更待办 | 哪些字段要改?哪几项已执行,哪些仍待确认? | 只提交提醒时间的变更,根据执行收据组织回复 |
这里的「收据」指领域层交回的执行结果。工具请求只能证明模型提议过什么,收据才能支持「已修改」这样的措辞。如果用户有两场同名评审会,查询可以提供各自的开始时间,让助手问「你指周五三点那场,还是四点那场?」用户看到的是一个能答的问题,也用不着认识内部任务编号。
从 ART 到 Agent Tool,谁决定下一步
待办助手早期用一套称为 ART 的编排来处理自然语言。理解这次演进,可以从一个问题入手。模型在什么时候能看到业务结果,又能拿这个结果做什么?
第一阶段,识别一个动作。 用户说「明天下午三点开评审会」,入口把消息交给待办流程,模型给出创建意图和时间,后端做校验、写入。这种分工容易追踪,一条创建命令就能解释本轮发生了什么。等用户说「把评审会提前半小时,再把另一场会标成完成」,一个动作已经装不下两个要求了。
第二阶段,一次生成多步计划。 ART 的规划器可以把一句话拆成多个步骤,由后端检查目标和依赖,执行后汇总收据。在需要润色的待办回复里,独立的表达环节依据已知事实组织文案。这个版本已经能执行组合操作,但规划时只能使用当时的上下文。假如查询才发现有两场同名评审会,后续走哪条路,得靠计划里已有的处理规则。润色环节即使看见了两个候选,也没有权力回头发起一次新的查询。
第三阶段,模型看到工具结果后再决定。 换成 Agent Tool 之后,模型可以先查「周五的评审会」。只查到一场,就基于该记录请求修改提醒;查到两场,就直接问「你指三点还是四点那场?」这句话结束当前轮次。用户回答「三点那场」以后,助手再结合刚才展示的候选继续处理。修改成功时,同一个对话模型读取收据,向用户说明改动。
迁移时,任务归属、版本校验、实际写入和投递收据仍由后端负责。改变的是查询与决策的先后关系。它让助手能根据新事实改变动作,代价是一次对话可能多次往返模型,也可能在中途断开。后面讲的调用预算、上下文冻结和写入恢复,都是为这段多出来的往返准备的。
从部署架构看消息如何流转
图里取一个区域画出自然语言待办所用的部署单元。微信回调经网关进入 Kubernetes 里的后端应用。接入端先按消息身份去重,把入站事实持久化后即可应答。应用内的后台工作单元按会话顺序领取消息,经模型网关调用语言模型。任务、工具执行收据、会话检查点和待发送回复保存在关系数据库中。
这样拆开后有两个不同的完成时刻。第一个是提醒变更已提交,第二个是回复已从发件箱投递。假如应用恰好在两个时刻之间重启,后续处理可以继续投递原回复。为了补发一句「改好了」而再改一遍待办,会把投递故障变成业务数据故障。
一轮对话如何使用上下文和工具
修改一次提醒的执行流程
收到「提醒改到下午两点四十」时,编排层先固定本轮的消息时间、时区和可见历史。这些信息说明用户刚才谈的是评审会。随后,查询工具提供当前任务的身份和字段值。历史回答里的「三点」能帮忙定位,但用户也可能已经在清单里改过时间,所以写入只应涉及用户点名的提醒字段。
目标唯一时,助手提交一次变更。工具确认成功后,一句合适的回复是「周五评审会改为 14:40 提醒,会议仍是 15:00 开始」。如果查询出现两个合理候选,本轮可以停在补问;用户下一条消息和之前列出的候选合起来,才足以确定写入目标。
会话压缩怎样保住「刚才那场会」的上文
这里采用的是抽取式裁剪。系统从原对话里挑出能放进本轮请求的完整轮次,保留原话。新一轮无须先请模型写摘要。对待办尤其重要的是「我问的是哪一项」和「助手当时给了哪些选项」,把问答拆开,很容易丢掉「第二个」的指代对象。
- 固定时间锚点。 以当前消息的可信来源时间为截止点,只选同一用户、同一会话里排在它之前的有效输入。消息在队列里等了十分钟,窗口仍从这条消息的来源时间往前看。
- 取双窗口的并集。 默认取最近 1 小时内最新的 30 轮,再取最近 24 小时内最新的 10 轮,按轮次去重。如果一小时内已经聊了 30 轮,长窗口里的最新 10 轮已经包含在其中。如果一小时内只聊了 2 轮,长窗口还能带入较早的对话。
- 按整轮分配字节。 跳过不完整或不可读的轮次,从新到旧计算每组原文的 UTF-8 字节数。默认正文预算为 24 KiB。放得下就保留整组,放不下就跳过这组,继续尝试更早、更短的组。选完后恢复时间顺序。
- 合并已投递提醒并冻结。 已有发送证据的提醒单独选取,默认最多 20 条,按发生时间并回历史,保留助手角色。它们单独限量,连同普通历史、当前消息和工具说明一起受完整请求预算约束。本轮保存所选内容和截止点,故障恢复时沿用原输入。
图中把预算缩成 10 个单位,方便心算。最新一轮占 5,余下 5 装不下中间的 8,却装得下更早的 4。因此最终看到的是早、晚两轮,中间可能有空缺。如果「第二个」依赖的候选清单恰好落在空缺里,就得重新查询或请用户指明。裁剪改变的是本轮模型能看见的对话,数据库里那场评审会仍可查询。
工具怎么定义,粒度选多大
假设后端已经有三个接口,分别能查任务、撤销旧提醒、登记新提醒。要把 14:30 改到 14:40,该给模型几个工具?如果直接暴露后两个接口,模型得自己安排调用顺序。撤销成功、新增失败,用户明天就收不到提醒了。把它们包成一次「修改这条待办的提醒」更合适,替换过程和失败恢复都归待办服务负责,模型只需给出目标和新时间。
先按业务意图聚合,再按权限、副作用和失败后的处理方式拆分。 可以用三个问题决定边界。
| 设计时问自己 | 待办助手里的取舍 |
|---|---|
| 用户会把哪些动作看成同一件事? | 「三点开会,提前二十分钟提醒」可以作为一次创建提交。工具一起接收会议时间和提醒要求,返回同一场会的结果。 |
| 一次观察能否改变下一步决定? | 「改一下评审会」可能查到两个候选。查询单独暴露,模型看过结果再决定补问还是修改,查候选本身没有写入副作用。 |
| 能否用一句话讲清这次调用可能改什么、失败后怎么办? | 创建、更新可以共用一个变更入口,各操作有各自的参数约束和逐项结果。若还得在同一段说明里解释查列表、发消息、重新投递,就该拆开了。 |
工具说明也要写给第一次见它的调用者。以修改提醒为例,说明里要写清适用场景、目标从哪里取得、省略字段和显式清除各代表什么,以及成功或失败后能拿到哪些事实。尤其要把会议开始时间和提醒触发时间分成两个含义明确的字段。「14:40」在本例填进后者,未提到的字段保持原值。名字再漂亮,也救不了一个同时表示两种时间的参数。
传统 API 和 MCP 工具怎么分工
传统业务 API 可以继续服务网页、手机端和后台任务。以手机端为例,用户点开哪场会,页面就持有那条任务的标识;点击「保存提醒」后,客户端按预先写好的流程调用接口。Agent 面对的输入只有「刚才那场」,还得决定先查什么、哪个动作合适、手头的信息是否足够。
MCP(Model Context Protocol)提供工具发现与调用协议。客户端可以列出工具,把名称、描述和输入结构提供给模型,再按模型的选择发起调用,取回结果或工具错误。接入同一套待办服务时,可以在这一层组合已有 API,把「修改提醒」暴露成一个工具。鉴权、目标归属和写入一致性仍由服务端检查。这个案例本身使用应用内工具;若以后接入 MCP 客户端,这些业务契约可以复用。MCP 官方工具规范
把异常码变成模型能用的重试提示
「调用失败,请重试」没说清刚才到底改过数据没有,也没告诉模型再试时该换哪个参数。比如模型把「设置提醒为 14:40」和「清除提醒」同时放进请求。参数校验已经看出了二者冲突,把这条信息丢掉,模型下一次仍可能原样提交。
我会为每个模型可见的错误约定四项内容,即稳定的错误码、出错位置或目标、已知的执行结果、允许的下一步。具体存储异常留在日志里。下面用示意码说明这种约定。
| 示意码 | 告诉模型的事实 | 合适的下一步 |
|---|---|---|
FIELD_CONFLICT | 同一提醒同时要求设置和清除;校验阶段已拒绝,尚未写入 | 根据原话保留「设置为 14:40」,只重试被拒绝的变更 |
TARGET_AMBIGUOUS | 查到两场同名会议,用户没有指定哪一场 | 展示能区分的时间并补问,等待用户选择 |
STALE_VERSION | 刚才读取后,目标记录已有新版本 | 重读当前记录,只在原意仍适用时提交变更 |
WRITE_UNCONFIRMED | 写入已发起,缺少能确认结果的收据 | 按原操作标识核对,必要时查询当前状态,暂停后续写入 |
这就构成了一个小型 ReAct 循环。模型选一次动作,工具返回一次观察,模型据此修正下一步。图中第一条反馈明确了「还没写」和「哪两项互斥」,因此第二次请求可以有依据地删掉「清除」。收到成功收据,循环随即结束。可追踪的记录只需包含工具动作、观察和结果。ReAct 原论文及示例
次数和时间由宿主控制。这个案例里,普通轮次默认最多调用模型 6 次、工具 16 次;修复参数也要消耗同一份预算。已成功的写入复用收据,结果未知的写入先核对。增加调用上限解决不了「不知道第一次发生了什么」。
怎样知道提示真的提高了重试成功率? 固定模型、题库和重试预算,让两版各跑同一批故障样本。A 版只给错误码,B 版增加出错位置、写入状态和修复提示。按错误类型统计「首次可修复失败中,下一次调用就正确完成、且只生效一次的样本占比」。两版都从相同的首次失败开始,才能比较反馈的作用。需要用户澄清、写入结果未知的题另看应该停手时是否停手。重复创建两条待办,即使第二次调用返回成功,这道题也算失败。
多轮评测与提示词迭代
多轮评测怎么做,AI 裁判评什么
给定任务标识和新提醒时间,普通集成测试很容易断言只更新了一行、会议仍在 15:00。它也可以调用多个接口。Agent 评测还要考虑上文,因为下一轮用户说的「那场」或「第二个」,指向的是助手上一轮实际展示的内容。预先替助手填好任务标识,就绕开了最值得测的那一步。
可以把开头的例子变成一道三轮题。在隔离库里预置周五下午两场同名评审会,分别在 15:00、16:00 开始,原提醒各提前半小时。业务时钟固定在周四,三轮使用同一会话和同一份数据。
| 轮次 | 用户说什么 | 本轮要保留的证据 |
|---|---|---|
| 第一轮 | 「明天下午有哪几场评审会?」 | 保存助手实际展示的候选和顺序,同时断言任务没有变化 |
| 第二轮 | 「把提醒改到下午两点四十。」 | 两场都符合描述,应补问并给出可区分的候选;再次断言没有写入 |
| 第三轮 | 「三点那场,开会时间照旧。」 | 仅 15:00 那场的提醒改为 14:40。会议开始时间、另一场的提醒和任务总数都保持原值 |
同一道题还可以把第三句换成「第二个」。此时要对照第二轮回复中真实的候选顺序确定期望目标。若助手没列出有序候选,这句追问就缺少依据,评测应记录这个问题。测试偷偷按数据库顺序补齐答案,会让一个理解错指代的版本也拿到好成绩。
我会把验收拆成两份。程序逐轮检查业务事实,负责目标、字段、收据和副作用次数;需要验收到点投递时,用测试接收端分别观察旧、新提醒时刻。独立的 AI 裁判逐轮评可见回复,输入包括此前的真实对话、本轮用户要求、业务判据、已验证的结果和实际回复。裁判按是否找对对象、是否分清两个时间、补问或完成声明是否有依据给分,并摘出决定分数的原句。
例如,下列两句都出现在第三轮,而且数据库都改对了。
| 助手实际回复 | 裁判应如何评分(10 分制示例) |
|---|---|
| 「三点那场改为 14:40 提醒,开会时间照旧。」 | 10 分。对象、变更字段与执行结果一致。 |
| 「已把三点的评审会改到 14:40 开始。」 | 2 分。把提醒时间说成会议开始时间,会让用户误以为要提前到场。 |
反过来,话说得再准确,只要改错了另一场会,状态断言就应直接判该题失败。批次报告并列展示逐轮状态、AI 分数和扣分依据。先用人工标过的正反例校准裁判,再固定裁判模型和评分提示词比较两个版本;低分、临界分以及程序和裁判结论冲突的样本留给人复核。案例现有的场景流水线已自动比较待办终态,回复仍由人复核。把多轮 AI 评分接入这条流水线,是这套评测方案的下一步。
用 RSI 持续改进提示词
假设这道三轮题连续出现同一种错答。工具收到的是「修改提醒」,收据里也是 14:40 的提醒,助手却回复「会议改到 14:40 开始」。这就找到了一个适合改提示词的问题。反过来,如果工具已经写错了会议时间,润色最后一句只会把故障藏得更深,应该回到参数契约或执行逻辑排查。
这里把 RSI(Recursive Self-Improvement,递归自我改进)用于提示词的离线优化。模型根据上一版的失败样本提出下一版,再由独立评测决定是否采用。 每一轮都从已经验证过的版本起步。待办助手可以在离线评测中引入这个循环,生产对话仍使用随版本发布的提示词。历史候选及其得分可以作为下一轮改写的输入。OPRO 论文。
| 一次迭代 | 在「把提醒说成开会」这道题里怎么做 |
|---|---|
| 收集并归因 | 给负责改写的模型看脱敏对话、原提示词、工具收据和错答。先指出第一个出错的环节。本例的读写都正确,偏差发生在最后表达。 |
| 生成候选 | 只改回复规则。让模型解释新规则应修复哪一类错误,同时列出可能受影响的正确回复,便于检查它是否改得太宽。 |
| 做对照实验 | 旧版和候选版使用相同的业务模型、时钟、工具和评分标准,重复跑同一组对话。覆盖只改提醒、只改开会时间、两者都改、尚待用户选择。看各类题的回复和状态差异。 |
| 选择并进入下一轮 | 在开发题上选出候选,再用未给改写模型看的保留题验收。错写任务或无收据却宣称成功,都足以淘汰候选。保留题通过、关键场景稳定改善,才提交提示词变更;连续无改善或用完实验预算,就保留已验证的版本。 |
举个微小但能检验的改动。初稿可以是「操作成功后简洁告知用户」。一个候选改法是「回执里写清本次变更的字段和值。只改提醒时,说‘改为几点提醒’;如果同时提到会议开始时间,使用查询或收据中已核实的值」。它也留下了一个很好的反例题:用户只改开会时间时,助手会不会机械地套用提醒话术?这些是教学示例,两种写法的效果要由实验决定。
递归发生在下一轮。假如候选修复了提醒措辞,却开始在只有候选、尚未写入时也说「改好了」,就把这个失败和收据加入下一批开发样本,让模型继续提案。裁判规则和保留题由评测侧管理。每次记录提示词差异、题集版本和逐题结果,才能知道改善来自哪里,也能在新版本退步时退回上一版。