演示20次成功19次，上线后半小时就报了警

一个客服 Agent 在会议室里演示，20 条手写问题答对 19 条。上线后第一批真实用户进来，半小时内出现三类事故：把两个订单号搞混、用户只问“能不能退”时直接调用了退款接口、遇到带错别字的地址返回“无法理解”。

行业里常说的“90% 的 Demo 上不了线”，没有统一的统计口径，它来自几个结构性原因：Demo 测的是能不能把流程串起来，生产测的是输入长尾、工具故障、副作用、成本和责任归属。

维度	Demo 的隐含假设	生产的现实
输入	你挑过的 20 条用例	错别字、方言、多语言、超长粘贴、恶意输入
工具	网络稳定、接口秒回	429 限流、超时、字段改名、token 过期
状态	单轮、进程内存	多轮、并发、服务重启、灰度发布
失败代价	重跑一次就行	订单已退、消息已发、报表已发出
成本	没人算	每次调用都出账单，月底对不上预算
可解释性	你自己看日志	客服主管要问为什么答错，合规要留痕

下面五道坎，是上线前必须逐条处理的。

坎一：任务规划是产品决策，不是提示词技巧

很多团队卡在第一步：让模型自己决定下一步做什么。自由度越高，行为越难复现。

Anthropic 在《Building effective agents》里把“工作流”和“Agent”分开讨论：如果任务路径可以提前写清楚，就用固定工作流；只有路径确实依赖运行时反馈时才交给模型自主决策。原文地址 https://www.anthropic.com/engineering/building-effective-agents 。ReAct 的原始论文（arXiv:2210.03629，https://arxiv.org/abs/2210.03629）给了“推理—行动”交替的基础范式，它解决的是能力问题，不解决稳定性问题。

落地先处理这四件事：

1）把可用工具压到 5～8 个，参数越少越好

工具描述写得越长，模型越容易在相似工具之间选错。能合并的合并，能用枚举的用枚举。

from typing import Literal
from pydantic import BaseModel, Field
class RefundArgs(BaseModel):
    order_id: str = Field(pattern=r'^SO[0-9]{12}$', description='订单号，形如 SO 加 12 位数字')
    reason: Literal['damaged', 'wrong_item', 'late']
    # 退款金额由后端按订单计算，不接受模型传入

金额这一条尤其重要。让模型传金额，等于把对账风险交给一个概率模型。

2）结构化输出走 function calling 或 JSON Schema

“请以 JSON 返回”在多数模型上成功率还行，但失败时报错不可定位。走 schema 校验，失败能明确知道是哪个字段不合法，重试时只改那一个字段。

3）错误分层，别对所有异常都重试

错误类型	例子	处理方式
瞬时故障	429、503、连接超时	指数退避重试 2～3 次
参数错误	订单号格式不符	把校验信息回给模型，最多重生成 1 次
凭证问题	token 过期	刷新凭证后重试一次
业务拒绝	订单已退款	不重试，把事实反馈给用户
未知错误	500、响应解析失败	熔断该工具，走兜底

**4）写操作必须幂等，并且有步数上限**

重试是稳定性手段，但重试一个已经成功的下单请求会造出第二笔订单。请求侧带幂等键，服务侧去重。规划器再加两个限制：单任务最大步数（常见 8～15 步）、重复动作检测（连续两次调用同一工具同一参数就中断）。

坎二：记忆分三层，状态别塞进对话历史

把所有历史都拼进 prompt，是成本超支和答案漂移最常见的原因。记忆按用途分开存：

类型	存什么	常见存储	读取时机	典型坑
短期记忆	当前任务的工作上下文	进程内存 / 会话表	每轮	无限增长，第 30 轮时 prompt 已经几万 token
长期记忆	用户档案、偏好、历史工单结论	关系库 / KV	任务开始时读一次	写入无审核，错误事实被反复引用
向量记忆	非结构化知识、历史相似案例	向量库	需要语义召回时	拿它当数据库做精确查询

三条判断规则：

能精确查的，不要用向量。 订单号、金额、日期区间这类查询，SQL 返回确定结果；向量检索返回相似结果，两者的错误形态完全不同。
短期记忆到阈值就摘要，摘要要保留原文片段。 只留摘要会让后续追问丢掉细节，把关键原文一起带上。
向量记忆要有写入门槛。 至少做一次去重和置信度过滤，否则一次错误回答会变成以后每次回答的依据。

状态持久化用框架自带能力，比如 LangGraph 的 checkpointer 加 thread_id，能保证服务重启后会话继续。自己用全局字典存状态，多实例部署时必然出问题。

坎三：Eval 是回归测试，不是上线前的验收报告

只做端到端评测，出了问题不知道是检索错了、工具选错了还是生成错了。分层评：

层级	评什么	怎么评	跑的频率
工具层	参数是否符合 schema、字段值是否和期望一致	JSON Schema 校验 + 字段比对	每次提交
轨迹层	选对了工具没有、步数是否合理、有没有绕路	和参考轨迹比对工具序列	每次提交
端到端	最终答案是否正确、是否满足业务口径	LLM 裁判 + 人工抽检	每日或每周

现成工具可以看 RAGAS（https://docs.ragas.io/ ，偏 RAG 指标）、LangSmith（https://docs.smith.langchain.com/ ）、Langfuse（https://langfuse.com/docs ）、OpenAI Evals。

LLM 裁判的四个硬性要求，少一个结果就不可比：

评分标准写进 prompt，别只说“打分”。
给参考答案或判定要点。
要求先输出理由再输出分数。
固定模型版本，人工抽检 5%～10%，算和人工判断的一致率。一致率低于 80%，这个裁判的分就不能用来卡发布。

