搭建 AI 聊天智能体的 7 条实战教训：Trigger.dev 工程师复盘

Trigger.dev 的工程师为自己的控制台做了一个聊天智能体：帮用户排查失败的任务、按数据画图、检索文档。上线几个月后，他们在博客发了一篇坦诚的复盘——《构建 AI 聊天智能体前我们希望早知道的 7 件事》，文中还附了真实代码链接。本文用中文把七条教训逐一讲一遍：从"第一个回复必须快"到用裁判模型自动评分。原文：7 things we wish we'd known before building an AI chat agent。

第一个回复要立刻出现，哪怕智能体还没就绪

如果智能体要干真活（调用工具、读文件、起沙箱），它启动就需要时间。但盯着空白加载条的用户会认定系统坏了。Trigger.dev 的做法是把回复拆成两段：第一次模型调用直接在请求处理器里完成并立刻流式返回给用户，重的智能体同时在后台启动。第一个回复通常就是一次工具调用——仅这一点就能让用户看到 get_run("abc123") 正在发生，知道流程是活的。

关键在上下文交接：后台智能体接管时拿到第一步的全部内容（文本、工具调用），并且沿用同样的提示词和同样的模型——否则缓存失效，回答的语气也会中途变调。据他们的经验，这一改动把"到第一条有用反馈"的时间缩短了一半。

为什么这很重要？我们的数据能说明问题：以最近 14 天（2026 年 10 月 1–14 日，服务数据库）4912 次已完成的图片生成为样本，从发起到出成品的中位数是 78 秒，p95 达 236 秒。如果界面全程沉默，一半用户会以为卡死了。展示进度，哪怕只是一句"正在调用工具"。

准确统计 token，否则压缩对话会提前误触发

长对话会被压缩：摘要、裁剪，好塞进上下文窗口。它只应在对话真的很长时触发，而这需要准确的 token 计数。Trigger.dev 最初的版本把每个步骤的输入 token 加总——可每一步本来就包含之前的全部对话。结果：一个带五次工具调用的问题被算成 178,926 个输入 token，实际只有 39,557，压缩远在必要时就开始了。修法很简单：只取最后一步的输入 token——模型此前输出的内容，下一步本来就会变成输入。

限制重试次数——模型会把失败的工具敲到天荒地老

工具调用失败后，模型几乎肯定会再试一次。再一次。再一次。要统计连续失败并设硬上限，而且计数放在工具内部：网络抖动不算——工具自己用短退避重试。在 Trigger.dev 的实现里，连续三次查询失败后，智能体收到的不是新的报错，而是一句明确的话："次数用完，用已有的信息作答。"

顺带说重试：同样这 14 天里，我们服务共 5301 次图片生成，只有 89 次需要重试——占 1.7%。只要明确告诉模型"停下"，它不会无限敲打失败的工具。

对话要能在断线后活下来

连接会因各种原因断开，天真的实现在重连后会显示一个"永远在生成"的回复。解法是给流里的每个事件编号：重连时客户端说"我最后收到的是 43 号"，服务器从 44 号起补发，然后继续实时推送。为此回复不能只是一次 HTTP 响应——需要持久化的流存储（他们建在对象存储上，也有基于 Redis 的现成库，比如 resumable-stream）。

他们还建议把工具调用实时展示出来——他们的用户是开发者，喜欢看这个。另一面是：用户发来的消息要写进有序的持久化收件箱。智能体在步骤之间检查它（"纠偏"类消息直接注入当前轮），在轮次之间取出最旧的一条排进下一轮。Claude Code 里这就是 Enter 与 Ctrl+Enter 的区别。

给提示词做版本管理——枯燥，但躲不掉

提示词就是代码，迭代成本必须低，否则你改的次数会比应有的少。Trigger.dev 的方案：提示词定义在代码里，每个版本都保存，可以在控制台直接切换到新版本而不用重新部署。每个版本标注所用模型——哪个模型产出大量差评，一眼可见。再配合自动评估，提示词工程就从玄学变成了可度量的工作。

为智能体设计的工具，而不是为人设计的

这一节是几条短小但中肯的建议：

• 把边界告诉工具：如果结果会被截断，在描述和 API 响应里都要写明。
• 让智能体自己渲染：带错误卡片、品牌配色图表和"下一步"按钮的 render_view 工具，使用频率出乎意料地高。
• 给它一个反馈工具——一个普通 API 端点，智能体可以提交报告。调试循环立刻缩短。
• 给它用户上下文：get_current_page（"用户现在在看什么"）成本不高，回报很快。
• 子智能体可以并行任务，还不会撑爆主智能体的上下文。
• 最后，给它一台机器：能拉取用户代码、跑脚本、复现故障。

自动评估：10% 的对话由裁判模型打分

每轮对话结束后有 10% 会进入后台评估任务：裁判模型拿到问题、工具结果和回答，按三个维度（有据可依、切中问题、简洁）打 1 到 5 分，并标记缺失的工具、文档缺口或幻觉。分数与提示词版本一起存储——问题和回答不存。当一段对话被判为差，工程师打开步骤追踪，能精确看到哪里开始跑偏。

同样的原则——给失败分类，而不是只数个数——在我们这边也省了不少心：按最近 14 天（2026 年 10 月 1–14 日）的生成错误日志，297 次失败里约 40% 是内容过滤器触发，另有相当一部分是提示词过长或不支持的画面比例。一眼就能看出：该修的是面向用户的过滤器和限额提示，而不是基础设施。

如果你也在做聊天智能体，从第一条教训开始：快速的首个回复是投入一小时就能换回最多"哇"的改动。我们博客里还有一篇讲清智能体与聊天机器人区别的文章，可以配合上面的教训一起看。