1. 为什么“五件事”这个说法值得认真对待做了快两年 Agent 开发我最大的感受是这个领域看起来每天都在冒新框架、新概念、新名词但真正落到工程里能决定项目成败的东西其实非常收敛。收敛到什么程度收敛到如果你把下面这五件事吃透市面上八成的 Agent 项目你都能上手反过来这五件事里任何一件没搞明白项目就会在某个阶段卡死而且卡得莫名其妙。先把这五件事摆出来后面逐个拆业务需求的边界拆解不是“我要做一个智能体”而是“我要让它在什么边界内、替谁、完成哪一步决策”。上下文工程模型看到什么、按什么顺序看到、什么时候该忘掉这一层直接决定输出质量的上限。工具调用与编排Agent 和普通对话机器人的分水岭就是它能不能可靠地调用外部能力并处理返回结果。工程化落地并发、超时、重试、可观测性、成本控制这些词听着不性感但它们是 Demo 和产品的分界线。安全与记忆治理Agent 会记住东西、会执行动作这两件事叠加起来就是风险必须有主动防御的思路。这五件事不是并列的知识点它们有依赖关系。业务边界决定上下文怎么设计上下文设计决定工具怎么编排编排方式决定工程化要解决哪些问题而安全治理贯穿始终。很多人学 Agent 是“从框架学起”先学某个编排库怎么用结果做出来的东西能跑通 Demo一上真实业务就崩。原因就是跳过了第一层直接扎进第三层。我见过太多团队在选型阶段纠结“用哪个框架”纠结了两周最后发现真正的问题根本不在框架而在于他们连“这个 Agent 的失败模式是什么”都没想清楚。框架是工具五件事是内功。内功不到换什么框架都一样。下面我按自己的实战顺序把这五件事一件件拆开讲每一件都会给到具体的判断标准、操作方法和踩过的坑。2. 第一件事把业务需求拆到“可判定”的粒度2.1 从“我要一个 Agent”到“我要它做哪一步决策”新手最容易犯的错是把需求写成“做一个能帮我处理客服工单的 Agent”。这句话没法落地因为它没有边界。什么叫“处理”是分类是回复是升级是归档每一步的判定标准是什么我在实际项目里用的方法叫决策点拆解法把整个业务流程画成一条线标出所有需要“判断”的节点然后问自己——这个判断Agent 能不能做做了之后谁来验收举个具体例子。一个电商售后场景流程大概是用户发起诉求 → 判断诉求类型 → 判断是否符合退款条件 → 生成处理方案 → 执行或转人工。这里面有四个决策点。Agent 适合做的是“判断诉求类型”和“生成处理方案”因为这两个是语言理解和生成任务而“是否符合退款条件”更适合用规则引擎因为它是确定性的让模型去判断反而引入不确定性。提示凡是能用确定性规则解决的问题不要交给模型。模型的优势在模糊判断和语言生成不在精确计算和规则匹配。这个拆解过程产出的东西应该是一张表而不是一段话。表格里每一行是一个决策点列出输入是什么、输出是什么、判定标准是什么、失败时怎么兜底。这张表就是后面所有工作的地基。2.2 判定标准怎么写才算“可判定”“可判定”的意思是给定一个输出两个人看完了能得出一样的结论说它合格还是不合格。很多需求写出来是不可判定的比如“回复要专业”“语气要友好”。这种标准没法用来做评估也没法用来做回归测试。我的做法是把不可判定的标准翻译成可观测的行为。比如“专业”可以翻译成不出现口语化语气词、引用信息必须来自知识库、涉及金额必须精确到分。“友好”可以翻译成开头有称呼、结尾有下一步指引、不使用否定式命令句。这些翻译出来的行为直接就能变成评估用例。你攒上三五十条这样的用例就有了一个最小可用的评估集。这个评估集的价值比任何框架文档都大因为它是你这个业务专属的。2.3 一个反直觉的经验需求要往小了拆我踩过最大的坑是一开始总想把 Agent 做得“全能”。结果就是上下文里塞了一堆指令工具挂了一大堆模型在中间反复横跳最后哪个任务都做不好。后来我改成一个原则一个 Agent 只负责一个决策点。需要多个决策点协作就用多个 Agent 串起来或者用工作流编排。这样每个 Agent 的上下文都很干净指令聚焦工具集也小调试起来一目了然。这个原则带来的直接好处是评估变简单了。单个决策点的评估集很小跑一次几分钟改一版提示词马上能看到效果。而如果是一个全能 Agent你改了一处不知道会影响哪一处评估跑一次半小时迭代速度直接掉一个数量级。3. 第二件事上下文工程决定输出质量的天花板3.1 上下文不是“塞得越多越好”现在模型的上下文窗口越来越大百万级上下文已经不是新鲜事。但我实测下来的结论很明确上下文长度和输出质量不是正相关很多时候是负相关。原因有两个。第一模型在长上下文里的注意力是会被稀释的关键信息淹没在大量无关内容里召回率会下降。第二长上下文意味着高成本和高延迟这两项在真实业务里都是硬约束。所以上下文工程的核心不是“怎么塞更多”而是“怎么塞得更准”。我把它拆成三个动作选、排、压。选是从所有可用信息里挑出这次任务真正需要的。排是决定这些信息的顺序把最关键的放在模型注意力最集中的位置。压是把长内容压缩成短内容比如把十轮对话压成一段摘要。3.2 上下文的四个层次要分清我在项目里习惯把上下文分成四层每层的处理策略不一样层次内容处理策略更新频率系统层角色设定、核心指令、输出格式固定精简反复打磨极低任务层当前任务的目标、约束、可用工具每次任务动态生成每任务记忆层历史交互、用户偏好、已确认事实摘要检索按需注入动态即时层本轮用户输入、工具返回结果原样保留注意截断每轮这四层里最容易出问题的是记忆层。很多人把历史对话一股脑全塞进去结果就是上下文越来越长模型越来越糊涂。正确的做法是历史对话定期摘要摘要存起来需要细节的时候用检索把相关片段捞回来而不是全量注入。3.3 提示词工程和上下文工程的关系这两个词经常被混着用但我觉得它们不是一回事。提示词工程关注的是“怎么把指令写清楚”上下文工程关注的是“模型在这一刻看到了什么”。前者是写作技巧后者是信息架构。一个很实际的例子你写了一段完美的系统提示词但如果工具返回的结果格式混乱、字段缺失模型照样会输出垃圾。这时候问题不在提示词在上下文的数据质量。所以我现在排查问题第一步永远是打印出模型实际看到的完整上下文而不是盯着提示词改。提示调试 Agent 的第一动作永远是把“模型实际收到的完整输入”打出来看。九成的问题看一眼真实上下文就明白了。3.4 上下文压缩的实操方法压缩这件事我试过几种方案分享下取舍。最简单的是滑动窗口只保留最近 N 轮。优点是实现简单缺点是会丢掉早期的重要信息。适合短会话场景。进阶一点的是摘要压缩把早期对话用模型总结成一段话。这里有个坑摘要本身也会丢信息而且摘要质量不稳定。我的做法是摘要只保留“已确认的事实”和“未完成的待办”不保留过程性内容。再进一步是结构化记忆把对话里提取出的关键信息存成结构化字段比如用户 ID、订单号、已确认的诉求类型。这些字段在需要的时候精确注入比摘要更可靠。这个方案实现成本高一些但在长周期任务里效果最好。我现在的默认组合是结构化记忆打底摘要补充滑动窗口兜底。三层配合基本能覆盖大部分场景。4. 第三件事工具调用与编排Agent 的分水岭4.1 工具调用的本质是“契约”很多人把工具调用理解成“让模型调用一个函数”这个理解太浅了。工具调用的本质是模型和外部系统之间的一份契约模型承诺按约定格式发起调用外部系统承诺按约定格式返回结果。契约的任何一端出问题整个链路就断。所以设计工具的时候重点不是“这个函数怎么写”而是“这个契约怎么定”。我总结了几条硬性要求工具描述必须说清楚“什么时候用”和“什么时候不用”。只写功能不写边界的工具模型会滥用。参数必须做严格校验。模型生成的参数经常有类型错误、字段缺失、格式不对校验层要能拦住并给出明确错误。返回值必须结构化且稳定。不要让工具返回一大段自然语言模型解析起来容易出错。错误信息要能被模型理解。返回“error 500”模型不知道怎么处理返回“参数 order_id 格式错误应为 16 位数字”模型就知道怎么修正。4.2 编排的三种模式按复杂度选工具多了之后就需要编排。我见过的主流模式有三种复杂度递增第一种是单轮调用。模型决定调哪个工具调完拿到结果直接生成回复。适合简单查询类任务。第二种是循环调用。模型调工具看结果决定是否再调直到任务完成。这是目前最主流的模式也是大部分编排框架的核心。这里的关键是循环终止条件必须有最大轮数限制否则模型可能陷入死循环。第三种是图编排。把整个流程画成一张有向图节点是处理步骤边是流转条件。这种模式适合流程复杂、分支多的场景。它的优势是流程可控、可观测缺点是灵活性差遇到图里没定义的路径就卡住了。我的选型经验是能用单轮就别用循环能用循环就别上图。图编排的维护成本很高流程一变就要改图而且调试起来要沿着图走很费劲。只有当流程确实复杂到循环模式表达不了的时候才上图。4.3 工具调用的常见失败模式这块是我踩坑最多的地方列几个高频问题参数幻觉。模型编造了一个不存在的参数或者把参数值写成了看起来合理但实际错误的内容。应对方法是参数校验加白名单非法参数直接拒绝并返回明确提示。工具选择错误。工具多了之后模型经常选错。应对方法是精简工具集每个 Agent 只挂它真正需要的工具同时把工具描述写得更有区分度。结果解析失败。工具返回的格式和模型预期的不一致。应对方法是返回值严格结构化并且在提示词里明确告诉模型返回值的格式。并发冲突。多个工具调用同时修改同一份数据。应对方法是加锁或者串行化这个属于工程问题后面还会讲。4.4 一个具体的工具设计示例假设我要设计一个“查询订单状态”的工具我会这样写描述工具名query_order_status 用途查询指定订单的当前状态和物流信息 何时使用当用户询问订单进度、物流位置、预计送达时间时 何时不使用当用户询问退款进度时应使用 query_refund_status 参数 order_id (string, 必填)16 位数字订单号从用户输入或历史上下文中提取 返回值 { status: 已发货, logistics: [{time: ..., desc: ...}], estimated_arrival: 2026-01-15 } 错误情况 订单不存在返回 {error: ORDER_NOT_FOUND, message: 未找到该订单请确认订单号}这份描述里“何时不使用”这一条特别重要。它明确划清了和另一个工具的边界能显著降低选错工具的概率。5. 第四件事工程化Demo 和产品的分界线5.1 并发问题Agent 扛并发到底难在哪“AI Agent 怎么扛并发”这个问题本质上是问一个请求要占用多少资源、持续多久、怎么隔离。Agent 请求和普通接口请求最大的区别是耗时长且不确定。普通接口可能 50 毫秒返回Agent 请求动辄几秒到几十秒中间还要调好几次模型和工具。这意味着单个请求占用的连接、内存、上下文资源都更多并发能力天然比普通接口弱。我实际项目里的做法是分层处理接入层做限流。按用户或按租户限流防止单个用户打满资源。请求层做异步。Agent 请求全部异步化前端轮询或推送结果不占用长连接。执行层做队列。把请求放进队列按优先级调度避免瞬时高峰压垮后端。模型调用做池化。模型 API 调用做连接池和重试避免单点失败。这套组合下来单机并发能力能提升一个数量级。但要注意队列会引入延迟所以队列长度和超时时间要配合业务容忍度来定。5.2 超时、重试和幂等Agent 链路长任何一环都可能超时。我的原则是每一环都要有独立的超时和重试策略不能用一个全局超时糊弄过去。模型调用超时重试要谨慎因为模型调用可能已经产生了副作用比如已经扣了 token。工具调用超时重试前要确认工具是否幂等非幂等工具重试会导致重复操作。幂等这件事在 Agent 场景里特别重要。比如“创建工单”这个工具如果超时后重试可能创建出两张工单。解决办法是让调用方生成一个唯一请求 ID工具侧根据这个 ID 去重。提示所有会产生副作用的工具都必须支持幂等。这是 Agent 工程化的底线要求不是可选项。5.3 可观测性没有日志就没有调试Agent 的调试难度比普通程序高一个量级因为它的行为是不确定的。没有完善的日志你根本不知道模型为什么输出了那个结果。我要求日志里必须记录这几样东西完整的输入上下文、模型的原始输出、每一次工具调用的参数和返回值、每一环的耗时、最终的输出。这些日志按请求 ID 串起来出问题的时候能完整回放整个链路。除了日志还要有指标。我关注的几个核心指标是任务成功率、平均轮数、平均耗时、工具调用失败率、token 消耗。这几个指标能覆盖大部分问题。5.4 成本控制token 是要花钱的Agent 的 token 消耗比普通对话高得多因为每一轮都要带上完整上下文还要加上工具调用的开销。一个复杂任务跑下来token 消耗可能是普通对话的几十倍。控制成本的手段有几个上下文压缩前面讲过、工具结果精简、模型分级简单任务用小模型复杂任务用大模型、缓存相同输入直接返回缓存结果。模型分级这块我特别想强调。很多团队所有任务都用最强的模型成本高得离谱。实际上大部分任务用中等模型就够了只有少数复杂推理任务需要上大模型。做一个路由层按任务复杂度分发到不同模型成本能降一半以上。6. 第五件事安全与记忆治理容易被忽视但代价最高6.1 Agent 的安全边界和普通应用不一样普通应用的安全问题主要是输入校验和权限控制。Agent 的安全问题多了一层模型可能被诱导做出非预期行为。这个风险来自两方面。一是用户输入可能包含诱导性内容让模型绕过限制。二是工具返回的内容也可能被污染模型如果无条件信任工具返回就可能被间接操控。我的防御思路是不信任任何输入。用户输入要过滤工具返回要校验模型输出要审核。每一层都假设上游可能有问题做独立的检查。6.2 记忆治理Agent 该记什么、不该记什么Agent 有记忆能力是好事但记忆也是风险。记错了会导致后续判断错误记多了会泄露隐私记久了会积累过时信息。我的记忆治理原则是三条只记确认过的事实。模型推断出来的内容不写入长期记忆避免错误累积。记忆要有过期机制。临时信息设过期时间到期自动清理。敏感信息不落库。涉及个人隐私的字段做脱敏或加密不进入模型上下文。这三条听起来简单但执行起来需要一套完整的数据流设计。我的做法是在记忆写入前加一道审核审核通过才落库落库的内容带元数据来源、时间、置信度读取的时候按元数据过滤。6.3 主动防御的思路被动防御是出了问题再修主动防御是提前假设会出问题。我在项目里会做几件事红队测试。专门设计一批诱导性输入定期跑一遍看 Agent 会不会被绕过。输出审核。模型输出在返回给用户前过一道审核检查是否包含敏感内容或非预期格式。权限最小化。每个工具只给完成任务所需的最小权限不做超范围授权。操作审计。所有有副作用的操作都记录审计日志可追溯。这套东西做下来初期会拖慢开发速度但长期看是省钱的。我见过太多项目因为一个安全漏洞回滚重做那个成本比前期做防御高得多。7. 这五件事怎么学一条务实的路线7.1 学习顺序不能乱很多人学 Agent 是从框架文档开始的我觉得这个顺序反了。正确的顺序应该是先找一个真实的小需求把它拆到可判定的粒度这是练第一件事。然后手动写提示词反复调感受上下文对输出的影响这是练第二件事。接着给这个任务加一两个工具体会工具调用的契约设计这是练第三件事。再然后把它部署起来加日志、加限流、加超时这是练第四件事。最后加上记忆和审核这是练第五件事。这个顺序的好处是每一步都有产出而且每一步的问题都是真实遇到的不是纸上谈兵。7.2 框架什么时候学框架我建议在第三件事之后再学。因为框架解决的主要是编排问题如果你连工具调用的契约都没设计过学框架就是学了个 API理解不了它为什么这么设计。学框架的时候重点不是学怎么用而是学它怎么解决编排问题。看它的源码看它怎么处理循环终止、怎么管理上下文、怎么做错误处理。这些设计思路比 API 本身有价值得多。7.3 面试和岗位要求怎么看Agent 开发岗位的要求翻来覆去就是这几个词上下文管理、工具调用、编排、工程化、评估。这正好对应我说的五件事。所以准备面试的时候与其背框架的 API不如把这五件事各准备一个真实案例讲清楚你遇到了什么问题、怎么解决的、效果如何。面试官真正想听的不是你会用哪个框架而是你有没有踩过坑、有没有形成自己的判断。框架会过时判断力不会。8. 一些零散但重要的实操心得最后分享几条我在实际项目里攒下来的经验不成体系但都挺有用。关于评估集。评估集要尽早建哪怕只有十条用例。有了评估集你改任何东西都能马上知道是变好还是变坏。没有评估集改提示词就是盲改。关于提示词版本管理。提示词要像代码一样管理每次修改都记录版本和改动原因。我吃过亏改了一版提示词效果变差想回滚发现没存旧版本。关于工具数量。一个 Agent 挂的工具不要超过十个超过之后模型选错的概率明显上升。工具多了就拆 Agent。关于上下文长度。不要迷信大上下文能用检索解决的不要全量注入。我实测下来精简后的上下文效果往往比全量注入更好。关于失败兜底。任何 Agent 都要有兜底路径任务失败时能优雅降级到人工或规则处理。不要假设 Agent 永远成功。关于迭代节奏。Agent 项目的迭代要小步快跑每次只改一个变量改完马上评估。一次改多个地方出了问题根本定位不到原因。关于团队协作。Agent 项目里提示词、工具定义、评估集这些东西要集中管理不能散落在各人手里。我见过因为提示词版本不一致导致线上事故的案例。关于预期管理。Agent 不是万能的它会在某些场景下表现很差。提前和业务方对齐预期明确哪些场景 Agent 处理、哪些场景转人工比事后解释省事得多。这五件事说到底核心就一句话Agent 开发不是调模型是设计一个围绕模型的系统。模型是系统里的一个组件它的输入、输出、边界、失败处理都需要你来设计。把这个系统设计清楚了用什么模型、什么框架都是次要的。