回归集的来源只有一个可靠渠道：线上真实失败案例。每修一个线上问题，就往测试集里加一条。攒到 100 条左右，你就能在改提示词之前知道这次改动会碰坏哪些原有能力。

坎四：没有 trace 就没法调，没有预算就会超支

Agent 出问题时，你需要的不是一段日志，是一次完整调用的时间线：先调了哪个模型、输出了什么、接着调了哪个工具、返回了什么、哪一步开始跑偏。

按 OpenTelemetry 的 GenAI 语义约定（https://opentelemetry.io/docs/specs/semconv/gen-ai/ ）把 span 埋上，一次用户请求一个 trace，模型调用、工具调用、检索各是一个子 span。至少要记：trace_id、会话 id、模型名和版本、prompt 版本、输入输出 token、耗时、工具名、错误码。

成本控制不是等月底看账单，是在请求级就设上限：

手段	做法	效果
模型分级	分类、抽取、格式化用小模型；推理和规划用大模型	通常能砍掉最大的一块 token 支出
上下文裁剪	只带相关历史和相关检索片段	直接减少输入 token
前缀缓存	相同系统提示词走缓存	重复部分的成本大幅下降
结果缓存	相同查询短时间内复用结果	高频重复问题接近零成本
硬预算	单任务 token 上限，超限降级或转人工	防止一条请求烧掉一天预算

每上线一个功能都过一遍这个式子：

单次任务成本 = 输入 token × 输入单价 + 输出 token × 输出单价 + 工具调用费用

然后在 trace 上按天聚合，看 P95 成本，不看平均。多 Agent 编排尤其容易失控，一次任务几十次模型调用很常见。具体单价以各厂商 2026 年官网价目为准，这里不写死数字。

坎五：兜底策略要在写代码之前定

上线后一定会遇到：模型不确定、工具挂了、用户问的超出范围、操作有风险。这些情况下的行为要提前写成规则，不留给模型临场发挥。

flowchart TD A[用户请求] --> B{是写操作吗} B -- 是 --> C[生成操作预览] C --> D{用户确认或人工审批} D -- 拒绝 --> E[终止并说明] D -- 通过 --> F[执行] B -- 否 --> G{证据是否充分} G -- 否 --> H[转人工或澄清提问] G -- 是 --> I[生成回答] I --> J{置信度与校验} J -- 不通过 --> H J -- 通过 --> K[返回并记录 trace]

几条可直接抄的规则：

涉及资金、删除、对外发送的操作，一律先给预览再执行，或者进人工审批队列。
检索结果为空或相关度低于阈值时，不要让模型“根据常识回答”，直接转人工或给出明确的范围外说明。
单请求超时（比如 30 秒）就降级到静态 FAQ 或人工，不要让用户一直转圈。
人工修改过的答案要回收：进回归集，必要时进记忆库，作为下次依据。
转人工触发比例要监控。太低说明没兜住，太高说明模型能力不够或阈值设置不合理。

三个行业里的实际形态

下面三类是公开产品里能观察到的做法，不引用任何未经核验的效果数字。

客服场景。 公开产品包括 Intercom 的 Fin、Salesforce Agentforce、Zendesk 的 AI 功能。典型链路是意图识别 → 知识库检索 → 工单系统动作 → 转人工。这个场景最容易被低估的是知识库时效：一份过期的退换货政策会让 Agent 在几百个对话里给出同一个错误答案。另一处风险是给 Agent 开退款权限，务必先做金额上限和二次确认。

数据分析场景。 Databricks Genie、Snowflake Cortex Analyst 这类产品做的是自然语言到 SQL，链路是 schema 检索 → SQL 生成 → 执行 → 结果解释。三个高频问题：口径歧义（“活跃用户”到底怎么定义）、大表全扫描带来的查询成本、行级权限没跟着 Agent 走。上线前先明确语义层，把指标定义写死在元数据里，比让模型猜稳。

研发提效场景。 GitHub Copilot、Claude Code、Devin 这类工具的用法，是读代码、改代码、跑测试。评估点上有个常见误判：测试通过不等于需求正确。代码评审的负担不会消失，只是从写代码挪到了读 diff。给 Agent 划清可改目录和必须人工确认的路径，比追求更高的自动完成率更有用。

团队里谁该负责什么

Agent 项目卡住，多数时候卡在职责划分上。最小配置参考：

角色	负责的事	交付物
业务/产品	定义任务边界、失败时怎么办、转人工规则	任务清单、兜底规则
Agent 工程师	规划逻辑、工具 schema、提示词与编排	可运行流程、版本化 prompt
数据/知识工程师	知识库切分与更新、语义层、记忆写入策略	知识数据集、更新流程
平台/后端	鉴权、限流、幂等、审计日志	工具 API、trace 埋点
测试/Eval	回归集维护、裁判校准、发布门禁	评测报告、门禁标准
运维	监控、告警、成本看板、灰度与回滚	SLO、预算看板

小团队可以一人兼多角，但有三件事必须有明确责任人：线上失败案例谁来收、评测集谁来维护、预算超了谁来决定降级。这三件事没人认领，项目就会在第二个月停住。

明天可以做的第一件事

别急着调提示词。先做这一步：把工具调用和模型调用的 trace 埋上，跑一周，收集至少 100 条真实请求，把答错的挑出来标一遍。你会在一天内知道问题主要出在检索、工具选择还是生成上。这份标注也会变成你的第一版回归集。

文中论文与文档链接均为公开地址，请以访问时的最新内容为准；产品能力与价格以各厂商 2026 年官方页面为准。

AI Agent落地避坑手册：从Demo到生产要跨过的5道坎