我见过太多 AI Agent 项目Demo 里跑得行云流水一上生产就原形毕露要么多轮对话后把上下文忘得一干二净要么工具调用乱套要么并发一上来直接超时雪崩。原因很简单——Agent 的工程实现核心不在 Prompt 写得多漂亮而在几个要素和几个决策点上是否想清楚了。这篇文章我想把 AI Agent 工程实现这件事拆开讲先说清楚一个能落地的 Agent 至少要具备哪七个要素再给出工程落地时绕不开的七个决策点每个决策点我都会说明选项、代价和我自己的选择依据。不管你是刚入门想搭第一个 Agent还是已经在用 LangGraph、Spring AI、Rust 之类的技术栈做正式项目这套拆解都能当一张地图用。1. 先分清套壳对话和Agent 工程的边界1.1 Agent 最朴素的定义模型驱动的工作流很多教程把 Agent 说得很玄动辄智能体自主决策多智能体协作。但剥掉这些词Agent 的本质就是一件事让大模型处在循环里工作。它读入任务、规划步骤、调用工具、观察工具返回的结果、再决定下一步直到满足结束条件。这个定义里最关键的不是模型而是循环。普通 Chat API 是一次问答用户问模型答结束。Agent 是多次问答加工具执行串联起来的流程模型问系统要数据系统给数据模型分析后再问再执行动作再观察结果……这个循环的长度、分支和终止条件才是工程上真正要设计的东西。我习惯把一个 Agent 比作带工具的实习生你给他目标他自己拆解步骤查资料、调系统、核对结果最后交作业。但你得给他明确的任务书、靠谱的工具箱、记事的便签本还得有一套做完没、做错没的验收标准。没有这些再聪明的实习生也会乱来。1.2 七要素全景一套 Agent 至少要有哪七块基于这个实习生的类比一个能上生产的 Agent我认为至少要具备七个要素。我用一张表把它们列出来方便对照要素作用缺了会怎样目标定义明确要完成的任务与成功标准模型不知道何时算干完容易无限循环感知输入把用户请求、环境状态、检索结果喂给模型模型只能瞎猜回答全凭幻觉规划将大任务拆成步骤、在多个路径中做选择一次生成直接跑偏无法纠错工具外部 API、数据库、代码执行等能力只会说不会做和聊天机器人没区别记忆短期上下文存取与长期知识沉淀多轮对话失忆任务做到一半忘了前提执行循环控制、超时、重试、分支、并发调度流程卡死或失控一个报错整个任务中断反思自评结果、错误修正、终止判定错了继续跑越跑越远最后给你一份错误答案这七要素对应的是一套完整回路目标定方向感知给输入规划出路径工具给手脚记忆保上下文执行做推进反思验质量。任何一个环节过于薄弱整个 Agent 就会像木桶的短板一样性能被死死压住。1.3 七个决策点是什么工程实现时每个要素都要拍板要素描述的是系统里有什么决策点描述的是这些东西怎么落地。同样是记忆你要决定上下文窗口怎么划分、超过长度是截断还是摘要还是向量检索同样是执行你要决定用代码把流程写死还是让模型自己决定下一步。这些就是决策点。把七要素映射到工程实现上会得到七个必须拍板的选择编排模式流程靠代码写死还是靠模型自由发挥还是用状态图/图编排。状态存储会话状态放内存、数据库还是 Redis要不要持久化。上下文管理token 怎么分配、超长怎么压缩、哪些信息必须保留。工具协议用 OpenAI Function Calling、MCP 还是自定义 JSON Schema。并发模型单 worker 串行还是多 worker 异步队列怎么处理重试和限流。安全边界工具调用权限怎么控制哪些动作必须人工审批。可观测性出错了怎么定位用日志、Trace 还是 Eval 回归集。后面的章节我会先把七要素逐个拆透再讲这七个决策点在真实项目里怎么选。2. 七要素逐个拆解哪些能简化哪些必须认真做2.1 目标与感知把用户一句话变成可执行任务书目标定义是七要素里最容易被忽视的。很多人把用户输入直接塞给 Agent当作任务本身。用户说帮我写个周报Agent 就开写。但放到工程场景里写周报背后还藏着很多约束周报给谁看格式是什么数据从哪个系统取篇幅多长要不要包含下一步计划真正的目标定义要做一层任务结构化。我常用的做法是在系统 Prompt 里显式声明任务的三个部分目标要达成的最终状态、约束不能做什么、必须符合什么格式、验收条件什么算完成。有些项目干脆用一个 task_schema 的 JSON 来承载这些字段模型先解析任务再开始干活。感知输入也一样。Agent 能看到的不是整个世界而是你喂给它的那些上下文。工程上要做的是把感知层抽象成一个输入聚合器用户消息、系统查询结果、外部 API 返回、数据库快照统一拼装成模型可读的输入。这里有个经验感知层要主动做信息裁剪不要什么都往里塞。模型上下文是有限的塞进去的噪音越大关键信息被淹没的概率就越高。2.2 规划ReAct 与 Plan-and-Execute 的取舍规划是 Agent 的核心智力所在。目前主流的规划范式就两类一类是ReActReasoning and Acting模型边想边做每一步都基于上一步工具返回的结果决定下一步。优点是灵活能应对意外情况缺点是不可控模型可能绕圈子也可能在某个分支上反复横跳。另一类是Plan-and-Execute模型先产出完整计划比如 1. 查数据 2. 分析 3. 写报告然后由执行引擎按计划逐步执行执行中如果发现计划行不通再回到规划节点重新规划。优点是整体路径清晰token 开销更可控缺点是计划外的意外处理起来比较笨拙。我的建议很直接业务步骤越固定越偏向 Plan-and-Execute探索性越强、没有固定路径的任务越适合 ReAct。比如自动发布一篇内容到自媒体平台这种任务步骤是固定的——生成内容、审核、发布——就应该用 Plan-and-Execute。而帮用户研究一个陌生领域并输出报告这种开放任务ReAct 更合适。工程上还有一个更务实的做法用状态图把主干流程固定死只在小分支上留 ReAct 的决策口。这既保证了主流程可预期又保留了分支上的灵活性。后面第 4 章讲 LangGraph 时会看到这种混合模式的落地形态。2.3 工具Agent 能力的上限在工具不在模型我经常跟团队说一句话决定 Agent 上限的从来不是模型智商而是你给它配的工具。模型再聪明调不到数据、执行不了动作它就只能纸上谈兵。工具层要做的事情有三件第一把能力封装成模型可调用的函数。不管底层是调用 HTTP API、执行 SQL 还是运行一段 Python 代码对外都要提供一个结构化的函数描述函数名、参数列表、参数类型、返回值说明。这一步本质上是在给模型写产品说明书说明书越清晰模型用工具的成功率越高。第二工具的返回值要面向模型设计。很多人的工具返回的是面向人类展示的 HTML 页面模型根本读不出结构化信息而好的工具返回的是精炼的结构化结果比如直接给 JSONstatus: success, items: 32 条。我见过太多 Agent 工具调用失败不是工具坏了是返回值太人类化模型解析起来吃力。第三工具要有明确的效果预期。每个工具都应该说明什么时候用、用了能拿到什么。如果工具的描述含糊模型就会在不该用的时候调用浪费 token 还引入噪音。2.4 记忆上下文窗口不是记忆这个误区的杀伤力很大。很多人以为模型上下文窗口大就能当记忆用把窗口开到 128K、200K然后所有对话历史全塞进去。结果是token 费用暴涨模型在长上下文中反而抓不住重点该记住的忘了该忽略的却当成关键信息。真实的记忆系统应该是分层的短期记忆当前任务内的对话状态、工具调用记录。这部分容量小但高频读写通常直接放在当前上下文里。工作记忆当前会话的阶段性结论、中间产物。比如用户已确认目标是 A预算上限是 B这些信息需要跨步骤保留我会单独用结构化字段存而不是让它混在对话历史里。长期记忆跨会话的知识沉淀。比如用户的偏好、项目的历史决策、常用模板。这部分不适合每次都塞进上下文应该通过检索按需召回。工程上很常见的一个做法是把长期记忆做成一个向量库加一个 KV 存储向量库存语义相似的软记忆KV 库存事实类的硬记忆。每次新会话开始先按用户 ID 召回相关记忆再拼装进上下文。2.5 执行与反思状态机 自检回路执行层最容易写成一坨while 循环里调模型的代码这在 Demo 阶段没问题生产就是灾难。一个健壮的执行层至少要处理四类问题超时控制模型调用和工具调用都要有超时上限Agent 卡在一个分支上不能无限等。重试策略对临时性错误网络抖动、API 限流做指数退避重试对确定性错误参数错误、权限不足直接短路不要盲目重试。步骤上限给整个 Agent 循环设置最大迭代次数防止死循环烧钱。分支条件用状态机显式表达什么条件下走哪条路避免模型每次都在同样的岔路口做选择。反思层的核心是一个自检回路。最朴素的做法是任务执行完让模型对照验收条件做一次自评是否满足全部要求有哪项不满足是否需要补一次工具调用自评不过就回到执行层补做自评通过才返回最终结果。这个自检回路听起来简单但在工程里价值极高。我统计过自己线上的 Agent 日志加了 Reflection 步骤后用户明确表达结果不对的比例下降了一半以上。小成本大收益。3. 七个决策点实操开发到生产必须拍板的七个选择3.1 决策一编排模式——code、ReAct 还是 GraphAgent 主流的实现架构本质只有三种对应热搜词里常说的ai agent 主流架构纯代码编排流程全部用代码写死模型只负责流程中的文本生成和工具参数抽取。可控性最高但灵活性差模型只是填空题机器。纯模型编排模型自己决定每一步做什么代码只提供工具。灵活但不可控适合探索型任务不适合有明确 KPI 的业务。图编排状态图管理流程节点上是模型调用、工具调用、条件判断。这是我在生产项目里最推荐的折中方案——主流程可视、可控、可测试分支处保留模型的决策能力。用 LangGraph 这类框架落地时代码逻辑大致是这样定义状态对象、定义节点函数每个节点做一件事、定义边和分支条件最后编译成一个可执行图。值得强调的是图的第一版别画太复杂先把主干跑通再把容易出问题的分支拆出来做成单独节点每拆一个节点都要回归验证。3.2 决策二状态存储——会话内存要与持久化分开状态存储要回答的问题很实在Agent 干到一半进程重启了这个任务还接得下去吗我见过不少项目把所有状态都存在进程内存里一个 Agent 实例挂了所有进行中的任务全部丢失。正确的做法是区分两类状态会话级状态当前任务的步骤进度、中间结果。高并发场景下建议放到 Redis给每个会话一个 key用 hash 或 JSON 存状态。任务执行到任何一步都可以随时恢复。业务级状态跨会话沉淀的数据如用户配置、审核记录、发布结果。放数据库按业务主键组织。第 5 章的表结构设计里我会给出一个具体的落地方案。这里先说一个判断标准你的 Agent 任务如果执行时长超过 30 秒就一定要做状态持久化否则任何一次发布部署都会打断线上的任务。3.3 决策三上下文管理——token 到底怎么算回答热搜词里ai agent token 是什么意思这个问题token 是模型对文本的最小切分单元一个中文汉字大约对应 1~2 个 tokenAPI 计费和上下文窗口上限都按 token 数算。所以上下文管理的本质是在一个有限预算里决定哪些字符能占用模型注意力。我的上下文预算分配原则是目标与约束占 10%系统指令与工具说明占 20%当前步骤的输入数据占 40%短期会话历史占 30%。超过预算后按优先级裁剪先压缩历史用摘要替换逐字记录再裁剪工具说明按当前分支只保留可能用到的工具最后才动任务目标。工程上强烈建议做一个上下文打包器在每次请求前把所有信息按上述优先级组装成一个上下文包并在组装时动态计算 token 数。具体可以用 tiktoken 这样的分词库估算超出预算就触发压缩逻辑。不要等模型因为上下文超限报错才处理应该在请求前就控制住。3.4 决策四工具协议——Function Calling、MCP 还是自研 Schema工具层的协议选型直接决定了你的 Agent 能接入多少生态。OpenAI Function Calling是目前兼容性最好的协议几乎所有主流模型都支持类似格式。核心就是把工具的 JSON Schema 传给模型模型输出工具名和参数。适合大模型 API 直接调用生态成熟但说实话模型偶尔会编造参数参数校验这层必须自己兜底。MCPModel Context Protocol是工具接入的标准化协议把工具变成可插拔的标准化服务。它解决了多 Agent 项目里工具重复实现的问题写好一个 MCP server多个 Agent 都可以连。适合中大型团队、工具数量变多之后的统一治理。自研 JSON Schema适合强约束场景。比如工具参数必须满足特定业务规则或需要在调用前做复杂鉴权。自研的代价是要自己维护协议文档和兼容层一般项目不太建议从零自研。我个人在中小项目里的选择是先用 Function Calling 快速跑通工具数量超过 10 个再引入 MCP 标准化。别一开始就上重型协议工具都没几个治理个空气。3.5 决策五并发模型——从单 worker 到任务队列怎么扛ai agent 怎么扛并发是目前所有做 Agent 上线的人都会撞上的问题。Agent 和普通接口不一样一个任务可能跑几十秒甚至几分钟里面好几次模型推理、好几次工具调用。如果同步处理一个 worker 同时只能跑一个任务并发能力极差。扛并发的核心思路是把接收请求和执行任务解耦。接收请求时立刻返回一个任务 ID真正执行放到后台队列里。前端轮询任务状态执行完成后返回结果。架构上从低到高的演进路线是单进程多线程只适合开发调试模型调用是会阻塞的 IO线程切换开销大不推荐生产。多 worker 进程 共享状态存储多个 Agent worker 进程同时消费任务状态放 Redis谁有空谁处理。这是性价比最高的起步方案。异步任务队列把任务投递到消息队列Redis Stream、RabbitMQ、Kafka 都可以消费者按需扩容任务失败进死信队列做补偿。适合任务量大且需要可靠投递的场景。并发场景下有几个坑要特别留意一是工具调用时要加分布式锁防止两个 worker 同时操作同一份外部资源二是要给队列任务设置超时和最大重试次数避免坏任务反复消费三是模型 API 的限流配额要共享统计否则 worker 一多直接把限流打爆。3.6 决策六安全边界——最小权限加人工审批Agent 的权限比普通程序危险得多因为它会把权限范围内的自由裁量交给模型。模型一旦被诱导或被幻觉带偏可能会调用它不该调的工具。安全边界我用了三条原则第一最小权限。Agent 服务的账号只授予完成业务所必需的权限。处理数据查询的 Agent 只给只读权限负责发布的 Agent 只能操作草稿不能删除历史内容。不要图省事用一个万能账号。第二高危动作人审。凡是涉及对外发布、资金操作、数据删除的动作一律走 human-in-the-loopAgent 生成动作申请系统通知人工确认人确认后 Agent 才执行。有人觉得这样不够智能但我宁愿损失一点自动化率也不愿意让 Agent 在无人监督下把事搞砸。第三输入输出双重校验。工具参数在传给外部系统前要做规则校验类型对不对、值是否在允许范围内、是否命中黑名单。模型生成的参数是概率产物校验这层绝对不能省。也顺便说一句经常有读者问个人使用 ai agent 可以做期货交易吗。我的看法是用 Agent 做行情分析和提醒没有问题但让 Agent 直接下单是另一个量级的事——模型对结果的置信度无法穷尽校验行情数据延迟、接口异常、模型幻觉任何一个环节出问题都可能造成真金白银的损失。真要碰交易建议 Agent 只负责生成分析和交易建议把最终的执行动作留给人工确认。这不是技术能力问题是责任边界问题。3.7 决策七可观测性——Trace 与 Eval 集Agent 出错了查不到根因是生产事故里最痛苦的事。普通后端服务排查靠日志就够了Agent 不行一次任务里有多次模型调用、工具调用、状态跳转没 Trace 根本不知道在哪一步跑偏的。最低成本的方案是结构化日志把每次模型调用的输入输出、token 数、耗时、工具名、参数、返回结果、状态跳转都记录到同一个 request_id 下。但我更推荐引入 Tracing 工具把每次 Agent 任务画成一条完整的链路哪个节点、调了什么工具、工具等了多久、模型回复了什么。排查问题的时候一眼就能看到卡在工具调用还是模型重复循环。除了日志和 Trace还要有 Eval 集。Eval 集是一批标注过的测试用例每个用例记录了输入、期望路径、期望结果。每次改动 Agent 配置或 Prompt跑一遍 Eval 集看是否出现回归。这个环节在 Agent 项目里特别重要因为 Agent 的行为是概率性的今天改了 Prompt 感觉没问题很可能某个边角用例已经悄悄坏了。没有 Eval 集你根本不知道它坏了。4. 技术栈选型参考LangGraph、FastAPI、Spring AI、Rust 与低代码平台4.1 LangGraph把状态图当一等公民LangGraph 是目前做生产级 Agent 绕不开的框架它把第 3.1 节说的图编排做成了标准能力状态用 TypedDict 定义节点是普通 Python 函数边支持条件分支。LangGraph 还内置了 Checkpointer可以把任务状态持久化挂了随时恢复——这个能力直接解决了第 3.2 节说的状态存储问题。我在实战里最满意的点是它的人类介入机制可以在图里定义 interrupt任务运行到某个节点时暂停等人工审核通过后再继续。比如自动发布文章前图会停在草稿待审核节点等人工确认后 resumeAgent 才继续调用发布工具。这比自己在业务代码里写状态机要省事得多。需要注意LangGraph 的图定义如果写得太复杂调试成本也会上升。我的习惯是核心流程控制在 6~8 个节点内每个节点函数保持单一职责边上挂的条件分支用专门的函数处理不在节点里塞一堆 if-else 判断逻辑。4.2 FastAPI 加 LangChain服务层与编排层分离热搜词里让 AI 真的下地干活基于 fastapi langchain langgraph 的 ai agent 智慧本质上就是那篇文章采用的架构组合。我的实践经验是LangGraph 管编排LangChain 消化模型调用和工具抽象FastAPI 管 HTTP 接口和任务调度入口三层各司其职。FastAPI 在 Agent 项目里承担两个角色。一是提供同步接口给前端轮询任务状态二是提供工具回调入口——Agent 的某个工具可能是内部服务FastAPI 正好可以把这些工具实现成标准 Webhook。相比 DjangoFastAPI 在异步并发上的开销更小Agent 这种高 IO 场景天然匹配。如果你团队熟悉 Java 生态Spring AI 也是同类选择它的核心抽象类似 LangChain 的模型客户端和工具接口但在 Java 已有的企业中间件生态里集成更顺。选 Spring AI 还是 LangChain与其说是技术问题不如说是团队技术栈问题Java 团队接 Spring AIPython 团队接 LangGraph都是合理路线。4.3 Spring AI 与 Rust两种极端的取舍如果团队以 Java 为主Spring AI 是进入 Agent 领域最平滑的路径。它提供了 ChatClient、工具调用、向量存储等抽象和 Spring Boot 的应用模型一致配置、依赖注入、监控都能复用家族能力。缺点是生态迭代比 Python 系稍慢新特性跟进不如 LangChain 快。Rust 语言做 Agent 则是另一个极端。有热搜在问基于 rust 语言 ai agent我理解这个诉求主要来自两类场景一是对性能敏感的基础设施层比如网关、路由、工具代理层用 Rust 重构降低整体的延迟和资源占用二是想在嵌入式或资源受限环境里跑轻量 Agent。Rust 的工程价值在于编译期安全和极低的内存占用但缺点是生态相对薄很多 Agent 的能力要靠自己造轮子开发效率明显低于 Python。我的选型建议是分层的业务编排层用 Python/Java 这类生态成熟的性能敏感的基础设施层网关、并发调度、工具代理用 Rust 单独做。不要试图用 Rust 重写整个 Agent 全栈除非你有足够的团队资源。4.4 低代码平台什么时候该用热搜词里的【愚公系列】《扣子开发 ai agent 智能体应用》指向的是以扣子Coze为代表的低代码 Agent 平台。这类平台的优点是显而易见的拖拽式编排、内置大量工具插件、免运维发布对非工程背景的人来说是体验 Agent 的最低门槛。但低代码平台的代价是编排灵活度受限、底层运行时不可见、工具生态受限。适合的场景是快速验证想法、内部效率工具、非核心业务流程。一旦你的 Agent 要深度融入自己的业务系统读写你的数据库、调用你的内部服务、和你的权限体系对接最终还是要走到代码研发这条路。我的经验是低代码平台做原型和演示生产系统的主流程自己做两边并不冲突。5. 完整动作清单从零搭一个能上线的 Agent以自动发布内容到小红书为例5.1 先定义任务边界热词里有个具体场景是ai agent让小红书自动发消息。我用这个场景走一遍完整落地流程工程细节都能落到具体表结构和代码上。但先声明一点这里讲的是基于开放接口或自己账号的自动化测试发布不涉及任何绕过平台规则的手段。业务上要确保你的自动化行为不违反平台条款。任务定义如下目标根据用户提供的话题生成一篇图文内容并发布到指定账号发布前经过人工确认。约束内容须符合平台内容规范发布时间由用户指定单次任务只发布一篇不做批量刷量。验收条件发布成功返回笔记 ID发布失败需要给出失败原因并支持重新生成。这个任务看起来简单但已经能覆盖七要素中的大部分目标定义上述文字、感知用户输入话题、规划生成内容→人工审核→发布、工具内容生成服务和发布 API、记忆用户偏好、执行状态推进、反思发布结果校验与重试。5.2 数据表与会话设计三层上下文这个场景需要三张基础表-- 任务表记录一次完整的 Agent 执行 CREATE TABLE agent_task ( id BIGINT PRIMARY KEY, user_id VARCHAR(64) NOT NULL, task_type VARCHAR(32) NOT NULL, -- e.g. content_publish status VARCHAR(16) NOT NULL, -- pending/running/reviewing/done/failed input_data JSON NOT NULL, -- 用户输入话题词、目标账号、期望发布时间 state_data JSON, -- 中间状态执行到哪一步、当前结果 result_data JSON, -- 最终结果笔记ID、发布链接 created_at TIMESTAMP NOT NULL, updated_at TIMESTAMP NOT NULL ); -- 步骤表记录每个工具调用的输入输出用于排查问题 CREATE TABLE agent_step ( id BIGINT PRIMARY KEY, task_id BIGINT NOT NULL, step_name VARCHAR(64) NOT NULL, -- e.g. generate_content/publish_note tool_name VARCHAR(64), input_data JSON, output_data JSON, status VARCHAR(16) NOT NULL, duration_ms INT NOT NULL, created_at TIMESTAMP NOT NULL ); -- 记忆表用户偏好和平台账号信息 CREATE TABLE user_memory ( user_id VARCHAR(64) PRIMARY KEY, preferences JSON, -- 文风偏好、常用话题 accounts JSON, -- 平台账号与授权信息 updated_at TIMESTAMP NOT NULL );这个设计的核心思路是任务表存全景状态步骤表存过程明细记忆表存跨会话沉淀。进程随时可以凭借 task_id 从数据库恢复执行排查问题时从步骤表就能还原完整链路。5.3 工具实现发布 API、草稿审核、重试这个 Agent 最少需要两个工具内容生成服务调用模型生成文案和图片方案和内容发布 API封装目标平台的发布接口。发布工具的 Schema 大致如下{ type: function, function: { name: publish_note, description: 将一篇图文内容发布到指定账号返回笔记ID仅发布草稿状态内容需预先过审, parameters: { type: object, properties: { account_id: { type: string, description: 用户绑定的平台账号ID }, title: { type: string, description: 文案标题 }, content: { type: string, description: 正文内容 }, images: { type: array, items: { type: string }, description: 图片URL列表 } }, required: [account_id, title, content] } } }发布动作必须走 human-in-the-loop。执行流程是Agent 生成内容后不直接调发布接口而是把内容写入待审核状态发通知给用户用户确认后任务从审核节点继续Agent 才调用发布工具。发布工具本身的实现要处理两类错误参数校验错误直接返回错误信息让模型重新生成参数接口临时故障做最多 3 次指数退避重试超过次数标记任务失败并通知人工介入。5.4 上线检查清单上线前我有一份固定检查清单这里分享给你[ ] 模型 API 限流配额是否与 worker 数量匹配并发压测过没有[ ] 所有工具调用是否有超时和重试重试是否会重复提交发布接口要做幂等[ ] 任务状态是否持久化进程重启后能否恢复执行[ ] 高危动作发布是否有人工确认环节[ ] 工具参数是否有业务规则校验模型乱传参数会不会打到线上[ ] 一次任务的 token 预算是否设了上限防死循环烧钱[ ] 日志和 Trace 是否覆盖每次模型调用和工具调用[ ] Eval 集是否包含至少 20 个典型用例关键路径改动后跑过回归6. 一次真实的 Agent 事故排查从 Trace 到根因6.1 现象Agent 说我做不了有一次线上 Agent 突然批量报错用户反馈非常一致任务刚提交Agent 就回复这个任务超出了我的能力范围建议换一种方式。但同样的任务类型昨天还在正常运行。这类软性拒绝是 Agent 事故里最隐蔽的形态。代码没报错、任务也没失败Agent 就是不明原因地拒绝干活。没有工程化日志的项目碰到这种情况基本只能抓瞎改 Prompt运气好改好了但不知道为什么好。6.2 排查链路Trace → 上下文 → 工具权限我按照三步定位第一步看 Trace。从任务链路里发现模型在进入规划节点之前就已经给出了拒绝回复根本没有调用任何工具。这说明问题不在工具执行而在模型收到的那份任务描述上。第二步看上下文包。把模型实际收到的输入拉出来对比发现上下文里有一行系统提示被改成了如果任务涉及外部内容发布不得执行请礼貌拒绝并给出替代建议。这行提示本身来自某次配置变更原本是打算加在未登录用户条件下的安全限制结果条件判断写错了全局用户都命中了这条规则。第三步看工具权限。继续往下查发现发布工具的权限配置也同步变更过工具对模型不可见所以即便 Agent 想执行它手里也没有可用的工具。根因清楚了一次配置变更同时改了三样东西——安全规则条件、工具可见性、系统提示三者叠加把一个正常任务打成了不可执行。6.3 修复与反思修复本身很简单修正条件判断、恢复工具可见性、把安全规则从系统提示挪到权限配置里。真正有价值的是这次事故暴露的管理问题Agent 配置的变更没有做 Eval 回归也没有最小化发布——一次改动里夹带了多个互不相关的修改出问题后很难定位。这次之后我把配置变更流程改成了三条铁律一次变更只改一个变量不管是 Prompt、权限还是工具配置都单独提 PR单独跑 Eval。安全规则不写在系统提示里全部收敛到底层权限校验层让模型碰不到规则的执行逻辑。上线前必须跑 Eval 回归Eval 集里专门加了正常任务不能被错误拒绝这类反向用例。这三条在后面的项目里帮我挡掉了至少三次同样类型的事故。Agent 是概率系统配置变更的影响面远比普通代码大没有回归测试兜底每一次修改都是一次赌博。做 Agent 工程这几年我最大的体感是模型能力在快速拉平真正拉开差距的恰恰是这些工程决策做得够不够细。七要素保证你有一个完整的系统框架七个决策点决定你的系统在真实流量下能不能站稳。对一个新项目我建议先按七要素盘点现状找出最弱的那块再针对它做决策点优化——不要一上来就追求全栈完美先把闭环跑通再逐步加固。项目做完也别急着丢把当时的选型理由、踩过的坑、Eval 用例整理进团队文档这些沉淀会比任何一篇教程都值钱。