做Agent开发的人应该都有同样的感受Demo永远比生产好用。单轮问答、短链路工具调用跑起来又快又稳一旦把任务拉长到几十个步骤问题就全冒出来了——上下文越堆越长、模型开始忘记最初的目标、一次工具调用失败把后面全带崩。我花了大半年时间专门折腾长任务场景最后发现真正管用的还是那套工程化方案把Agent当成一个需要供电、需要刹车、需要仪表盘的机器而不是一个会说话的模型。这篇文章把我完整的实践整理成教程覆盖Anthropic工程化方案里最核心的Agent循环、工具接入、上下文管理、子代理编排、状态容错和可观测性。不管你是刚开始写Agent的小白还是已经被长任务坑到想放弃的开发者都可以按图索骥。我会尽量把每个选择的背后逻辑讲清楚而不只是丢一堆配置让你抄。1. 为什么长任务这么难先想清楚四个核心矛盾长任务不是多轮对话的加长版它有四个工程矛盾需要先厘清。很多时候方案设计得别扭就是因为没有意识到这些矛盾的存在。1.1 上下文窗口有限但任务需求无限大模型的上下文窗口虽然越做越大几十万token的上限听起来很够用但实际可用性不是单纯看那个数字。每多一轮工具调用历史就往上涨一截几十轮消息、工具返回的JSON、中间产物轻轻松松烧掉几万token。token浪费只是表层的疼真正的隐患是模型在长文本里找不着重点注意力被无关细节稀释决策质量肉眼可见地下降。长任务的第一性约束是你不可能把全程所有信息都留在上下文里。这跟人脑一样短期记忆容量有限要想完成复杂任务必须把信息分级处理——哪些留在工作记忆哪些写进外部文件哪些压缩成摘要。工程化方案里所有的设计包括循环、子代理、状态持久化本质上都在解决这一个约束。1.2 模型的健忘与长期目标保持实测中很常见的一种现象任务刚开始的时候模型还能严格照着最初的指令执行跑到第15轮、第20轮它就开始自己加戏把边界外的事情也干了。这不是模型变笨了而是它对初始目标的注意力权重被大量中间过程稀释了。就像你炒菜炒到最后忘了最开始打算做的是清淡口味——不是锅的问题是任务太长、太多念头挤进来。工程上的解法不是指望模型记住而是把目标外置。每一轮循环都重新强调核心目标或者用一个任务清单文件让Agent随时回查。这一点在后面任务编排章节会细讲这里先记住一个结论目标必须放在模型不需要回忆就能看到的地方。1.3 错误累积小问题滚成大事故Agent的每个动作都有失败率而且失败不是均匀分布的。一个工具返回了格式错误的数据模型可能基于错误数据做下一步推理一步错了后面每一步都建立在错误地基上。这就是雪球效应。长任务里最怕的不是一次大失败而是一连串小失败在几轮之后悄悄改变了任务走向。所以工程化方案会强调认错和纠错机制让模型在关键节点停下来自检在每次工具调用后做一个简短的合理性确认。这看起来浪费了一些时间但长远看是省时间的——返工的代价远高于检查的代价。1.4 中断恢复进程没了任务怎么接着跑长任务跑十几分钟到几个小时都很正常。这段时间里服务重启、模型接口超时、进程崩溃任何一个都能让进度归零。Demo阶段你可以接受重跑一遍生产环境不行。这要求系统具备可恢复性把运行状态以检查点形式持久化让任务能从某个断点继续跑而不是从头再来。这个矛盾是长任务工程化和短对话Demo最大的分水岭。短对话断了大不了重问一次长任务断了一次你可能就想删库跑路。所以状态管理不是可选项而是必修课。2. Agent循环的完整拆解工程化方案的底层骨架理解了长任务的困难下一步就是看工程化方案用什么骨架来解决。核心就是Agent循环也叫agent loop。下面的内容我尽量用大白话讲透。2.1 Workflow与Agent的边界开始设计之前先做一个非常关键的判断你要做的到底是workflow还是agent。早期很多人不分什么需求都上智能体结果是又慢又不可控。判断标准其实很朴素任务的执行路径是否可预测。固定流程——比如每天定时抓数据、清洗、存库——应该用workflow写清楚每一步怎么走需要根据中间结果自主决策的任务——比如让程序自己研究一个陌生代码库并修复问题——才适合agent。把可预测的流程装进Agent等于花大代价买了一个灵活却什么都用不上还要承受它出错的风险。Anthropic的工程化方案里明确区分这两类我强烈建议你在动手写代码之前先想清楚自己属于哪一类。判断错了后面所有设计都跑偏。2.2 三个构建块模型、工具、指令Agent 模型 工具 指令这个三元组是整套方案最核心的抽象。模型是推理引擎决定下一步做什么工具是手脚决定能做什么指令是方向盘决定该不该做、做到什么程度、什么时候停。这三者里最容易被忽视的是指令。很多人的系统提示词就是一句你是一个AI助手这等于让模型在完全不知道怎么服务目标的情况下开始自主行动。好的指令要写清楚五件事目标、约束、可用工具概览、执行步骤偏好、终止条件。后面讲到子代理任务描述时我会给一个具体的五段式模板那对主代理同样适用。2.3 一个最小可运行的Agent循环理解了三个构建块再看Agent循环就简单了它就是一个while循环循环里做三件事——把当前状态发给模型模型返回决策回答或调用工具如果是工具调用则执行并回填结果然后继续循环直到模型说完成。官方SDK替你封装好了这套循环但你必须理解它才能调参。下面是我常用的一个最小实现思路和官方方案一致可以当模板用def run_agent(instructions, tools, model, max_steps30): messages [{role: system, content: instructions}] for step in range(max_steps): response model.chat(messages, tools[t.schema() for t in tools]) if response.stop_reason tool_use: messages.append(response.message) for tc in response.tool_calls: result tools.execute(tc.name, tc.input) messages.append({role: tool, tool_call_id: tc.id, content: result}) continue if response.stop_reason stop: return response.text if response.stop_reason pause: # 主动暂停去问人 human_reply ask_human(response.text) messages.append({role: user, content: human_reply}) continue raise MaxStepsExceeded(hit max steps)这段代码有三个关键点。第一系统指令只放一次它是Agent的宪法不会被对话长度稀释所以核心目标、边界、退出条件都要写在这里。第二stop_reason是循环的控制器tool_use表示要调用工具stop表示正常完成pause表示需要人工介入。第三max_steps是硬兜底不管模型多能聊超过步数直接中断宁可不完成也不能无限烧钱。2.4 循环停止条件什么时候该收手工程化方案里有一个很妙的设计它把请求人工帮助当成Agent的一个合法动作而不是未定义行为。模型在不确定的时候可以停下来带着当前状态问人类系统UI弹一个确认框得到回答后继续跑。这比让Agent硬着头皮瞎猜要安全得多。我实际跑任务时最常遇到的一个场景让Agent做一个涉及删除数据的操作它犹豫了触发pause人类确认后它继续执行。没有这个机制的话它要么自作主张把数据删了要么什么都不做卡死在那个环节。这两种我都经历过体验都很糟糕。还要注意停止条件一定要显式定义不要只依赖模型的自觉。至少要同时提供四个条件完成标志要求模型最终输出结构化结果、最大步数、最大token数、超时时间。哪个先触发就停哪个。少一个条件你的Agent循环就有一种你没预料到的方式烧掉你的预决算。3. 工具设计与MCP接入把Agent的手接好模型再聪明没有好用的工具也是空谈。长任务里工具的质量直接决定最终结果质量这一章说几个踩过的坑。3.1 工具描述与Schema的写法模型要正确使用工具靠的不是运气是工具描述里是否有足够的信息。很多人的工具Schema只有一句搜索商品模型根本不知道什么时机该用、输入格式是什么样的。一个合格的工具定义要包含使用时机、输入参数含义、输出结构、副作用、出错时的表现。一个我后来觉得比较好用的工具定义长这样{ name: search_products, description: 在商品库中按关键词搜索商品返回商品列表、价格与库存。适合在用户查询商品信息时使用。, input_schema: { type: object, properties: { keyword: {type: string, description: 搜索关键词}, category: {type: string, enum: [electronics, books, clothing]}, page: {type: integer, default: 1} }, required: [keyword] } }写description的一个技巧是站在模型的视角想象它拿到了这个工具看到什么描述才能准确判断现在该用它吗怎么填参数。另外能用枚举约束就不要留自由文本比如排序字段直接给enum模型选错的可能性会大幅下降。这个细节能在长任务里省下很多轮无谓的来回试错。3.2 工具粒度从一次失败的工具设计说起工具粒度是个非常微妙的设计题。工具太大模型只能整块调用没有中途纠偏的余地工具太小一次操作要拆成七八次调用上下文爆炸且每多一次调用就多一分失败的可能。我见过最极端的失败案例是把解析网页并提取正文做成一个大工具模型无法指定只提取价格那一行反过来有人把打开文件和读取第N行拆成两个工具搞得模型每处理一个文件都要来来回回调用十几轮。我的建议是以人类完成该子任务时的自然操作单元作为粒度基准。人类不会每次读一行也不会把整个文件分析一次做完——介于两者之间一次调用完成一个有明确输入输出的原子操作。判断这个粒度是否合适你可以问自己一个问题模型调用这个工具之后大概率还需要用另一个工具补充信息吗如果经常需要粒度就拆小了如果每次都只能整块执行粒度就太大了。3.3 MCP的三类原语与一个Server的接入流程工具越来越多之后接入就成了问题。每个工具都写进Agent主程序几十个工具把代码库塞得乱七八糟而且权限没法隔离工具可以随便访问它不该碰的数据。MCPModel Context Protocol把这件事标准化了。MCP定义了一套Server/Client架构工具实现方跑在独立Server进程里Agent作为Client通过协议调用。Server暴露三类原语Tools可执行的动作、Resources可读取的数据、Prompts可复用的提示模板。接一个MCP Server的流程很简单就三步写一个Server声明工具列表并实现处理函数在Agent配置里指定Server的连接方式本地用stdio建进程远程用Streamable HTTP启动后在Agent里把工具列表导入上下文。这套标准最大的收益是生态复用。同一个工具Server今天留给你这个Agent用明天那个Agent也能接不用重新适配。而且权限边界天然隔离工具运行在独立进程Agent拿不到Server进程的内存Server也不该访问Agent所在系统的敏感目录。长任务系统里有大量工具的时候MCP这种隔离方式真的能救命。3.4 工具失败时的错误返回设计工具一定会失败。会失败这件事本身没有设计好才是灾难。我最开始的实现是工具出错时返回一行字符串error: something went wrong模型根本不知道接下来该怎么办。后来改成结构化的错误返回包含错误码、可读信息、可选的恢复建议效果立刻不一样了。举个例子一个数据库查询工具失败时返回这样的结构{ error_code: DB_TIMEOUT, message: 查询超时超过3秒, suggestion: 建议缩小查询范围或改用search_users_by_filters工具 }模型看到这个之后可以自己决定下一步重试一次、换一种工具、还是停下来问人。记住错误信息不只是给人类看的日志它是Agent下一步决策的输入。写不清楚模型就会乱猜一猜就错一错就滚雪球。4. 上下文生命周期管理压缩、记忆与缓存的配合长任务跑到几十轮之后上下文管理是绕不开的坎。这一章讲清楚怎么让上下文不失控。4.1 截断、摘要与混合策略的取舍逻辑最简单的策略是截断——早期的消息直接丢只保留最近N轮。好处是省token、实现快坏处是早期的关键信息可能已经进了后面决策的前提丢了它等于拆了大楼的地基。稍微聪明点的是摘要定期把旧消息交给模型生成一段结构化摘要替换掉原文。摘要保留了大方向但会丢细节——一个具体的ID、一个确切的数字都可能在一次摘要之后悄悄消失。成熟的方案都是混合策略。我给一个对比表格策略原理适合场景主要风险简单截断直接删最早消息轮数少的短任务关键信息丢失摘要压缩模型总结旧消息替换原文本中长任务细节失真混合策略设阈值触发压缩摘要为主、截断兜底真正的长任务实现复杂度较高实际落地时给上下文设一个阈值比如超过80k token时触发压缩压缩时对对话类内容做摘要对工具返回的大块数据直接截断或索引化最后用截断做兜底。这是一套工程权衡没有银弹要根据任务类型反复调。4.2 三层记忆结构与持久化我在实战里把记忆分成三层瞬时记忆也就是当前窗口内的消息模型直接可见工作记忆指被摘要化的中期信息每轮循环开始前注入长期记忆存在外部存储里数据库、向量库或者普通文件都行需要时按需检索。这三层对应不同的读写频率和成本。瞬时记忆最贵但最准长期记忆最便宜但要靠检索。很多人的错误是把所有信息都塞进瞬时记忆然后抱怨上下文不够用。正确姿势是主动把不需要模型逐字看到的内容降级到工作记忆或长期记忆让模型始终在一个轻盈的上下文里做决策。具体操作举个例子某次工具调用返回了一个1万token的JSON模型需要其中300个token的内容。那就不要把这1万token放进历史而是提取关键字段后把摘要存进工作记忆甚至把原始数据放到一个文件里只在上下文里留下文件路径。4.3 Prompt Caching怎么把成本打下来长任务的token消耗是很多人忽略的隐性成本。以Claude这类大模型API为例系统指令、工具定义、部分长上下文片段在每轮循环里都是重复发送的这部分token费用属于纯浪费。工程化方案给出一个很明确的解法prompt caching。把稳定的上下文前缀缓存起来后续请求命中缓存时输入成本大幅降低延迟也更低。具体到长任务场景工具定义和系统指令是每次循环都不变的把它们放进缓存前缀几十轮循环跑下来省下的token相当可观。我在一次48步的长任务测试里做过对比开启缓存之后输入token成本大概降了一半首词延迟也明显缩短。如果你的任务步骤数很多这一步几乎必须做否则光token费用就能让你的项目停在Demo阶段。4.4 上下文管理的实操参数分享一组我常用的起点参数你可以先照抄再根据你的任务类型调整硬性上下文上限设为窗口的60%超过就触发压缩摘要间隔设为每10轮或每30k token一次缓存前缀包括系统指令、全部工具定义、最后一条用户消息压缩时保留最近3轮完整消息更早的合并进摘要这组参数跑大多数任务都能稳住。不过如果任务类型偏数据分析大块表格数据返回频繁建议把摘要间隔缩短因为表格数据在摘要里最容易失真。数字一旦被概括成大约几千后续步骤就没法精确处理了。5. 任务编排主代理与子代理的分层协作复杂长任务单靠一个Agent硬扛大概率会翻车。这一章讲怎么用分层协作把任务拆开、并行、合并。5.1 为什么单代理跑长任务容易迷失单代理一口气跑完一个复杂任务我在早期项目里试过很多次。结论是10步以内没问题30步之后再往回看它经常会偏离最初的目标。原因很现实每多一轮交互初始指令在上下文里的相对权重就低一点中间任何一个分支决策做得不理想后面就会沿着偏的方向越走越远。这就像一个人同时负责管钱、做饭、招待客人、打扫卫生事情一多每件事都做不精。工程上解决问题的思路不是逼单代理更自律而是引入分工主代理只做规划、协调、验收把具体的细分任务丢给子代理去执行。5.2 子代理的任务描述怎么写子代理本质上是临时创建的、带独立上下文的一次性Agent所以它最需要的是自包含的任务说明。我踩过一个大坑给子代理的任务描述里写了处理一下之前说的那个数据结果子代理完全不知道之前说的是什么因为它没有父代理的完整记忆。后来我把任务描述固定成五段式目标一句话说清要交付什么输入直接给出数据或引用ID不要依赖父上下文约束权限、边界、禁区输出格式结构化报告模板退出条件什么情况算完成什么情况算放弃有了这五段子代理的完成质量稳定多了。这也意味着父代理在拆任务时要多做一步——把上下文转译成文本而不是把消息历史直接丢给子代理。子代理拿到一段自包含的任务说明比拿到几十条父代理的聊天记录高效得多。5.3 并行子代理与结果合并的工程细节长任务里很多子任务是天然并行的比如调研三个竞品的价格可以拆成三个独立子代理同时跑。并行能大幅缩短墙钟时间但也带来新问题结果合并和副作用隔离。我的做法是让每个子代理把结果写入独立的临时文件或对象存储父代理只收集各自的摘要引用。这样就算某个子代理返回了超大文本也不会挤爆父代理的上下文。并行还要注意资源上限比如同一时间最多跑3个子代理避免API限流把整个任务拖垮。限流之后同时等4个子代理恢复比串行跑还慢。5.4 子代理的止损机制子代理也需要止损。实测里经常遇到一个子代理在一个分支里绕圈修一个bug修了五轮还没修好但因为它每次都有微小进展所以一直不退出。如果没有上限它会一直跑到超时。我的方案是给每个子代理设两个硬指标最大步骤数比如15步最大失败次数比如3次。触发上限后立即停止把未完成原因 已尝试的方案 中间产物打包成一个报告交回父代理由父代理决定是换一种方式还是放弃整个子任务。切记及时止损的子代理报告比一个硬撑着跑完全程但结果不可靠的子代理有价值得多。失败的子代理至少能告诉你哪里走不通硬撑的结果可能连哪里出了问题都看不出来。6. 状态与容错让长任务在故障后还能接着跑长任务必然遇到进程崩溃、接口超时、服务重启。状态与容错设计决定了你是损失一步还是损失整个任务。6.1 检查点该保存什么很多人的检查点只存了消息历史恢复之后发现模型上下文是接上了但任务真正要推进的目标反而丢了。完整的状态至少应该包含四部分消息历史模型视角的完整对话任务进度已完成步骤、当前步骤、下一步候选关键事实ID、路径、重要参数防止压缩后丢失运行统计步数、token用量、错误次数把这些保存成JSON放进数据库或对象存储任务随时可以存档。我的习惯是每次工具调用后都写一次检查点这样最坏情况只会丢一步。6.2 重试策略哪些错误值得重试不是所有失败都该重试。我把错误分成三类错误类型典型例子重试策略瞬时故障网络超时、API限流、服务端5xx指数退避重试逻辑错误参数不合法、数据格式不对不重试回传模型调整策略根本性错误工具被删除、权限被吊销不重试直接止损并告警瞬时故障值得重试且要用指数退避第一次等2秒之后翻倍逻辑错误重试大概率还是同样失败应该把错误信息回传给模型让它自己重新规划根本性错误重试毫无意义直接进入人工处理流程。把这三种情况分开处理能少烧很多token也少很多莫名其妙的失败。6.3 工具幂等设计在Agent里的应用长任务中同一个工具被调用多次很常见尤其是重试场景。如果工具不是幂等的第二次执行就可能产生重复副作用——给用户发两次推送、创建两个一样的订单。凡是会产生副作用的工具都要做幂等保护。实现方式有很多最简单的是调用方生成一个request_id服务端对相同request_id去重或者工具内部检查如果目标资源已存在就返回现有引用而不新建。在设计新工具时优先考虑幂等性比事后补救容易得多。一旦某个工具在线上产生了重复副作用排查和修复的成本远高于一开始做的防御设计。6.4 让模型自己修复错误的反馈回路Agent区别于传统程序的强项之一是自我修复能力但这个能力需要你给链路留出反馈空间。具体做法在循环里每次工具调用失败后不要让错误直接叠加上去就完事而是把期望结果、实际结果、差异分析结构化地发给模型甚至明确要求它输出一个修正计划再行动。实测中这一小步能明显降低连续失败的概率。还有一个实用技巧让模型在关键步骤完成后写一行进度日志更新任务文件。如果日志内容和预期不符你能早一点发现跑偏而不是等到最后验收时才发现结果完全不对。这就相当于给Agent装了一个心跳监测器。7. 生产环境落地可观测性、评估与避坑清单到了生产环境技术本身反而不是最大的问题了。运行了一段时间之后最痛苦的是排查问题的时候发现没有数据。7.1 轨迹记录与成本核算的字段设计长任务的黑盒属性在排查问题时最让人头疼。我的做法是给每轮循环都写一条结构化日志字段包括step_idstep_typethink / tool / human模型输出截断到合适长度工具名称工具输入摘要工具输出摘要状态码耗时输入token数、输出token数有了这些数据任务跑完你随时能回放它是怎么一步步走到最终结果的。成本核算也很简单每轮记录的tokens乘以单价随时能拉出一份成本报表。生产环境里这些日志还能用来做告警比如最近100次任务中工具调用失败率超过30%就是一个明确需要人工介入的信号。7.2 评估集怎么建聊了这么多最后绕不开一个问题怎么知道你的Agent真的变好了。我的经验是给长任务建一套离线评估集。从真实需求里抽50个左右典型任务每个任务都有明确的完成标准和预期产物跑完自动判定成功或失败。然后记录几个核心指标任务完成率平均步数平均token消耗工具调用失败次数需要人工介入的次数注意只盯着成功率不够。同样成功率的两个版本可能一个便宜一个贵token消耗和步数也要纳入对比。每次改动工具描述、指令、编排逻辑都用这套数据集做回归测试。别靠这次跑起来感觉挺顺来决策感觉会骗人。7.3 一套避坑清单最后列一个避坑清单基本每个坑我都踩过工具描述含糊不清模型靠猜来用工具一猜就错。解法是把工具description当产品文案来写。没有设置最大步数模型陷入循环账单肉眼可见增长。所有Agent跑起来之前先设上限。上下文管理只做截断早期关键信息丢光模型在残缺信息里瞎编。至少用摘要保留主线。子代理任务描述依赖父上下文子代理拿不到共享记忆输出一堆不知所云的结果。任务描述必须自包含。工具非幂等重试导致重复副作用生产环境直接是事故级别。缺少可观测性出问题只能靠肉眼盯日志排查效率极低。以上任何一条踩中长任务系统的稳定性都会掉一个档次。建议在系统上线前逐条对照检查每一条都能省掉你未来几天甚至几周的排查时间。我自己实际跑长任务的经验里收益最大的一件事是给任务本身建好一个进度文件让Agent每完成一个关键步骤就更新它。这个文件既是检查点、又是上下文压缩的摘要来源、还是人工介入时的上下文一举三得。如果你只记住这篇文章里的一件事我希望是这一件。长任务开发说到底是把模型能力翻译成系统能力的过程翻译的质量全靠工程细节。模型本身的能力已经很强真正的差距在你怎么构造循环、怎么设计工具、怎么管理状态。希望这套方案能帮你少踩几个坑剩下的坑咱们下次继续填。