agno Agent 崩溃后如何靠 checkpointtool-batch 从最后一个检查点恢复 run【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno长时间跑的 Agent run多次调用工具的 research 类任务最怕 worker 进程中途挂掉OOM-kill、SIGKILL、断电这类崩溃不会执行任何清理逻辑。agno 的默认 checkpoint 行为只在终态写库这种情况下工作直接丢失把 Agent 的checkpoint设为tool-batch后每个工具批次结束都会把 run 持久化到数据库崩溃后用/continue路径acontinue_run就能从最后一个检查点原地恢复。崩溃为什么会丢工作默认 checkpoint 的写入时机agno Agent 的checkpoint参数取值为Literal[runs, tool-batch, tools]见 Agent 源码默认checkpointruns只在终态COMPLETED、PAUSED、CANCELLED、ERROR写库。worker 在 run 中途崩溃时session 行存在但这个run_id从未被记录在该 session 下——工作丢失见 Checkpointing README。checkpointtool-batch在每个工具批次之后写入post-gather barrier而不是只在终态写入。一次 run 有 K 个工具批次加最后一个无工具回合会得到 K 1 次写入K 次 run 中途 1 次终态。如果进程死在第 J 批和第 J1 批之间数据库行里包含到第 J 批为止的全部内容状态仍标记为RUNNING。checkpointtools逐工具写入保留给 3.02.x 中会抛NotImplementedError。README 同时给出适用边界这是对session.runsJSON 列的真实写放大应当刻意选择适合长研究类 run 和需要崩溃恢复的 workflow不适合高频聊天的 agent。准备条件示例使用本地 SQLite 数据库SqliteDb持久化状态可以用任意 SQLite 客户端检查。示例模型为OpenAIResponses(idgpt-5.4)运行需要有效的 OpenAI API key02_tool_error_persistence.py 中通过OPENAI_API_KEY环境变量操作该 key。官方示例的运行方式见 Running 一节.venvs/demo/bin/python cookbook/02_agents/18_checkpointing/01_crash_recovery.py .venvs/demo/bin/python cookbook/02_agents/18_checkpointing/02_tool_error_persistence.py .venvs/demo/bin/python cookbook/02_agents/18_checkpointing/03_checkpoint_endpoints.py复现一次真实崩溃并验证检查点存活01_crash_recovery.py 不是模拟取消而是真的让一个正在跑的 run 崩溃再证明数据库里有最后一个检查点、/continue能原地恢复。它的流程是启动一个 worker 子进程执行 run该 run 连续调用两个慢工具每个约 1 秒与父进程共享同一个 DB 文件通过CRASH_DB环境变量传递路径父进程轮询数据库直到第一个RUNNING检查点落地至少 1 个工具批次父进程对 worker 执行SIGKILLworker.kill()——真崩溃无清理逻辑检查数据库中的残留状态再调用/continue恢复。选择 SIGKILL 而不是asyncio.Task.cancel()的原因写在示例 docstring 里cancel 会被优雅处理——run 被标记为CANCELLED并重新持久化而cancelled run 是故意设计为不可 continue 的。真实崩溃OOM-kill、SIGKILL、断电不执行清理存活下来的就是最后那个RUNNING检查点。崩溃后脚本通过db.get_session读取 session 并打印检查点信息脚本输出示例run_id: run_xxx status: RUNNING tool batches in DB: 2 message count: 5 last_checkpoint_at_message_idx: 4关键点状态是RUNNING说明循环没有走到终态清理。文档明确对/continue而言RUNNING和ERROR等价两者都是原地恢复in place同一个run_id。如果轮询窗口内模型没产生足够的工具批次就直接答完了脚本会打印 Did not catch a RUNNING checkpoint before the worker finished. 并建议重跑——这是示例自己的判定不是失败。手动恢复一个已崩溃的 run把上面的模式套用到你自己的服务上恢复路径分三步。恢复用的 agent 要和崩溃的 agent 保持同样的配置同一模型、同一 DB、同一批工具示例中通过同一个build_agent()构造。from agno.agent import Agent from agno.db.sqlite import SqliteDb from agno.models.openai import OpenAIResponses from agno.run.base import RunStatus DB_FILE tmp/checkpoint_crash_recovery.db # 崩溃前后必须是同一个 DB 文件 SESSION_ID crash-demo-session agent Agent( nameresearch-agent, modelOpenAIResponses(idgpt-5.4), dbSqliteDb(session_tablecheckpoint_demo, db_fileDB_FILE), checkpointtool-batch, tools[slow_search, slow_fetch_detail], # 与崩溃 run 相同 ) # 1. 定位崩溃的 run状态为 RUNNING 且已包含工具批次 session agent.db.get_session(session_idSESSION_ID, session_typeagent) run session.runs[-1] if run.status RunStatus.running and run.tools: crashed_run run # 2. 原地恢复同一个 run_id resumed await agent.acontinue_run( run_idcrashed_run.run_id, session_idSESSION_ID ) print(resumed.run_id, resumed.status)acontinue_run的完整签名含continue_from、fork、regenerate等参数见 Agent.acontinue_run崩溃恢复只需传run_id和session_id其余走默认值continue_fromend。判定恢复成功返回的resumed.run_id与崩溃 run 相同in-place resumeresumed.status到达COMPLETEDresumed.tools/resumed.messages的数量不少于崩溃前检查点里的数量——即示例中total tool batches / total messages两个打印项示例最终还会打印恢复后跑完的resumed.content。可选分支通过 AgentOS 的 checkpoint 端点查看时间线如果你的 Agent 跑在 AgentOS 服务里而不是纯 Python 进程内03_checkpoint_endpoints.py 展示了两个 GET 端点检查点边界是从持久化 run 推导出来的没有独立的 checkpoint 表GET /agents/{agent_id}/runs/{run_id}/checkpoints?session_id...返回可供 UI 展示为恢复点的 message 边界时间线GET /agents/{agent_id}/runs/{run_id}/checkpoints/{message_index}?session_id...返回截断到该边界的 run 快照只读派生不改写存储行。拿到时间线里某个message_index后可以直接作为continue_from参数回喂给POST /agents/{agent_id}/runs/{run_id}/continue从指定检查点续跑并追加新的 input。示例用fastapi.testclient.TestClient在进程内驱动 AgentOS无需单独起服务器。边界与限制写放大是明确的代价tool-batch用额外写入换可恢复性README 建议只对长研究类 run 和崩溃可恢复的 workflow 显式开启不要给高频聊天 agent 默认开。cancelled run 不可恢复Task.cancel()这类优雅取消会把 run 标记为CANCELLED并重新持久化cancelled run 被设计为不可 continue只有RUNNING真崩溃和ERROR走原地恢复。模型调用失败是另一条路径02_tool_error_persistence.py 区分了工具抛异常被模型循环内部捕获转成tool_call_errorTrue的 tool 消息run 正常完成无数据丢失和模型调用本身失败异常逃逸出循环走终态ERROR写入两种情形。对ERRORrun 调acontinue_run不会触发 auto-fork-on-COMPLETED 规则同样是原地重试、run_id不变。checkpointtools在 2.x 中不可用会抛NotImplementedError。相邻的/continue能力重做最后一次响应、回退到更早检查点、fork 整个 session分别位于 19_regenerate/、20_time_travel/ 和 21_fork_session/ 示例目录不在本文的崩溃恢复范围内。【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考