## Demo 能跑和系统能跑，中间隔着三个月

去年这个时候，我和团队花了三天搭出第一个 Agent 原型：接个 LLM、挂几个工具、套个流式输出，跑起来像模像样，演示的时候老板都点头了。
然后我们开始往生产推。
三个月后才真正稳定。中间踩的坑，没有一个是 LLM 本身的问题 —— 模型还是那个模型，Prompt 还是那段 Prompt—— 全是工程层面的事。
这篇文章不聊架构图，不聊哪个框架更优雅，就把那三个月里真正咬人的五个细节摊开讲。每个坑我都标了当时花的代价，方便你判断要不要提前防。
## 坑一：上下文窗口不是垃圾桶

### 发生了什么

第一版 Agent 跑长对话，三天后开始 "犯傻"—— 明明之前告诉过它的业务规则，它全忘了，或者把三个会话的上下文混在一起。
直觉反应是：上下文不够长？换 128K 模型？
换完发现更糟。128K 是够了，但每次请求都把历史对话全塞进去，Token 成本直接翻了四倍，而且模型在超长上下文里反而 "注意力分散"—— 关键信息淹没在几十轮闲聊里，召回率下降。
### 真正的问题

上下文管理根本不是 "装得下就行"，而是三个维度的权衡：
- **装多少**：全量历史 vs 摘要历史 vs 检索片段

- **什么时候装**：每轮全量注入 vs 按需检索注入

- **装什么**：消息原文 vs 结构化摘要 vs 向量检索召回

Demo 阶段这三个问题不用想 —— 会话短、任务单一、成本不敏感。一上生产，用户聊了两百轮，你才发现每一轮都在为前面一百八十轮的废话付 Token 钱，而且模型越来越抓不住重点。
### 我们最后怎么做的

三层分流：
1. **最近 N 轮**（比如 20 轮）原文保留，这是短期工作记忆，模型需要连贯上下文

1. **更早的对话**离线跑一遍摘要，只存关键结论和决策，不存闲聊

1. **跨会话的长期事实**（用户偏好、业务规则、历史决议）单独存一份结构化记忆，按需检索后注入，而不是无脑塞

加了这套之后，单轮 Token 消耗降了 60%，模型在长会话里的 "失忆" 问题基本消失。
**代价**：多写了一个摘要 job + 一个记忆检索模块，大概两周工时。
## 坑二：工具调用的错误率被严重低估

### 发生了什么

Demo 里工具调用十次成九次，剩下一次重试就好了。上线第一周，我们监控到工具调用成功率只有 82%。
一开始以为是模型不行。查了三天日志发现：模型每次都把参数格式写对了，问题出在下游 —— 有的接口超时，有的参数语义对了但业务校验没过，有的工具返回了意料外的格式，模型直接把错误信息当结果继续往下编。
最离谱的一次：某个查询工具返回了 "无数据"，模型把 "无数据" 当成了查询结果，编了一条完全不存在的业务记录给用户。
### 真正的问题

工具调用不是 "模型说调就调" 这么简单。生产环境里，每一次工具调用都可能失败，而且失败的方式五花八门：
- **网络层**：超时、限流、502

- **业务层**：参数校验失败、权限不足、资源不存在

- **格式层**：工具返回了模型没见过的字段结构

- **语义层**：工具成功返回了数据，但数据和用户问的不是一回事

Demo 里你不会遇到这些，因为工具都是你自己 mock 的，返回格式你都知道。
### 我们最后怎么做的

给每个工具包了一层 "防御性外壳"：
1. **结构化输出校验**：工具返回值先用 JSON Schema 校验，不合规直接返回明确的错误提示，不让模型把垃圾数据当结果

1. **重试分级**：网络错误重试三次，业务错误不重试直接报错给用户

1. **失败后的恢复路径**：不是让模型自己看着办，而是给它明确的指令 ——"工具失败了，你现在应该做 A 或 B，不要编造结果"

1. **成功率埋点**：每个工具的调用量、成功率、平均耗时全部打点，哪天下跌了立刻告警

