Agent 出 Demo 只要一周，但上线可能要用一年。差距不在"能不能跑"，而在于三个核心问题：循环怎么维护、上下文怎么管、工具调用失败怎么处理。

很多开发者把 90% 的时间花在 Agent 的逻辑开发上，但上线后才发现：部署、运维、错误处理才是真正的深坑。

一、Agent 循环的三个深坑

Agent 的核心循环看似简单：

用户输入 → 模型决定（调工具或不调）
→ 调工具 → 返回结果 → 模型再决定 → ... → 返回最终答案 → 终止

但上了线，每个环节都能让你翻车。

坑 1：循环维护

每个 Agent 循环中有两个关键概念：

• Choice：从输入到最终答复的完整过程
• Turn：一次模型调用（一个 Choice 包含多个 Turn）

生产环境需要在循环中插入多个干预节点，以 pi-agent（70K Star 项目）为例，它在 10 个时机插入干预逻辑：

Choice 开始/结束 → 记时长、统计
Turn 开始/结束 → 判断轮次，防无限循环（>100 轮停）
模型调用前/中/后 → 敏感词检测、输出过滤
工具执行前/中/后 → 安全检查（禁止 DROP/DELETE）、结果脱敏

其中最关键的拦截位置是工具执行前——这是兜底防线，禁止危险操作的最后机会。

坑 2：上下文管理

核心原则只有两条：

1. 该给的信息要给齐：完成任务的必要信息都要提供，不打信息差
2. 不用给的信息不给：占用上下文→分散注意力→Lost in the Middle

具体工程处理：

工具输出截断：完整结果保存本地文件，提供截断文本 + 文件路径，让模型自己评估要不要读完整版。

上下文压缩：token 剩余量低于阈值时主动压缩。关键细节——压缩在上一轮完成后做，不在下一轮开始时做，避免用户等待。压缩结果用结构化模板（用户目标 / 约束条件 / 工作流程 / 关键决策 / 下一步计划）。

提升缓存命中率：系统提示词分层、前后顺序优化、避免前缀变化。

坑 3：工具调用管理

三阶段保障流程：

参数验证。JSON 序列化问题→自动转准确格式。Schema 验证→文本型参数要数字型→自动转化。原则是尽量给模型兜底。

调用前后干预。调用前做危险指令检查和文件权限检查，调用后做敏感信息脱敏。

错误处理（最有意思的部分）。当工具执行失败时，把报错信息当成结果返回给模型，而不是终止循环。 模型看到报错→可能意识到错误→重新生成准确调用。举例：SQL 用了不存在的字段→报错返回→模型重新读表结构→生成正确 SQL。

基本原则：把错误返回给模型，不终止循环，给模型纠错的机会，Agent 才会变得稳定自然。

二、路架构选型：LangGraph vs LangChain

当你需要构建多步、有状态的 Agent 流程时，框架选型的第一步就踩坑了。

对比	LangChain	LangGraph
图结构	有向无环图（DAG），一条路走到黑	原生支持循环和回溯
场景	无法处理"生成→校验→不合格→重新生成"	轻松搞定回溯和循环
状态管理	无	内置 Checkpointer，每步自动存状态，支持暂停/人工审核/回滚（时空旅行机制）

简单的回答用 LangChain 就够了。但只要你的 Agent 涉及"检查→不合格→修改→再检查"这类循环，LangGraph 是不可替代的。

节点、边、状态三组件

组件	职责	设计原则
节点（Node）	任务单元化：调 LLM、调 API 或纯代码清洗	高内聚低耦合
边（Edge）	流控和动态抉择：读取当前 state 决定跳转	—
状态（State）	贯穿全图生命周期的共享字典	支持 reducer 增量合并，只能追加而非替换

状态管理最容易踩的坑

状态膨胀：多轮交互堆满冗余信息，context 爆掉。方案：状态裁剪，只保留核心要素和近三轮对话。

高并发状态冲突：多节点同时写 state 互相覆盖。方案：reducer 锁定关键字段，只做 append 不做 replace。

三、错误恢复：鬼打墙与死胡同

Agent 错误恢复有几种特有的模式，区别于传统后端：

死循环：设置硬性限制——recursion limit 不超过 15-20 步，触发上限强制抛异常兜底。同时做软性检测：条件边加 counter，连续多次调同一工具且结果高度相似→判定死循环。

鬼打墙（生成内容来回重复）：余弦相似度实时计算连续两轮生成文本，相似度超 0.95 且评估分没上升→原地打转。破局：强行切换备用模板、降低 temperature、提高 top_p、中断转人工审核。

死胡同（模型固执重复同一错误）：Error Injection——把报错日志强行注入新一轮 prompt，打破认知惯性。配合 Checkpoint 做无感重构：第五步崩了不从第一步重来，从第五步直接恢复。

四、安全：间接注入攻击

Agent 特有的安全风险是间接注入攻击——Agent 调搜索引擎或读第三方网页，里面可能藏着恶意指令。这不是用户直接输入的，所以输入过滤拦不住。

正确做法：不光用户指令要过安检，外部工具返回的数据流回 state 前也必须强制检测，异常直接截断输出备用模板。

五、评估体系：你怎么知道变好了

生产环境必须有数据证明 Agent 在变好：

维度	做法
LLM-as-Judge	单独部署评测模型当裁判，从输入/工具返回/最终回答三维度做一致性和事实性评分
Trace 链路监控	对接 LangFuse 或 Arize Phoenix，记录每次调用的全套路径，统计节点流向准确率
每日回测	每次改 prompt 或调架构前跑上百个高难案例回测，确保迭代不退化

六、部署架构

开发环境（本地调试）→ 测试环境（集成测试）→ 生产环境（容器化部署）

• 容器化：Docker + Kubernetes，每个 Agent Runtime 打包为镜像
• API 网关：统一入口，负载均衡，限流熔断
• 健康检查：K8s 定期检查 /health，自动重启故障容器
• 灰度发布：先对少量用户开放，稳定后再全量

七、三句话总结

1. 控制性 > 灵活性：流程有清晰边界，节点内用大模型弹性转换，不放任野蛮生成
2. 有状态 > 无状态：结构化的持久化检查点，状态可回溯、可干预、可降级
3. 数据驱动 > 直觉：评估与监控并重，让每次优化都有确定性反馈

八、用户触达与落地路径

1. 让用户在熟悉的平台中使用 Agent（微信/飞书等）
2. 降低使用门槛 = 提高采用率。默认配置即可用
3. 灰度发布：先对少量用户开放

从 0 开发一个 Agent 的推荐路径：先确定目标场景 → 设计 Skill 体系 → 选择 LLM → 搭建 Tools → 测试迭代 → 部署上线。