1. 上下文管理：Agent的“短期记忆”是怎么被维护的在做Agent运行时拆解之前，我先说一个真实发生过的场景。某次我在本地跑一个多步骤的数据整理Agent，它已经执行到第27步，前面26步全部成功，结果第27步因为上游接口超时直接抛异常。我重启进程准备让它继续，却发现它连“自己刚才在做什么”都说不清楚——因为我没有把上下文落盘。那一刻我意识到，理解Agent的运行机制，核心就是理解上下文、检查点、任务恢复这三件事是怎么配合的。标题里的“上下文”是第一个关键点。LLM本身是无状态的，每次调用模型，你需要把之前对话和中间结果重新喂给它。所谓上下文管理，本质上就是决定“这次调用我要把哪些历史信息放进窗口里”。1.1 上下文边界：不是所有历史都该进窗口上下文窗口是有限资源。现在主流模型的窗口虽然越来越大，但大窗口不等于你应该把所有东西都塞进去。原因有两个：一是成本，token是按量计费的，塞进窗口的每一段话都在烧钱；二是注意力稀释，窗口塞得太满，模型反而抓不住重点，尤其是中间部分的信息容易“被忽略”。我见过不少初筛方案，直接把Agent每轮的工具返回结果全部追加到消息列表里。跑个二十步，窗口就被工具输出的JSON占满了，模型开始答非所问。所以在设计上下文时，第一件事就是分级：哪些信息必须留在窗口里，哪些可以压缩，哪些可以归档到外部存储。必须留在窗口里的，我总结下来是这几类：用户的核心目标与最新指令，这是最高优先级。当前执行到哪一步、已完成哪些步骤的简短摘要。本轮循环中尚未落定的临时变量和待决策信息。与下一步决策直接相关的关键结果，比如查询返回的核心数字。可以压缩的，是历史对话的详细内容、中间过程的冗长日志、重复出现的工具调用记录。可以归档的，是已经完成的子任务完整结果、大段原始数据。归档不等于删除，而是存到检查点或外部存储里，需要用的时候再按需捞回来。1.2 三条主流压缩路径：截断、摘要、结构化归档上下文压缩不是只有一种做法，实际工程里通常按场景组合使用。第一种是滑动窗口截断，也就是只保留最近N轮对话。实现简单，但对早期信息会有影响，如果用户的原始需求很长，截掉之后模型可能“忘记初心”。所以滑动窗口一般只截中间，头部保留系统提示和原始目标。第二种是层次化摘要。每完成一个子任务，就让模型把这段过程总结成两三句话，把摘要保留在上下文中，详细内容移到外部存储。代价是多一次模型调用，换来的是窗口利用率大幅提高。我实测下来，摘要最好在“子任务边界”触发，而不是每隔固定轮数触发，这样摘要的语义完整性更好。第三种是结构化归档。把Agent的状态抽成固定的字段，比如当前阶段、已完成清单、待办事项、关键参数，以结构化数据的形式放在上下文里。模型每次读到的是一张“状态表”，而不是一长串对话。这种方式最适合流程固定的任务，也是后面检查点设计的基础。1.3 上下文一致性：压缩后模型还是会“精分”压缩会引入一个隐蔽问题：一致性。比如说，上下文里把某个中间结果摘要成了“用户偏好A方案”，但后续某一步实际拿到的是“用户偏好B方案”，模型就可能两边矛盾、来回摇摆。我在一个模拟项目X里就遇到过，Agent在压缩上下文后突然改口，把已经确认过的参数又推翻重来，导致整个流程回退。解决这个问题，我的经验是：在上下文里维护一个不可被压缩的“状态锚点”。这个锚点用固定格式记录不可变事实，比如“用户ID、目标ID、已确认参数、版本号”。压缩可以压缩对话内容，但状态锚点必须原样保留，并且每次状态变更时更新版本号。模型如果发现版本号不一致，就应该以锚点为准，而不是猜测。另外一个细节是，压缩后要给模型一个明确的提示，告诉它“之前的历史我帮你精简了，精简版里包含所有关键决策，如果有冲突，以最新状态为准”。别小看这句话，它能明显减少模型在压缩后的“精分”概率。2. 检查点：给Agent的运行状态拍快照如果说上下文是内存，那检查点就是持久化存储。没有检查点的Agent就像一台不接UPS的服务器，一次断电全部归零。检查点的核心价值，是让Agent的运行状态可以随时被“存档”和“读档”。2.1 检查点到底要保存什么很多人以为检查点就是把对话历史存一下，这是误区。对话历史只是最表层的东西，真正要保存的是完整的状态视图。我整理过一份检查点必备清单：类别具体内容说明任务元信息目标描述、任务ID、创建时间、版本号用于追溯和恢复定位上下文快照系统提示、状态锚点、压缩后的摘要与当前上下文保持同步执行进度当前步骤索引、已完成步骤清单、失败重试记录决定恢复时从哪继续状态变量关键参数、中间结果引用、外部存储的句柄保证变量不丢队列与栈待处理任务队列、函数调用栈用于循环执行场景资源占用情况已消耗token数、当前并发数、租约信息用于恢复后继续管控这份清单看起来内容多，但实际落地时就是一个大JSON对象。我习惯在JSON里加一个schema_version字段，因为机制迭代后老检查点的格式会变，没有版本号你根本没法做迁移逻辑。2.2 检查点序列化：JSON之外还有什么选择JSON是最通用的选择，可读性好、调试方便，配合schema校验也不容易出错。但如果状态里有大量二进制数据，比如嵌入向量、图片特征，JSON就不合适了。这时候可以分两部分：元数据和轻量状态存JSON，重量级数据存对象存储，JSON里只放引用。序列化还有一个容易忽略的点：非可序列化对象。比如某个Agent持有了一个数据库连接池或一个内存中的锁，这些东西没法直接落盘。所以在做检查点之前，必须定义好“边界对象”的保存方式。我的做法是，凡是持有关联资源（连接、句柄、锁）的组件，都实现一个钩子接口，检查点触发时先执行释放或重建逻辑，恢复时再重新初始化。这个设计一开始就要做，否则后面加一个持有资源的模块，检查点就会悄悄漏掉它。2.3 检查点写入策略：同步、异步与Compaction检查点的写入频率直接影响两个指标：恢复的完整度（RPO）和运行性能。写太频繁，IO压力大，Agent主循环被拖慢；写太少，崩溃时丢失的进度多。同步写入阻塞，实时性最高，但性能最差。异步写入性能好，但内存中的状态先变化、落盘有延迟，崩溃的最后几秒状态可能丢。折中方案是异步批量写入加定期强制落盘。我常用的是“阈值触发+定时触发”双策略：状态变化超过一定次数后异步写一次，同时每30秒强制同步一次。这样在性能和可靠性之间取平衡。还有一个机制叫Compaction，合并压缩历史检查点。Agent跑到第100步时，第1步的检查点其实已经没有恢复价值了，保留它只会占空间。所以定期把老检查点合并成“阶段性断点”，只保留每个任务阶段的起始状态和最终状态，中间的细粒度检查点清理掉。这能大幅减少存储成本，尤其是跑大批量任务时。3. 任务恢复：从断点继续执行的关键设计检查点只是存了状态，真正难的是“怎么恢复”。任务恢复不是简单地读回JSON然后接着跑，它涉及恢复粒度、幂等性、脏状态清理这三个核心问题。3.1 恢复粒度：指令级还是步骤级我先说结论：恢复粒度决定了你恢复逻辑的复杂度，也决定了Agent崩溃后损失的范围。指令级恢复，意思是把每一步细粒度操作都记录下来，恢复时从最后一条未完成的指令继续。优点是精度高，缺点是记录成本大，而且步骤之间的依赖关系很难理清。步骤级恢复，是把任务划分为多个子步骤，恢复时从最后一个未完成的子步骤开始。粒度粗一些，但逻辑清晰，实现成本低。我个人的建议是，除非你的任务是纯顺序、无副作用的流水线，否则用步骤级恢复就够了。绝大多数Agent任务，子步骤内部也就几步操作，重跑这几步的成本远低于实现指令级恢复的复杂度。3.2 幂等与重放：重复执行不可怕，可怕的是副作用恢复必然带来重放，重放就必然遇到幂等性问题。一个操作如果重复执行会产生不同的结果，它就是有副作用的。典型的例子是“发送邮件”和“创建订单”。Agent在第一步发了邮件，第二步崩溃了，恢复后从第一步重新跑，邮件就被发了两次。所以任务恢复设计的真正难点，不是“如何恢复”，而是“如何让恢复过程中不会产生重复副作用”。解决这个问题有三种思路。第一种是操作前检查，在执行有副作用的操作前，先查询一下目标资源的状态，如果发现已经创建过了就直接跳过或复用。第二种是操作去重，给每个副作用操作生成一个唯一幂等键，下游服务支持按幂等键去重，重复请求只生效一次。第三种是动作日志，把每一步的“意图”和“结果”都记下来，重放时先查日志，如果这一步已经被标记为完成，就跳过执行直接引用结果。这三种思路可以组合。对于外部API调用，优先靠幂等键；对于内部状态变更，靠动作日志；对于资源型操作，靠状态检查。我实际项目中，用“动作日志+幂等键”的组合就能覆盖绝大多数场景。3.3 脏状态清理：恢复后先做一致性校验恢复执行前，必须做一次脏状态清理。所谓脏状态，就是Agent崩溃前留下的半成品。比如它已经创建了一个临时文件，但还没用完就崩了；或者它持有了一个租约锁，崩溃时锁没释放。我见过一个真实的线上事故：Agent在恢复后，发现某个临时目录里残留了上次崩溃的半截文件，它误以为那是一份完整的中间结果，直接拿来当输入，最后产出了一份错得离谱的报告。排查了半天才发现是脏数据污染。所以恢复流程必须包含一步：校验。校验规则包括：每个临时文件是否有完整标记；每个资源锁是否持有者还存在；每个中间结果是否满足格式约束。校验不通过的直接清理或重建。这一步放在恢复流程的最前面，宁可多花几毫秒，也不能带着脏状态往下跑。4. 循环执行：Agent主循环的骨架与保险栓Agent和普通脚本最大的区别在于，它是“自己决定下一步做什么”的。这就意味着，它的执行结构不是一条直线，而是一个循环：观察当前状态，做出决策，执行动作，更新状态，再观察。循环是Agent的心脏，但循环也是最容易失控的地方。4.1 标准主循环结构一个规范的Agent主循环，伪代码大致是这样的：while not should_terminate(state): # 1. 从上下文中读取当前状态锚点 context = load_context(state) # 2. 让模型决策下一步动作 action = model.decide(context) # 3. 执行动作，拿到结果 result = execute(action) # 4. 更新状态（变量、进度、上下文） state = update_state(state, action, result) # 5. 触发检查点写入（按策略） maybe_checkpoint(state) # 6. 记录循环日志，供可观测性使用 trace.append(action, result)这个结构看起来简单，但每个环节都有坑。第2步的decide可能返回非法动作；第3步的execute可能超时或抛异常；第4步的update_state可能因为字段嵌套过深导致序列化失败。所以真正生产级的循环，还需要在每步外面包一层异常捕获和重试逻辑。4.2 终止条件：三种退出路径循环必须有明确的终止条件，否则就是死循环。我梳理过，Agent循环的正常终止路径有三种：第一种是目标达成，也就是状态锚点里标记的所有待办事项都完成了。这是最理想的情况。但要注意，模型判断“完成”并不可靠，有些模型会过早宣布完成。所以“目标达成”的判断不能只听模型一句话，要结合步骤日志和状态校验。我习惯在终止前做一次“最终检查”，让模型输出一份完成确认清单，再把清单和状态锚点比对。第二种是用户中断。用户发来“停一下”或者“改个目标”，Agent应当能及时响应。实现方式是每轮循环开始时检查中断信号，而不是等当前动作执行完。这里要注意，如果正在执行的是一个长耗时工具调用，要配合超时机制，否则中断信号要等很久才能生效。第三种是失败退出。连续多次重试仍然失败，或者关键条件不满足，Agent应当主动放弃而不是硬撑。这时候要做的是“优雅降级”：把已完成的部分保存好，把失败原因写清楚，把未完成的子任务标记好，方便下次从断点恢复。4.3 防死循环：最大迭代数、行为检测与熔断即使有终止条件，模型也可能在条件不满足时反复执行相似的动作。比如它反复调用同一个搜索接口，搜出来的结果都是同一个，然后它又继续搜。这种情况模型自己意识不到，需要外部机制兜底。最简单的是最大迭代次数，跑满200轮强制终止。这个数字按任务复杂度设置，太小的会误伤长任务，太大的起不到保护作用。我建议设置成任务预估步数的两到三倍。进阶一点的是行为重复检测。记录最近若干轮的动作签名，比如动作名称加参数摘要，如果发现连续多轮的动作高度相似且状态没有实质进展，就触发警告。我常用的指标是“最近五轮内状态变量变化幅度”，如果变化幅度低于阈值且动作重复度高，就判定为原地打转，中断循环并提示人工介入。再加上熔断机制就更稳了。熔断分两个维度：错误率熔断和资源熔断。错误率超过阈值时，循环暂停，先把错误模式分析清楚再决定是否继续；资源消耗超过预算时，直接熔断，防止一个失控Agent烧完整个批次的额度。这三个保险栓叠在一起，基本能把死循环问题堵死。5. 资源管控：Token、内存、并发一个都不能少资源管控是Agent运行机制里最容易被忽视、但出事最严重的一环。我见过不少团队，上下文、检查点、循环都做得很规范，结果在一次大批量任务面前，token额度一小时烧完，或者内存被中间结果撑爆。资源管控不是“优化”问题，而是“生存”问题。5.1 Token预算：给每个Agent一张信用卡Token是Agent运行最核心的资源，也是最贵的资源。做预算管理，本质上就是给每个Agent一张信用卡，设定额度，超额就停。Token预算要分两层：单次会话预算和全局预算。单次会话预算决定一个Agent任务最多能消耗多少token，超出就终止任务并保存检查点。全局预算决定整个批次的token上限，用于多Agent并发场景下的总量控制。预算的执行方式，是在循环的每一步累加实际消耗。这里有个容易忽略的点：消耗的不只是模型输入输出token，还包括工具返回结果占用的token、上下文压缩时额外的摘要token。所以统计口径要统一，建议按“每次调用模型时的输入token + 输出token + 估算的工具结果token”来算。宁可算多，不能算少。超出预算后的处理也值得设计。最简单的是硬性终止，但不够优雅。更好的做法是分级处理：达到预警线时，自动切换更经济的模型、压缩上下文；达到硬顶时，保存检查点、记录失败原因、终止任务。这样至少能保住已完成的部分。5.2 内存与对象生命周期Agent运行时的内存消耗，主要来自两块：一是上下文中的大对象，比如长文档、图片、超大JSON；二是历史中间结果的累积。大对象进上下文的场景很常见，Agent读了一个几百KB的文档，把这个文档原样放在消息里，内存立刻飙升。更好的做法是预处理：文档先切块、抽取摘要或转成向量，放进上下文的只是摘要和引用，原始内容放外部存储。按需读取。中间结果累积是更隐蔽的问题。Agent每跑一步，把工具返回结果append到一个列表里，跑完50步这个列表可能已经很大了。如果这些中间结果后续用不到，就应该及时释放，只保留最近的几个或汇总后的结果。我习惯在循环里加一个“历史结果回收”逻辑：超过N步的原始结果直接释放，只保留摘要或引用。还有一类内存问题是连接泄漏。Agent如果频繁创建HTTP客户端、数据库连接池，又忘记关闭，跑几百轮后可能把连接数占满。这块要靠资源池化来解决：连接统一管理、统一复用、定期清理。自定义会话池、连接超时这些都要配上。5.3 并发与限流：多Agent时的共享池设计当你有多个Agent并发执行时，资源管控的复杂度立刻上了一个台阶。每个Agent单独限流还不够，因为它们会竞争同一个模型API的配额、同一批下游接口的调用权限。我踩过的一个坑是：10个Agent并发跑，每个Agent自己的token预算都设了上限，结果它们加起来把单日模型API配额打爆了。因为API配额是账户级的，不是会话级的。所以多Agent场景必须做共享池。共享池的核心是按优先级分配。我设计的方案是：把一批任务分成高优先级（用户在线等待）和低优先级（后台批量处理），低优先级Agent尽量在空闲时段跑，高优先级Agent优先拿配额。池子的配额用令牌桶实现，每个Agent每次调用模型前要“取令牌”，取不到就排队等待或降级。限流还要考虑下游接口的限制。很多外部API有QPS限制，多个Agent同时调同一个接口，很容易触发限流报错。解决方案是给每个下游接口建一个专用的限流队列，所有Agent的请求统一走队列。这比在每个Agent内部做限流要可靠得多。6. 端到端流程：一个真实任务的完整生命周期前面五节是把各个机制拆开讲，现在把它们串起来。一个标准的Agent任务，从接收到完成，其实是一条清晰的状态流水线。理解这条流水线，你才能真正看懂框架在设计什么。6.1 状态机：从初始化到完成我把Agent任务的生命周期归纳为六个主状态：状态触发条件主要动作初始化任务被接收加载配置、初始化上下文、建立资源池规划上下文就绪拆解目标、生成子任务列表、写入状态锚点执行子任务就绪进入主循环、按序执行、更新状态暂停用户中断/资源预警保存检查点、释放临时资源、等待指令恢复用户指令/资源恢复读取检查点、校验一致性、回到执行态完成所有子任务完成输出结果、清理资源、归档检查点这个状态机的好处是，每个状态的边界很清楚，崩溃发生在哪个状态一目了然。比如崩溃在执行态，恢复时就回到执行态，从最后的检查点续跑；崩溃在暂停态，恢复时先做资源重建，再回执行态。6.2 版本演进：从v22到v23.3我调整了什么标题里提到的23.3，是我维护的一套Agent运行时机制里的一个重要版本。这个版本相比之前，主要改了三个地方。第一个改动是“检查点结构升级”。旧版本把检查点直接存成一个大JSON，越跑越大，恢复时要反序列化很久。23.3里改成“分层检查点”：元数据、状态快照、历史归档分开存。恢复时先加载轻量的元数据和状态快照，历史归档按需懒加载。实测恢复时间缩短了将近一半。第二个改动是“上下文压缩策略从固定轮数触发改成状态变化触发”。旧版每五轮压缩一次，不管这五轮有没有实质进展。新版改为当状态锚点发生变更、且上下文长度超过阈值时再压缩，减少了无效压缩次数，也降低了上下文“精分”的概率。第三个改动是“引入了循环行为检测保险丝”。旧版只有最大迭代次数兜底，碰上模型原地打转，能把你几十万token干烧完。23.3里加上了动作签名比对和状态变化幅度检测，连续多轮无实质进展就自动熔断，省了不少冤枉钱。这三个改动不是拍脑袋想出来的，都是真实线上跑出来的痛点。第一个是被恢复时间折磨出来的，第二个是上下文精分事故逼出来的，第三个是烧了两次token额度后不得不加的。所以如果你在用类似的Agent运行时，我建议你也把“运行机制”当成一个可以持续迭代的工程，而不是写定就不动的。6.3 可观测性：没有日志的Agent就是一个黑盒最后一个环节，也是很多人最后才想起的：可观测性。Agent和传统程序不一样，它的每一步决策都是模型生成的，不记录日志，你就永远无法追溯它为什么做出某个决定。我在每个Agent任务里都会输出三类日志。第一类是决策日志，记录每轮循环模型返回的动作和它参考的关键上下文片段；第二类是执行日志，记录每个工具调用的请求参数、返回结果和耗时；第三类是资源日志，记录每步的token消耗、内存占用和队列状态。三类日志拼起来，就能完整还原一个Agent从接收到完成的全过程。有了日志还不够，还要有可视化的trace。我的做法很朴素，就是把日志按“任务ID+步骤ID”组织成树状结构，配合时间线展示。出问题时，按任务ID一查，从决策日志定位到是哪一步的决策失误，再配合当时的上下文快照，基本五分钟内能定位问题。这套机制，我现在维护的每个Agent项目都会默认带上。坦白说，Agent运行机制没什么高深莫测的魔法，它就是一套“状态保存、恢复、循环、控资源”的工程组合拳。难点不在于某个单独的技术，而在于它们之间的咬合：上下文失效了检查点来找补，检查点出错了恢复逻辑来兜底，循环失控了资源管控来熔断。把这套咬合关系理顺了，Agent跑得再久，你心里也有底。
1. 上下文管理：Agent的“短期记忆”是怎么被维护的在做Agent运行时拆解之前，我先说一个真实发生过的场景。某次我在本地跑一个多步骤的数据整理Agent，它已经执行到第27步，前面26步全部成功，结果第27步因为上游接口超时直接抛异常。我重启进程准备让它继续，却发现它连“自己刚才在做什么”都说不清楚——因为我没有把上下文落盘。那一刻我意识到，理解Agent的运行机制，核心就是理解上下文、检查点、任务恢复这三件事是怎么配合的。标题里的“上下文”是第一个关键点。LLM本身是无状态的，每次调用模型，你需要把之前对话和中间结果重新喂给它。所谓上下文管理，本质上就是决定“这次调用我要把哪些历史信息放进窗口里”。1.1 上下文边界：不是所有历史都该进窗口上下文窗口是有限资源。现在主流模型的窗口虽然越来越大，但大窗口不等于你应该把所有东西都塞进去。原因有两个：一是成本，token是按量计费的，塞进窗口的每一段话都在烧钱；二是注意力稀释，窗口塞得太满，模型反而抓不住重点，尤其是中间部分的信息容易“被忽略”。我见过不少初筛方案，直接把Agent每轮的工具返回结果全部追加到消息列表里。跑个二十步，窗口就被工具输出的JSON占满了，模型开始答非所问。所以在设计上下文时，第一件事就是分级：哪些信息必须留在窗口里，哪些可以压缩，哪些可以归档到外部存储。必须留在窗口里的，我总结下来是这几类：用户的核心目标与最新指令，这是最高优先级。当前执行到哪一步、已完成哪些步骤的简短摘要。本轮循环中尚未落定的临时变量和待决策信息。与下一步决策直接相关的关键结果，比如查询返回的核心数字。可以压缩的，是历史对话的详细内容、中间过程的冗长日志、重复出现的工具调用记录。可以归档的，是已经完成的子任务完整结果、大段原始数据。归档不等于删除，而是存到检查点或外部存储里，需要用的时候再按需捞回来。1.2 三条主流压缩路径：截断、摘要、结构化归档上下文压缩不是只有一种做法，实际工程里通常按场景组合使用。第一种是滑动窗口截断，也就是只保留最近N轮对话。实现简单，但对早期信息会有影响，如果用户的原始需求很长，截掉之后模型可能“忘记初心”。所以滑动窗口一般只截中间，头部保留系统提示和原始目标。第二种是层次化摘要。每完成一个子任务，就让模型把这段过程总结成两三句话，把摘要保留在上下文中，详细内容移到外部存储。代价是多一次模型调用，换来的是窗口利用率大幅提高。我实测下来，摘要最好在“子任务边界”触发，而不是每隔固定轮数触发，这样摘要的语义完整性更好。第三种是结构化归档。把Agent的状态抽成固定的字段，比如当前阶段、已完成清单、待办事项、关键参数，以结构化数据的形式放在上下文里。模型每次读到的是一张“状态表”，而不是一长串对话。这种方式最适合流程固定的任务，也是后面检查点设计的基础。1.3 上下文一致性：压缩后模型还是会“精分”压缩会引入一个隐蔽问题：一致性。比如说，上下文里把某个中间结果摘要成了“用户偏好A方案”，但后续某一步实际拿到的是“用户偏好B方案”，模型就可能两边矛盾、来回摇摆。我在一个模拟项目X里就遇到过，Agent在压缩上下文后突然改口，把已经确认过的参数又推翻重来，导致整个流程回退。解决这个问题，我的经验是：在上下文里维护一个不可被压缩的“状态锚点”。这个锚点用固定格式记录不可变事实，比如“用户ID、目标ID、已确认参数、版本号”。压缩可以压缩对话内容，但状态锚点必须原样保留，并且每次状态变更时更新版本号。模型如果发现版本号不一致，就应该以锚点为准，而不是猜测。另外一个细节是，压缩后要给模型一个明确的提示，告诉它“之前的历史我帮你精简了，精简版里包含所有关键决策，如果有冲突，以最新状态为准”。别小看这句话，它能明显减少模型在压缩后的“精分”概率。2. 检查点：给Agent的运行状态拍快照如果说上下文是内存，那检查点就是持久化存储。没有检查点的Agent就像一台不接UPS的服务器，一次断电全部归零。检查点的核心价值，是让Agent的运行状态可以随时被“存档”和“读档”。2.1 检查点到底要保存什么很多人以为检查点就是把对话历史存一下，这是误区。对话历史只是最表层的东西，真正要保存的是完整的状态视图。我整理过一份检查点必备清单：类别具体内容说明任务元信息目标描述、任务ID、创建时间、版本号用于追溯和恢复定位上下文快照系统提示、状态锚点、压缩后的摘要与当前上下文保持同步执行进度当前步骤索引、已完成步骤清单、失败重试记录决定恢复时从哪继续状态变量关键参数、中间结果引用、外部存储的句柄保证变量不丢队列与栈待处理任务队列、函数调用栈用于循环执行场景资源占用情况已消耗token数、当前并发数、租约信息用于恢复后继续管控这份清单看起来内容多，但实际落地时就是一个大JSON对象。我习惯在JSON里加一个schema_version字段，因为机制迭代后老检查点的格式会变，没有版本号你根本没法做迁移逻辑。2.2 检查点序列化：JSON之外还有什么选择JSON是最通用的选择，可读性好、调试方便，配合schema校验也不容易出错。但如果状态里有大量二进制数据，比如嵌入向量、图片特征，JSON就不合适了。这时候可以分两部分：元数据和轻量状态存JSON，重量级数据存对象存储，JSON里只放引用。序列化还有一个容易忽略的点：非可序列化对象。比如某个Agent持有了一个数据库连接池或一个内存中的锁，这些东西没法直接落盘。所以在做检查点之前，必须定义好“边界对象”的保存方式。我的做法是，凡是持有关联资源（连接、句柄、锁）的组件，都实现一个钩子接口，检查点触发时先执行释放或重建逻辑，恢复时再重新初始化。这个设计一开始就要做，否则后面加一个持有资源的模块，检查点就会悄悄漏掉它。2.3 检查点写入策略：同步、异步与Compaction检查点的写入频率直接影响两个指标：恢复的完整度（RPO）和运行性能。写太频繁，IO压力大，Agent主循环被拖慢；写太少，崩溃时丢失的进度多。同步写入阻塞，实时性最高，但性能最差。异步写入性能好，但内存中的状态先变化、落盘有延迟，崩溃的最后几秒状态可能丢。折中方案是异步批量写入加定期强制落盘。我常用的是“阈值触发+定时触发”双策略：状态变化超过一定次数后异步写一次，同时每30秒强制同步一次。这样在性能和可靠性之间取平衡。还有一个机制叫Compaction，合并压缩历史检查点。Agent跑到第100步时，第1步的检查点其实已经没有恢复价值了，保留它只会占空间。所以定期把老检查点合并成“阶段性断点”，只保留每个任务阶段的起始状态和最终状态，中间的细粒度检查点清理掉。这能大幅减少存储成本，尤其是跑大批量任务时。3. 任务恢复：从断点继续执行的关键设计检查点只是存了状态，真正难的是“怎么恢复”。任务恢复不是简单地读回JSON然后接着跑，它涉及恢复粒度、幂等性、脏状态清理这三个核心问题。3.1 恢复粒度：指令级还是步骤级我先说结论：恢复粒度决定了你恢复逻辑的复杂度，也决定了Agent崩溃后损失的范围。指令级恢复，意思是把每一步细粒度操作都记录下来，恢复时从最后一条未完成的指令继续。优点是精度高，缺点是记录成本大，而且步骤之间的依赖关系很难理清。步骤级恢复，是把任务划分为多个子步骤，恢复时从最后一个未完成的子步骤开始。粒度粗一些，但逻辑清晰，实现成本低。我个人的建议是，除非你的任务是纯顺序、无副作用的流水线，否则用步骤级恢复就够了。绝大多数Agent任务，子步骤内部也就几步操作，重跑这几步的成本远低于实现指令级恢复的复杂度。3.2 幂等与重放：重复执行不可怕，可怕的是副作用恢复必然带来重放，重放就必然遇到幂等性问题。一个操作如果重复执行会产生不同的结果，它就是有副作用的。典型的例子是“发送邮件”和“创建订单”。Agent在第一步发了邮件，第二步崩溃了，恢复后从第一步重新跑，邮件就被发了两次。所以任务恢复设计的真正难点，不是“如何恢复”，而是“如何让恢复过程中不会产生重复副作用”。解决这个问题有三种思路。第一种是操作前检查，在执行有副作用的操作前，先查询一下目标资源的状态，如果发现已经创建过了就直接跳过或复用。第二种是操作去重，给每个副作用操作生成一个唯一幂等键，下游服务支持按幂等键去重，重复请求只生效一次。第三种是动作日志，把每一步的“意图”和“结果”都记下来，重放时先查日志，如果这一步已经被标记为完成，就跳过执行直接引用结果。这三种思路可以组合。对于外部API调用，优先靠幂等键；对于内部状态变更，靠动作日志；对于资源型操作，靠状态检查。我实际项目中，用“动作日志+幂等键”的组合就能覆盖绝大多数场景。3.3 脏状态清理：恢复后先做一致性校验恢复执行前，必须做一次脏状态清理。所谓脏状态，就是Agent崩溃前留下的半成品。比如它已经创建了一个临时文件，但还没用完就崩了；或者它持有了一个租约锁，崩溃时锁没释放。我见过一个真实的线上事故：Agent在恢复后，发现某个临时目录里残留了上次崩溃的半截文件，它误以为那是一份完整的中间结果，直接拿来当输入，最后产出了一份错得离谱的报告。排查了半天才发现是脏数据污染。所以恢复流程必须包含一步：校验。校验规则包括：每个临时文件是否有完整标记；每个资源锁是否持有者还存在；每个中间结果是否满足格式约束。校验不通过的直接清理或重建。这一步放在恢复流程的最前面，宁可多花几毫秒，也不能带着脏状态往下跑。4. 循环执行：Agent主循环的骨架与保险栓Agent和普通脚本最大的区别在于，它是“自己决定下一步做什么”的。这就意味着，它的执行结构不是一条直线，而是一个循环：观察当前状态，做出决策，执行动作，更新状态，再观察。循环是Agent的心脏，但循环也是最容易失控的地方。4.1 标准主循环结构一个规范的Agent主循环，伪代码大致是这样的：while not should_terminate(state): # 1. 从上下文中读取当前状态锚点 context = load_context(state) # 2. 让模型决策下一步动作 action = model.decide(context) # 3. 执行动作，拿到结果 result = execute(action) # 4. 更新状态（变量、进度、上下文） state = update_state(state, action, result) # 5. 触发检查点写入（按策略） maybe_checkpoint(state) # 6. 记录循环日志，供可观测性使用 trace.append(action, result)这个结构看起来简单，但每个环节都有坑。第2步的decide可能返回非法动作；第3步的execute可能超时或抛异常；第4步的update_state可能因为字段嵌套过深导致序列化失败。所以真正生产级的循环，还需要在每步外面包一层异常捕获和重试逻辑。4.2 终止条件：三种退出路径循环必须有明确的终止条件，否则就是死循环。我梳理过，Agent循环的正常终止路径有三种：第一种是目标达成，也就是状态锚点里标记的所有待办事项都完成了。这是最理想的情况。但要注意，模型判断“完成”并不可靠，有些模型会过早宣布完成。所以“目标达成”的判断不能只听模型一句话，要结合步骤日志和状态校验。我习惯在终止前做一次“最终检查”，让模型输出一份完成确认清单，再把清单和状态锚点比对。第二种是用户中断。用户发来“停一下”或者“改个目标”，Agent应当能及时响应。实现方式是每轮循环开始时检查中断信号，而不是等当前动作执行完。这里要注意，如果正在执行的是一个长耗时工具调用，要配合超时机制，否则中断信号要等很久才能生效。第三种是失败退出。连续多次重试仍然失败，或者关键条件不满足，Agent应当主动放弃而不是硬撑。这时候要做的是“优雅降级”：把已完成的部分保存好，把失败原因写清楚，把未完成的子任务标记好，方便下次从断点恢复。4.3 防死循环：最大迭代数、行为检测与熔断即使有终止条件，模型也可能在条件不满足时反复执行相似的动作。比如它反复调用同一个搜索接口，搜出来的结果都是同一个，然后它又继续搜。这种情况模型自己意识不到，需要外部机制兜底。最简单的是最大迭代次数，跑满200轮强制终止。这个数字按任务复杂度设置，太小的会误伤长任务，太大的起不到保护作用。我建议设置成任务预估步数的两到三倍。进阶一点的是行为重复检测。记录最近若干轮的动作签名，比如动作名称加参数摘要，如果发现连续多轮的动作高度相似且状态没有实质进展，就触发警告。我常用的指标是“最近五轮内状态变量变化幅度”，如果变化幅度低于阈值且动作重复度高，就判定为原地打转，中断循环并提示人工介入。再加上熔断机制就更稳了。熔断分两个维度：错误率熔断和资源熔断。错误率超过阈值时，循环暂停，先把错误模式分析清楚再决定是否继续；资源消耗超过预算时，直接熔断，防止一个失控Agent烧完整个批次的额度。这三个保险栓叠在一起，基本能把死循环问题堵死。5. 资源管控：Token、内存、并发一个都不能少资源管控是Agent运行机制里最容易被忽视、但出事最严重的一环。我见过不少团队，上下文、检查点、循环都做得很规范，结果在一次大批量任务面前，token额度一小时烧完，或者内存被中间结果撑爆。资源管控不是“优化”问题，而是“生存”问题。5.1 Token预算：给每个Agent一张信用卡Token是Agent运行最核心的资源，也是最贵的资源。做预算管理，本质上就是给每个Agent一张信用卡，设定额度，超额就停。Token预算要分两层：单次会话预算和全局预算。单次会话预算决定一个Agent任务最多能消耗多少token，超出就终止任务并保存检查点。全局预算决定整个批次的token上限，用于多Agent并发场景下的总量控制。预算的执行方式，是在循环的每一步累加实际消耗。这里有个容易忽略的点：消耗的不只是模型输入输出token，还包括工具返回结果占用的token、上下文压缩时额外的摘要token。所以统计口径要统一，建议按“每次调用模型时的输入token + 输出token + 估算的工具结果token”来算。宁可算多，不能算少。超出预算后的处理也值得设计。最简单的是硬性终止，但不够优雅。更好的做法是分级处理：达到预警线时，自动切换更经济的模型、压缩上下文；达到硬顶时，保存检查点、记录失败原因、终止任务。这样至少能保住已完成的部分。5.2 内存与对象生命周期Agent运行时的内存消耗，主要来自两块：一是上下文中的大对象，比如长文档、图片、超大JSON；二是历史中间结果的累积。大对象进上下文的场景很常见，Agent读了一个几百KB的文档，把这个文档原样放在消息里，内存立刻飙升。更好的做法是预处理：文档先切块、抽取摘要或转成向量，放进上下文的只是摘要和引用，原始内容放外部存储。按需读取。中间结果累积是更隐蔽的问题。Agent每跑一步，把工具返回结果append到一个列表里，跑完50步这个列表可能已经很大了。如果这些中间结果后续用不到，就应该及时释放，只保留最近的几个或汇总后的结果。我习惯在循环里加一个“历史结果回收”逻辑：超过N步的原始结果直接释放，只保留摘要或引用。还有一类内存问题是连接泄漏。Agent如果频繁创建HTTP客户端、数据库连接池，又忘记关闭，跑几百轮后可能把连接数占满。这块要靠资源池化来解决：连接统一管理、统一复用、定期清理。自定义会话池、连接超时这些都要配上。5.3 并发与限流：多Agent时的共享池设计当你有多个Agent并发执行时，资源管控的复杂度立刻上了一个台阶。每个Agent单独限流还不够，因为它们会竞争同一个模型API的配额、同一批下游接口的调用权限。我踩过的一个坑是：10个Agent并发跑，每个Agent自己的token预算都设了上限，结果它们加起来把单日模型API配额打爆了。因为API配额是账户级的，不是会话级的。所以多Agent场景必须做共享池。共享池的核心是按优先级分配。我设计的方案是：把一批任务分成高优先级（用户在线等待）和低优先级（后台批量处理），低优先级Agent尽量在空闲时段跑，高优先级Agent优先拿配额。池子的配额用令牌桶实现，每个Agent每次调用模型前要“取令牌”，取不到就排队等待或降级。限流还要考虑下游接口的限制。很多外部API有QPS限制，多个Agent同时调同一个接口，很容易触发限流报错。解决方案是给每个下游接口建一个专用的限流队列，所有Agent的请求统一走队列。这比在每个Agent内部做限流要可靠得多。6. 端到端流程：一个真实任务的完整生命周期前面五节是把各个机制拆开讲，现在把它们串起来。一个标准的Agent任务，从接收到完成，其实是一条清晰的状态流水线。理解这条流水线，你才能真正看懂框架在设计什么。6.1 状态机：从初始化到完成我把Agent任务的生命周期归纳为六个主状态：状态触发条件主要动作初始化任务被接收加载配置、初始化上下文、建立资源池规划上下文就绪拆解目标、生成子任务列表、写入状态锚点执行子任务就绪进入主循环、按序执行、更新状态暂停用户中断/资源预警保存检查点、释放临时资源、等待指令恢复用户指令/资源恢复读取检查点、校验一致性、回到执行态完成所有子任务完成输出结果、清理资源、归档检查点这个状态机的好处是，每个状态的边界很清楚，崩溃发生在哪个状态一目了然。比如崩溃在执行态，恢复时就回到执行态，从最后的检查点续跑；崩溃在暂停态，恢复时先做资源重建，再回执行态。6.2 版本演进：从v22到v23.3我调整了什么标题里提到的23.3，是我维护的一套Agent运行时机制里的一个重要版本。这个版本相比之前，主要改了三个地方。第一个改动是“检查点结构升级”。旧版本把检查点直接存成一个大JSON，越跑越大，恢复时要反序列化很久。23.3里改成“分层检查点”：元数据、状态快照、历史归档分开存。恢复时先加载轻量的元数据和状态快照，历史归档按需懒加载。实测恢复时间缩短了将近一半。第二个改动是“上下文压缩策略从固定轮数触发改成状态变化触发”。旧版每五轮压缩一次，不管这五轮有没有实质进展。新版改为当状态锚点发生变更、且上下文长度超过阈值时再压缩，减少了无效压缩次数，也降低了上下文“精分”的概率。第三个改动是“引入了循环行为检测保险丝”。旧版只有最大迭代次数兜底，碰上模型原地打转，能把你几十万token干烧完。23.3里加上了动作签名比对和状态变化幅度检测，连续多轮无实质进展就自动熔断，省了不少冤枉钱。这三个改动不是拍脑袋想出来的，都是真实线上跑出来的痛点。第一个是被恢复时间折磨出来的，第二个是上下文精分事故逼出来的，第三个是烧了两次token额度后不得不加的。所以如果你在用类似的Agent运行时，我建议你也把“运行机制”当成一个可以持续迭代的工程，而不是写定就不动的。6.3 可观测性：没有日志的Agent就是一个黑盒最后一个环节，也是很多人最后才想起的：可观测性。Agent和传统程序不一样，它的每一步决策都是模型生成的，不记录日志，你就永远无法追溯它为什么做出某个决定。我在每个Agent任务里都会输出三类日志。第一类是决策日志，记录每轮循环模型返回的动作和它参考的关键上下文片段；第二类是执行日志，记录每个工具调用的请求参数、返回结果和耗时；第三类是资源日志，记录每步的token消耗、内存占用和队列状态。三类日志拼起来，就能完整还原一个Agent从接收到完成的全过程。有了日志还不够，还要有可视化的trace。我的做法很朴素，就是把日志按“任务ID+步骤ID”组织成树状结构，配合时间线展示。出问题时，按任务ID一查，从决策日志定位到是哪一步的决策失误，再配合当时的上下文快照，基本五分钟内能定位问题。这套机制，我现在维护的每个Agent项目都会默认带上。坦白说，Agent运行机制没什么高深莫测的魔法，它就是一套“状态保存、恢复、循环、控资源”的工程组合拳。难点不在于某个单独的技术，而在于它们之间的咬合：上下文失效了检查点来找补，检查点出错了恢复逻辑来兜底，循环失控了资源管控来熔断。把这套咬合关系理顺了，Agent跑得再久，你心里也有底。