**代价**：每个工具多写了大概 30% 的防御性代码，调试又花了一周。但工具调用成功率从 82% 拉到了 97%。
## 坑三：多轮会话的状态一致性

### 发生了什么

用户反馈一个 bug：他让 Agent 查了一下订单状态，然后让 Agent "把这个订单的问题反馈给客服"，结果 Agent 反馈给了三天前另一个订单。
查下来原因很简单：Agent 的会话状态里存了 "最近查询的订单号"，但这个值在另一个并行会话里被覆盖了 —— 用户同时开了两个聊天窗口。
### 真正的问题

Agent 的 "记忆" 如果不加隔离，就是一个全局变量。多会话并行、用户中途切换话题、定时任务和交互式会话共用上下文 —— 这些场景在 Demo 里根本不会遇到，因为你一个人一个窗口跑。
更隐蔽的问题是**幂等性**：同一个请求重试一次，Agent 会不会把订单查询两遍？会不会给用户发两条重复消息？Demo 里你手动点一次按钮，不会发现这个。
### 我们最后怎么做的

两件事：
1. **会话级状态隔离**：每个会话一个独立的状态命名空间，跨会话的共享数据（用户画像、全局配置）单独存，不和会话状态混在一块儿

1. **操作幂等键**：所有有副作用的工具调用（发消息、写数据库、调外部 API）都带一个幂等键，同一个键重试不重复执行

听起来都是常识，但在 Demo 阶段你真的不会想到要做这个 —— 因为 Demo 里没有并发，没有重试，没有用户同时开两个窗口的情况。
**代价**：状态层重构花了一周，改了六个工具接口加幂等键。
## 坑四：Token 账单的非线性增长

### 发生了什么

上线第一周，日活 50 人，Token 成本完全可控。第二周日活涨到 500，我们发现账单不是线性涨的，是指数涨的。
算了一下账：每个用户平均聊 15 轮，每轮请求都把全部历史塞进去，第 15 轮的请求 Token 数是第 1 轮的 15 倍。50 个用户的时候无所谓，500 个用户的时候，光上下文重复传输就烧掉了预算的 40%。
### 真正的问题

大多数人算 Agent 成本只算 "输入 + 输出" 的 Token 单价，忘了一个关键事实：**多轮对话的 Token 消耗是平方级的**—— 第 N 轮要把前 N-1 轮的历史全部重发一遍。
单用户单会话看不出来。一旦多用户、多轮、长对话，成本就炸了。
### 我们最后怎么做的

三刀砍成本：
1. **上下文压缩**：前面说的三层分流，旧对话摘要化，这是大头

1. **Prompt 缓存**：系统提示词里不变的部分（工具描述、业务规则模板）让模型服务商做前缀缓存，重复部分按缓存价计费，通常能省 50%-90%

1. **模型分级**：简单任务（分类、提取、格式化）用小模型，复杂推理（多步规划、工具决策）才用大模型。不是所有 LLM 调用都需要旗舰模型

砍完之后，单用户日均 Token 成本降了约 70%。
**代价**：前两项是纯工程，一周搞定；模型分级需要调路由逻辑，花了两周做 A/B 测试确定哪些任务可以下放给小模型。
## 坑五：Agent 出错了你都不知道哪错了

### 发生了什么

有用户投诉说 Agent 给了错误答案。我们去查日志，发现日志里只有 "用户问了什么 → Agent 回了什么"，中间调了几个工具、每个工具传了什么参数、模型为什么做了那个决策 —— 全没有。
等于开车的时候只看仪表盘的里程表，不看时速、油量、水温。
### 真正的问题

传统应用的可观测性是：请求进来 → 调了哪些服务 → 返回什么。每一步都是确定的代码路径，出错了看堆栈就知道。
Agent 不一样。Agent 是一个**由模型决策驱动的非确定性系统**：同一句输入，模型可能走三条不同的路径，调三个不同的工具。你不知道它为什么这么选，也不知道它在哪一步偏了。
没有中间过程的可见性，Agent 出了问题就是黑盒 —— 你只能猜。
### 我们最后怎么做的

