1. AI Agent 为什么总在“看起来能跑”和“一上生产就崩”之间反复横跳这两年聊 AI Agent 的人越来越多刷屏的 Demo 一个比一个惊艳自动写代码、自动查资料、自动操作浏览器、自动做数据分析。但真正自己搭过 Agent、或者把 Agent 扔到生产环境跑过一阵子的人心里多半都有个共同的困惑——这玩意在演示环境里什么都会到了真实业务场景里怎么就什么都不敢保证我印象很深的一次经历去年帮团队做一个内部知识库问答 Agent单轮对话调模型、调 RAG 都挺顺利demo 也给老板演示得风生水起。结果一接入团队群里几十个人同时用各种问题就炸出来了有人问着问着 Agent 突然开始胡言乱语有人上传了一份 PDF 之后整个上下文直接“失忆”还有人同一个问题连续问三次三次拿到三种完全不一样的答案。那天下午我一边看日志一边抓头发脑子里只有一个念头只把模型能力堆起来根本不算做完了一个 Agent真正的工程量在于让它在不可控环境里保持可控。这就是所谓“构建稳定的 AI Agent”这件事的残酷真相模型是不稳定的工具是脆弱的用户的输入是无规律的而你要在这三堆不确定性之上搭出一个尽量稳得住的生产系统。业界这几年逐渐把这一坨“让 Agent 稳定落地”的配套工程统称为Harness 工程——直白点说就是给 Agent 套上的那套“缰绳”和“护栏”包括了 Prompt 编排、工具契约、状态管理、错误恢复、可观测性这些东西。它不解决“模型聪不聪明”的问题它解决的是“模型就算偶尔犯浑系统也不能跟着崩”的问题。这篇文章我就想围绕 Harness 工程这个核心话题把我在实际搭建 Agent 过程中的思考和踩坑记录整理出来。内容不局限于某一个框架但会重点结合 Python 生态里常见的FastAPI LangChain LangGraph组合来讲最后也会聊到 Agent 中台化、产品化的方向。适合刚入坑 Agent 开发、想把原型变成生产级系统的同学参考。2. AI Agent 稳定性问题的根源拆解2.1 模型的不确定性是“原罪”不是 bug很多第一次搭 Agent 的人会习惯性地把 Agent 当普通接口来用传一个 prompt 进去期待一个 JSON 回来。但大模型本质上是个概率系统同样的输入、同样的参数每次生成的结果都可能有细微差异遇到推理能力不足或上下文过长的情况下差异会被放大到离谱的程度。我见过一个真实的案例某个 Agent 需要从用户输入里提取“城市”字段开发者在 Prompt 里写得很清楚“只返回城市名不要输出其他内容”结果模型还是会偶尔多输出一句解释、或者把省份一起带出来。如果这个输出直接被代码拿去当变量用后面的整个流程就全歪了。模型不是 bug但它的概率属性决定了你不能用“确定性系统”的思维来构建上层逻辑。处理这个问题的思路不是“让模型永远不出错”而是让系统在模型出错时不至于全盘崩溃。Harness 工程里有一块核心工作就是“输出校验与结构化约束”用函数调用function calling、JSON Schema 约束、输出校验器这些手段把模型的自由输出关进笼子里。你可以允许模型偶尔胡说八道但你的代码必须有办法一眼识别出它在胡说八道然后触发重试或者兜底逻辑。2.2 工具调用的脆弱性Agent 的能力越大爆炸半径越大Agent 和普通 Chatbot 的本质区别在于它能调用工具——查数据库、调 API、读写文件、执行代码。能力边界扩大了但随之而来的问题是工具调用链越长出问题的概率指数级上升。举个最常见的例子一个客服 Agent 先调用“查询订单接口”拿到订单号之后调用“查询物流接口”最后调用“生成回复模板”。三个环节里任何一个不通——订单接口超时、物流接口返回格式变了、生成模板时模型把参数搞错了——整个链路就挂了。更要命的是模型本身并不保证“每一次都选对工具、填对参数”它可能在第一步就把订单号填成用户 ID让后面的所有操作都建立在错误前提上。这就是为什么 Harness 工程里要反复强调“工具层隔离”和“契约测试”。你在让模型调用工具之前必须先把工具自身的稳定性做起来超时控制、重试机制、幂等设计、参数校验、异常返回约定这些常规后端工程的手段放到 Agent 的工具层一个都不能少。你不能默认模型会填对参数你只能默认“模型填错参数是常态”然后用校验逻辑把错误的调用挡在外面。2.3 上下文管理与状态隔离并发场景下最容易翻车的地方标题热搜词里有一个很扎心的问题AI Agent 怎么扛并发很多人在本地跑单个 Agent 时完全感觉不到状态管理的压力但一旦部署成多用户服务问题立刻暴露。核心原因是大模型的对话上下文是“有状态”的但大多数框架默认的用法却是“无状态”的。你把用户的对话历史存在内存里来了一个请求就丢给模型看起来没问题但一旦多个用户同时访问A 用户的上下文可能被 B 用户的请求覆盖或者历史消息在并发写入时顺序错乱模型就彻底“人格分裂”了。我在实操中用 LangGraph 处理这个问题时发现它的状态管理机制StateGraph天然支持显式定义状态对象和消息列表只要把状态对象做对隔离按会话 ID 区分不同用户的独立状态池并保证每次更新是原子操作绝大多数并发状态冲突问题都能在架构层面规避。核心原则就一句话绝对不要把用户的上下文集放在一个全局变量里哪怕你只是写个 Demo。3. Harness 工程的核心机制拆解3.1 定义“缰绳”Harness 到底在约束什么如果只用一句话概括 Harness 工程那就是在模型能力与业务目标之间插入一层可控的“约束面”。它的职责范围包括但不限于控制 Agent 的感知范围该看什么上下文、不该看什么控制 Agent 的行为边界允许调用哪些工具禁止调用哪些控制 Agent 的输出形态必须符合什么结构、什么格式控制 Agent 的失败路径出了错是重试、降级、还是终止这个思路和我之前做传统后端系统时的“契约优先”很像你先定义好系统的边界和接口再让实现去适配它。不同的是传统系统的实现是代码可控可测Agent 世界的“实现”是模型天然不可控所以这个约束面不得不做得更厚、更严密。实践中我习惯把 Harness 拆成五个层次从底层到顶层分别是基础设施层模型统一网关、模型降级路由、调用限额策略层安全策略、权限策略、敏感信息过滤流程层任务规划、步骤编排、状态流转工具层工具注册、参数校验、结果校验、错误重试表达层Prompt 模板、输出格式化、多轮上下文组装每一层都是独立的模块可以单独替换、单独测试。这样做的好处是模型升级了只动基础设施层业务逻辑变了只动流程层工具接口变了只动工具层互不干扰。3.2 ReAct 循环与 Plan-and-Execute两种主流的 Agent 运行时构建 Agent 时最基础的决策是你选择什么运行时模式来驱动 Agent 的“思考-行动”循环。当前主流的有两条路线。一条是ReActReason Act模型在每一步先“思考”然后决定调用哪个工具拿到工具结果后再思考下一步循环往复直到得到最终答案。这种模式适合任务路径不明确、需要动态决策的场景但它的问题在于没有全局规划每一步都是局部最优遇到需要多步递进的复杂任务时容易绕圈。另一条是Plan-and-ExecuteAgent 先根据任务目标生成一个完整的执行计划Plan然后按部就班地执行每一步Execute在执行过程中根据实际结果动态调整计划。这种模式的结构性更强、更可控也更适合生产环境——因为你可以把“计划生成”和“计划执行”两个环节分开监控、分开干预。我在实际项目里的做法是两者混合先让模型产出一个粗粒度规划plan再在每个规划步骤内部使用 ReAct 循环来动态决定具体操作。LangGraph 对这种混合模式的支持很友好你可以在图里面定义不同的节点规划节点负责产出步骤列表执行节点负责调用工具检查节点负责验证执行结果决策节点负责判断计划是否需要调整。整个流程是显式写出来的流程图而不是黑盒哪里出了问题直接看状态就能定位。3.3 状态管理从“对话历史”升级为“业务状态机”前面提到并发场景下的状态隔离这里再深入扩展一下。传统 Chatbot 的状态管理只需要管“对话上下文”——用户说过的每一句话。但真正的 Agent 要做的是多步骤任务执行它的状态远不止对话记录还包括当前任务目标及子目标分解情况已执行完成的工具调用及结果中间变量的值比如“订单号已经提取出来了”当前处于流程中的哪个阶段这些信息如果只塞在一个“messages 数组”里既不便于流程控制也不便于故障排查。我的经验是把它升级成一个显式的业务状态对象里面明确划分goal当前目标、steps规划步骤、completed_steps已完成步骤、context业务上下文、messages原始对话记录。用 LangGraph 的话这个对象就是传给 StateGraph 的 state每个节点都能读取和更新它的字段。这样做最大的好处是可恢复性。假设 Agent 执行到第三步调用数据库时超时了如果状态对象还在我可以直接从第三步重试而不是把整个任务推倒重来。这在传统后端里叫“断点续传”放到 Agent 世界里就是“任务可恢复”是稳定性建设的关键一环。3.4 可观测性不仅看日志还要看懂 Agent 的“心路历程”传统后端排查问题看异常堆栈就够了但 Agent 的问题往往没有异常——模型正常返回了只是返回的内容是错的工具正常调用了只是调用的参数是错的。这时候你光看日志里有没有 error 是完全不够的你必须要能看到模型的每一步输入输出、工具调用参数和返回值才能在出错时还原现场。所以我强烈建议在 Agent 的每一层都埋可观测性数据模型层完整 prompt、生成的原始输出、token 消耗、耗时工具层调用参数、返回值、耗时、是否重试流程层当前状态、当前节点、节点的输入输出用 LangGraph 的时候可以在每个节点上挂回调函数callbacks把节点执行信息吐到日志系统里。用 FastAPI 做服务层时可以用中间件记录每个请求的完整链路 ID把一次用户请求的所有日志串起来。关键是可观测性不只是给人看的更是给系统用的。当你积累到一定量的 Agent 运行日志后你完全可以用规则或小模型自动识别“高失败率”的模式提前预警。3.5 护栏Guardrails与安全边界宁可拒绝不可乱来Agent 一旦接入真实业务就必须面对两个问题它会接触到敏感数据它可能做出危险行为。这已经不是技术问题而是安全底线问题。我的做法是在 Harness 里设三层护栏。第一层是输入护栏用户输入进来先做敏感词过滤、越权检测、指令注入检测。第二层是行为护栏Agent 要调用工具时先校验这次调用是否在权限范围内、参数是否合法、目标资源是否越权。第三层是输出护栏Agent 生成最终回复之前先检查内容是否包含不该透露的内部信息。三层全过才放行任一层不过就走兜底回复或者拒绝。说实话护栏这件事没有银弹而是需要在具体场景里一点点补齐。但你可以在架构上一开始就留好位置而不是等出事了才补这是我在多个项目上的血泪教训。4. 从原型到扛并发基于 FastAPI LangChain LangGraph 的实战路径4.1 技术选型为什么是 FastAPI LangGraph而不是别的先回答一个常见问题为什么我现在不用纯 LangChain 的 AgentExecutor而转向了 LangGraph原因很简单LangChain 早期的 Agent 实现是个黑盒循环你很难干预里面的步骤流转LangGraph 把流程显式建模成图给了你完全的掌控力。这不是说 LangChain 不行而是对于要上生产、要精细控制、要扛并发的项目来说LangGraph 的“显式状态 显式流转”更符合 Harness 工程的要求。选 FastAPI 是因为它天然支持异步、性能好、生态成熟拿来包一层 HTTP 服务面对前端或者内部系统调用都轻松。至于 LangChain我现在主要用它已经沉淀好的工具封装和模型统一调用接口把它当成一个轻量库来用而不是让它来主导你的架构。4.2 服务层设计异步接口、请求级上下文隔离服务层是整个系统的入口它的核心职责是把 HTTP 请求转化为内部的 Agent 运行任务并保证每个请求都是独立、隔离的。我这里的标准做法是FastAPI 的接口定义为POST /api/v1/agent/run请求体包含session_id、user_input、metadata三个字段。session_id必填用来标记这是哪个用户、哪段会话的请求metadata用来带一些业务参数比如用户角色、租户 ID供安全策略层判断权限。接着在 FastAPI 的依赖注入里我按请求粒度创建 Agent 运行实例不搞全局单例。因为全局单例意味着所有用户共享一份运行时状态并发一上来就是灾难。按请求创建实例的开销远没有你以为的那么大——LangGraph 的编译图是可以复用的只是 state 是新的真正贵重的模型调用不会因为多创建一个实例就多花钱。4.3 LangGraph 的图结构设计编排、工具、检查三位一体LangGraph 应用的核心是定义一张执行图。我习惯把图设计成下面这些核心节点planner接收用户输入生成初步执行计划execute_tool执行具体工具调用这是最可能出错的环节inspect_result校验工具返回结果决定下一步是继续、重试、还是终止final_answer生成最终回复边上就是流转条件。比如inspect_result节点判断结果合法就走final_answer判断结果不合法但重试次数没到上限就回到execute_tool判断连续重试失败就走失败兜底节点返回一条“我暂时无法完成这个任务”的稳妥回复而不是让模型硬编一个答案。这套设计的精髓在于把 Agent 的每一步都暴露出来你可以在任意两个节点之间插入新逻辑比如加一个“人工审批节点”或者“权限确认节点”完全不影响整体架构。4.4 工具的契约化封装参数 Schema 与结果校验器工具是 Agent 的“手脚”也是最容易出问题的地方。我在封装工具时强制遵循一套契约每个工具必须声明自己的参数 JSON Schema明确每个字段的类型、是否必填、取值范围每个工具必须返回统一的结构至少包含success和data两个字段每个工具必须能处理自己不认识的输入返回错误而不是抛异常然后在调用工具之前我会加一个参数校验层用 JSON Schema 校验模型生成的参数。不通过就重试一次让模型琢磨一下重新填连续两次不过就降级到“该工具不可用”不让错误参数打到真实系统。结果校验这块容易被忽视。很多 Agent 工具调用之后压根不检查返回值默认工具返回的一定是对的。实际上工具返回的数据可能本身就有问题——比如数据库查询结果是空、第三方 API 返回了错误码、文件内容解析失败。所以在inspect_result节点里我会针对每个工具写一个轻量的校验函数至少检查返回结构和关键字段的合法性。4.5 并发与重试机制别把模型调用和业务逻辑绑死在同一个线程说到这里终于可以正面回答“AI Agent 怎么扛并发”这个问题了。首先你得明确一个事实单机同步串行地跑 Agent靠加机器堆性能是最笨的办法而且模型 API 的响应速度就摆在那动不动几秒到几十秒。扛并发的核心不是“让单个 Agent 跑得更快”而是“让系统能同时跑很多个 Agent并且互不干扰”。我的架构是这样FastAPI 接收到请求后通过消息队列或者异步任务队列把任务提交给 Worker 进程而不是在请求线程里同步等待模型推理结束。这样 Web 层保持高吞吐、低阻塞Agent 的整个执行过程在 Worker 中异步完成结果通过 WebSocket、轮询或者回调推送给前端。针对模型调用的并发控制我用两层策略第一层是每个 API Key 的调用限额RPM/TPM管理超了就在本地排队而不是死命往模型 API 上打第二层是重试机制对 429 限流错误和 5xx 服务端错误做指数退避重试而不是失败了就让整个任务挂掉。具体参数我是一个起跳值然后按实际压测调整的第一次重试延迟 1 秒第二次 2 秒第三次 4 秒最多重试 3 次对 429 错误读取响应头里的Retry-After字段按服务器要求等待对超时请求超时时间设为 30 秒连续超时就降级这些参数一开始是拍脑袋设的后来在压测环境里跑了一遍才定下来。建议你也拿自己业务的数据量去压一压别直接抄它的数字。5. 稳定性问题的排查与调优实录5.1 我的“高频翻车”问题速查表调试 Agent 的过程就像在解谜。下面这个表是我实际工作中整理出来的高频问题速查表每次排查问题时先对着它过一遍通常能省下一半以上的时间现象可能原因排查思路常见解决手段模型回复里多出解释性文字Prompt 约束力不够/模型能力不足看完整输出确认是否违反格式化指令改用结构化输出/函数调用加输出校验器工具调用参数频繁错误模型没理解工具 Schema查看日志里模型生成的参数和 schema 对比简化工具描述给明确示例必要时分拆工具任务执行到一半状态丢失并发环境状态互相覆盖检查 session 隔离逻辑全局变量污染按 session_id 隔离状态对象禁止用全局变量同一个问题每次答案不同缺乏确定性控制/温度太高对比模型参数和上下文组装逻辑调低温度固定 top_p必要时缓存相似问题答案流程在某个工具调用上反复重试工具本身的可调用性差/参数错误看重试日志确认是哪种错误类型修复工具补充参数校验设置重试上限API 返回 429 限流并发量超过模型接口上限检查队列积压和 API Key 用量本地限流排队多 Key 负载指数退避Agent 磨蹭很多轮才结束规划节点没有做好任务收敛看规划输出和最终轮次是否冗余设置最大迭代次数在提示中强调收敛用户传入非预期内容导致整个链路异常缺少输入清洗和兜底策略查看原始输入传入流程的情况加输入过滤器非法输入直接走固定回复排查时我记得最重要的一点是先定位是“模型问题”“工具问题”还是“编排问题”再动手改。三个层面的修复方式完全不同改错了地方不但没用还会引入新的不稳定因素。5.2 案例复盘一次真实的并发问题定位分享一个具体的排查过程也许能帮后来人少走弯路。那是一个内部工具型 Agent上线第二天就有同事反馈“我这边提交了一个问题结果看到了别人正在处理的记录。”我第一反应是状态隔离失效了。翻了代码发现确实如此我在模块层面定义了一个CONVERSATION_STORE {}用 session_id 做 key 来取上下文。看起来有隔离但实际上多个协程并发读写这个字典时Python 的字典操作本身不保证进程内多线程安全虽然没有直接崩但在高并发时数据错乱就出现了。我改成用threading.Lock包装所有读写操作之后问题初步缓解但这是我第一次意识到“用内存做会话存储”在并发场景下有多脆弱。后来我把会话存储迁移到了 Redis按 session_id 存储状态对象并设置过期时间才算真正解决问题。这个经历让我记住一句话生产环境里不要自己造轮子管理有状态数据用现成的、经过验证的存储层哪怕只是多引入一个 Redis 实例。5.3 重试策略的“度”什么该重试什么不该重试设计重试策略时最容易犯的错误是“什么错都重试”。实际上你得先分清错误的性质。对暂时性错误网络抖动、超时、限流重试是有意义的对确定性错误参数校验不过、权限不足、输入非法重试毫无意义只会浪费时间和 token我踩过的一个坑是某个 Agent 在调用数据库接口时用户本来就没有权限但系统一直自动重试了三次用户等了好几秒只得到一个“还在处理中”的提示。这种场景的正确设计是一开始就给出明确的“权限不足”拒绝而不是硬着头皮重试。所以我现在设计重试逻辑时会加一个判断只有异常类型匹配“可重试集合”的才进入重试分支其余错误直接快速失败。可重试集合一般包括超时、连接错误、429/5xx 响应而 4xx 类的业务错误和参数校验错误统统不重试。6. 关于 Agent 中台化与产品化的进一步思考6.1 从“一个 Agent”到“一堆 Agent”中台化的必要性单个 Agent 的稳定性问题解决之后紧接着来的问题是规模化的公司里有多个业务团队每个团队都要搞自己的 Agent如果每个人都从零开始搭一套 Harness地基部分全是重复劳动标准还不统一最后运维的复杂度会爆表。这就是“AI Agent 中台”出现的根本原因。我理解的中台不是一套炫酷的管理界面而是把 Harness 工程里那些公共能力抽出来做成平台服务包括模型网关统一接入各家模型、统一限额、统一降级工具注册中心统一管理工具定义、权限、灰度状态存储统一的会话存储和状态快照服务可观测性统一的链路追踪、日志采集、指标上报安全中心统一的隐私过滤、敏感信息脱敏、权限校验业务团队只需要基于中台开发自己的“流程编排”和“业务工具”不再关心模型怎么路由、状态怎么存储、日志怎么采集。这种分层方式本质上是把 Harness 工程从“项目里的代码”提升到了“组织级的基础设施”。6.2 产品化中的取舍功能广度 vs 确定性的权衡产品化 Agent 时还会遇到一个现实矛盾功能越广确定性越差。一个只做订单查询的 Agent 和一个什么都能聊的 Agent前者的稳定性大概率远好于后者因为它的行为边界清晰、工具集小、可预测性强。我的取舍原则是能用规则和流程解决的问题就不要让模型“自由发挥”只有真正需要理解、归纳、决策的部分才交给模型。典型的做法是给 Agent 定义“能力边界描述”当你把 Agent 的定位和官方文档写清楚之后再在 prompt 里明确告诉它“你只负责 A、B、C 三类任务其他问题一律回复无法处理”。这看起来减少了 Agent 的“能力”但换来的是用户可以预期的稳定体验。6.3 避坑指南这几个错误一定要少犯最后整理几条我觉得最有价值的实战避坑心得送给正在构建 Agent 的朋友们不要在 Agent 内部裸奔式地调用任何带副作用的外部系统所有工具调用都要有幂等设计和失败回滚不要在 prompt 里写一些含糊的“不要”指令比如“不要输出多余内容”而是直接用输出格式或者结构化工具约束它不要忽略超时与中断的处理用户可能等不及直接关掉页面但 Agent 可能还在后台傻傻地跑不要以为模型升级就可以自动解决稳定性问题模型越强它能搞出的新幺蛾子可能越隐蔽不要跳过压力测试一个 Agent 在单用户下表现得再完美都不代表它在 50 个并发请求下还能站得住我自己走过的弯路是初期过度信任模型的工具调用能力导致所有稳定性努力都押在“模型不会填错参数”上。现在我的态度刚好反过来——默认模型一定会出各种意外把每一个环节都当成可能出错来设计系统反而稳定多了。这种感觉就像写后端时默认“调用方一定会传非法参数”一样是个心态问题但直接影响系统的每一行设计。这个内容后续其实还有很大的扩展空间比如基于反馈数据自动优化 Prompt、用评测集对 Agent 质量做持续回归、把 Harness 能力和现有 DevOps 体系打通。如果你正在做 Agent 开发建议先把这篇文章里讲的状态隔离、工具契约、可观测性、重试策略这四件事落地跑通了再谈花活儿。