Agent 出 Demo 只要一周但上线可能要用一年。差距不在能不能跑而在于三个核心问题循环怎么维护、上下文怎么管、工具调用失败怎么处理。很多开发者把 90% 的时间花在 Agent 的逻辑开发上但上线后才发现部署、运维、错误处理才是真正的深坑。一、Agent 循环的三个深坑Agent 的核心循环看似简单用户输入 → 模型决定调工具或不调 → 调工具 → 返回结果 → 模型再决定 → ... → 返回最终答案 → 终止但上了线每个环节都能让你翻车。坑 1循环维护每个 Agent 循环中有两个关键概念Choice从输入到最终答复的完整过程Turn一次模型调用一个 Choice 包含多个 Turn生产环境需要在循环中插入多个干预节点以 pi-agent70K Star 项目为例它在 10 个时机插入干预逻辑Choice 开始/结束 → 记时长、统计 Turn 开始/结束 → 判断轮次防无限循环100 轮停 模型调用前/中/后 → 敏感词检测、输出过滤 工具执行前/中/后 → 安全检查禁止 DROP/DELETE、结果脱敏其中最关键的拦截位置是工具执行前——这是兜底防线禁止危险操作的最后机会。坑 2上下文管理核心原则只有两条该给的信息要给齐完成任务的必要信息都要提供不打信息差不用给的信息不给占用上下文→分散注意力→Lost in the Middle具体工程处理工具输出截断完整结果保存本地文件提供截断文本 文件路径让模型自己评估要不要读完整版。上下文压缩token 剩余量低于阈值时主动压缩。关键细节——压缩在上一轮完成后做不在下一轮开始时做避免用户等待。压缩结果用结构化模板用户目标 / 约束条件 / 工作流程 / 关键决策 / 下一步计划。提升缓存命中率系统提示词分层、前后顺序优化、避免前缀变化。坑 3工具调用管理三阶段保障流程参数验证。JSON 序列化问题→自动转准确格式。Schema 验证→文本型参数要数字型→自动转化。原则是尽量给模型兜底。调用前后干预。调用前做危险指令检查和文件权限检查调用后做敏感信息脱敏。错误处理最有意思的部分。当工具执行失败时把报错信息当成结果返回给模型而不是终止循环。模型看到报错→可能意识到错误→重新生成准确调用。举例SQL 用了不存在的字段→报错返回→模型重新读表结构→生成正确 SQL。基本原则把错误返回给模型不终止循环给模型纠错的机会Agent 才会变得稳定自然。二、路架构选型LangGraph vs LangChain当你需要构建多步、有状态的 Agent 流程时框架选型的第一步就踩坑了。对比LangChainLangGraph图结构有向无环图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自动重启故障容器灰度发布先对少量用户开放稳定后再全量七、三句话总结控制性 灵活性流程有清晰边界节点内用大模型弹性转换不放任野蛮生成有状态 无状态结构化的持久化检查点状态可回溯、可干预、可降级数据驱动 直觉评估与监控并重让每次优化都有确定性反馈八、用户触达与落地路径让用户在熟悉的平台中使用 Agent微信/飞书等降低使用门槛 提高采用率。默认配置即可用灰度发布先对少量用户开放从 0 开发一个 Agent 的推荐路径先确定目标场景 → 设计 Skill 体系 → 选择 LLM → 搭建 Tools → 测试迭代 → 部署上线。