给每一次 Agent 调用加了全链路 trace：
- 每一轮 LLM 调用的完整输入 prompt 和输出

- 每一次工具调用的参数、返回值、耗时

- 模型在多个工具之间选择的决策点

- 最终的状态变化链

不用全量存 —— 开发和测试环境全量存，生产环境按 trace_id 采样 + 异常全存。出了问题能复现 "这个用户这次为什么走到了这条路径"。
**代价**：接 trace 系统本身不难，两天搞定。难的是定下来 "哪些字段必须记录、哪些不用"，因为存太多成本高，存太少又查不出来。这个调了大概两周。
## 这些坑的共同点

回头看，这五个坑没有一个是 "LLM 不够强" 导致的。全都是同一个根因：**Demo 阶段你不需要关心工程边界，生产环境工程边界就是一切**。
- 上下文管理：Demo 里对话短，不需要优化；生产里对话长，不优化又贵又傻

- 工具错误：Demo 里工具是 mock 的，不会失败；生产里工具是真实的，一定会失败

- 状态一致性：Demo 里你一个人用，没并发；生产里几百个人同时用，状态会打架

- 成本：Demo 里几个用户，成本忽略不计；生产里规模一上来，平方级增长

- 可观测性：Demo 里出问题你直接跟用户说 "我再看看"；生产里你得自己能复现问题

## 什么时候别上 Agent

最后说个反直觉的判断。
如果你现在要做的事情是：**流程确定、步骤固定、不需要模型做决策**—— 那就别上 Agent。直接写确定性代码，又快又便宜又稳定。
Agent 的价值在于**需要模型在不确定的路径里做决策**的场景：用户问法千奇百怪、工具组合方式不固定、需要根据上下文动态调整下一步。如果你的场景里这些 "不确定" 成分很少，Agent 就是在给一个简单流程套一层昂贵的、不可靠的、还得你维护的模型调用。
反过来，如果场景里 "不确定" 成分很高 —— 开放域问答、多步任务规划、需要根据用户反馈动态调整 —— 那前面这些工程投入就是值得的。Demo 三天能跑，上线三个月才稳，这个时间差不是你能力不行，是生产级 Agent 系统本来就该这么重。
工具链选什么框架、用什么模型，反而不是最关键的决策。把这五个坑提前想到，比选哪个框架重要得多。

去年这个时候，我和团队花了三天搭出第一个 Agent 原型：接个 LLM、挂几个工具、套个流式输出，跑起来像模像样，演示的时候老板都点头了。然后我们开始往生产推。三个月后才真正稳定。中间踩的坑，没有一个是 LLM 本身的问题 —— 模型还是那个模型，Prompt 还是那段 Prompt—— 全是工程层面的事。这篇文章不聊架构图，不聊哪个框架更优雅，就把那三个月里真正咬人的五个细节摊开讲。每个坑我都标了当时花的代价，方便你判断要不要提前防。

AI Agent 上线记：五个把 Demo 拖垮的工程细节

去年这个时候，我和团队花了三天搭出第一个 Agent 原型：接个 LLM、挂几个工具、套个流式输出，跑起来像模像样，演示的时候老板都点头了。然后我们开始往生产推。三个月后才真正稳定。中间踩的坑，没有一个是 LLM 本身的问题 —— 模型还是那个模型，Prompt 还是那段 Prompt—— 全是工程层面的事。这篇文章不聊架构图，不聊哪个框架更优雅，就把那三个月里真正咬人的五个细节摊开讲。每个坑我都

人工智能

架构设计

后端

Demo能跑和系统能跑，中间隔着三个月，五个生产级Agent工程坑：上下文管理、工具调用错误率、状态隔离、Token平方级成本、全链路可观测性。文章用真实代价标注，帮你提前规避，判断何时该上Agent。

数据库

A/B测试

路由

Agent

2026上云采购 | AI焕新·智启新局

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

AI Agent 上线记：五个把 Demo 拖垮的工程细节-腾讯云开发者社区-腾讯云

AI Agent 上线记：五个把 Demo 拖垮的工程细节

AI Agent 上线记：五个把 Demo 拖垮的工程细节

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