Pydantic AI Harness Step Persistence指南：保存、恢复、分叉运行，一键接管AI Agent会话-北京尧图网络

【免费下载链接】pydantic-ai-harnessYour agents favorite harness, built on Pydantic AI项目地址https://gitcode.com/gh_mirrors/py/pydantic-ai-harness点击查看免费下载用 Pydantic AI Harness 的 Step Persistence 能力只需几行代码就能把 AI Agent 的会话变成可保存、可恢复、可分叉进程崩溃后从最近的检查点继续运行resume也能从任意快照点 fork 出一条新分支。它是基于 Pydantic AI 构建的 Agent 持久化底座专为多轮对话、多进程协作和故障恢复场景设计。为什么 AI Agent 会话需要存档点跑过 Agent 的人都遇到过这些场景进程崩溃Agent 跑到一半被 kill上下文全丢只能从头再来跨进程续聊想在新进程里接着上一轮的调查继续问却不知道从哪里接分支实验希望从某个中间状态分叉出一条新路径而不是覆盖原对话审计追溯想知道 Agent 到底调了哪些工具、每步花了多久、副作用是否真的发生。Step Persistence 就是为解决这些问题而生的它把 Agent 每次run的每一步都记录成事件与快照让你随时**恢复continue或分叉fork**运行。⚡ Step Persistence 的四大能力上这类轨迹上图是一次典型 Agent run 的模型请求与工具调用时序背后的每一步Step Persistence 都会落盘。它提供四类核心能力追加式步骤事件StepEventrun 开始/结束、模型请求、工具调用、失败等每个边界都会追加一条事件记录即使进程在工具调用中途被杀死也留有完整的事件线索可续接快照ContinuableSnapshot在工具调用全部完成的稳定边界保存快照。每个快照带statecomplete工具结果齐全或interrupted崩溃时留下的未完结工具调用工具副作用账本ToolEffectRecord按(run_id, tool_call_id)记录每个工具的生命周期started/completed/failed崩溃后能判断副作用到底发生没有谱系元数据conversation_id多轮序列与parent_run_id父-子 Agent 层级两个独立维度让一次对话和一次委托调用都能精确查询。它记录的是消息级检查点不是图状态graph-state检查点——能力内部状态、工作区快照的恢复不在当前范围内。三步开启 Step Persistence先安装Mongo 后端需额外安装[mongodb]扩展uv add pydantic-ai-harness # 或使用 pippip install pydantic-ai-harness最小接入只有几行核心就是把StepPersistence挂到 Agent 的 capabilities 上from pydantic_ai import Agent from pydantic_ai_harness import StepPersistence from pydantic_ai_harness.step_persistence import InMemoryStepStore store InMemoryStepStore() agent Agent( openai:gpt-5, capabilities[StepPersistence(storestore, agent_namelibrarian)], ) await agent.run(帮我调查一个符号的定义, conversation_idconv-1)run_id天然对应每次Agent.run调用多轮对话的分组请用conversation_id这样同一对话的所有轮次都能按组查询。四种存储后端按规模选择所有后端实现同一套异步StepStore协议可随时替换后端适用场景特点InMemoryStepStore单元测试、本地调试进程内存零配置FileStepStore(dir)单机、可追溯每个 run 一个目录run.json 追加式events.jsonlsnapshots/SqliteStepStore(db)单机生产单文件 SQLiteWAL 模式tool_effects按最新状态 upsertMongoStepStore(client/db_url)分布式原生异步首写自动建索引需[mongodb]扩展长对话的快照默认不裁剪可用max_snapshots_per_run限制单 run 的快照数量防止存储膨胀store FileStepStore(runs, max_snapshots_per_run8)后端实现位于 pydantic_ai_harness/step_persistence/_store.py。会话恢复continue_run 一键续接快照里保存的正是上图这类完整消息历史输入、回复、工具调用与参数。恢复会话的核心是continue_run它读取该 run 最新的complete快照消息直接回传给Agent.run(message_history...)from pydantic_ai_harness.step_persistence import continue_run # 找到对话的最后一轮 run prior_run (await store.list_runs(conversation_idconv-1))[-1].run_id history await continue_run(store, run_idprior_run) # 换个进程也没关系接着聊 await agent.run(继续检查一下这个路径, message_historyhistory, conversation_idconv-1)默认只返回安全的complete快照若确认崩溃点可安全续接可传include_interruptedTrue。分叉运行fork_run 开辟新分支fork_run(store, run_id...)返回与continue_run相同形状的消息历史但语义是从该快照点开辟一条新分支——新 run 会拿到新的run_id通常还有新的conversation_id不会污染原对话from pydantic_ai_harness.step_persistence import fork_run history await fork_run(store, run_idlibr-3f2a) # 传给一个全新的 delegate run新的 agent_name / conversation_id典型用法调查中途发现方向不对从某个快照点分叉重查或主对话继续推进同时另开一条分支做实验。崩溃恢复工具副作用账本是关键进程中途被 kill 时工具到底执行了没有是个经典难题。Step Persistence 的答案store.list_unresolved_tool_effects(run_id...)列出所有只有started记录、没有终态的工具——这类工具标记为unknown_after_crash副作用可能已发生也可能没有inspect_recovery(store..., run_id...)位于 pydantic_ai_harness/step_persistence/recovery.py一次性返回最新快照、已结算快照与未决效果清单便于决策是continue_run还是fork_run有外部副作用的工具改 issue 标签、发 PR 等建议在执行前调用annotate_tool_effect(store, ctx, idempotency_key..., effect_summary...)把幂等键和效果摘要写进账本恢复时即可判断能否安全重放。⚠️ 注意回到更早的complete快照不会撤销已发生的外部副作用去重决策由你的编排层负责。检查运行树与 SnapshotSaved 通知list_runs支持conversation_id、parent_run_id等过滤器组合查询结果按开始时间升序排列# 某个编排器 run 下的所有 delegate 子运行 delegates await store.list_runs(parent_run_idorch-3f2a) # 一次对话的全部轮次 turns await store.list_runs(conversation_idconv-abc)子 Agent 委托在进程内调用时parent_run_id会通过ContextVar自动推断填充无需手动传参跨进程场景可显式设置parent_run_id。每次检查点写入完成后会发出SnapshotSaved类型化能力事件携带persistence_run_id、conversation_id、step_index、state订阅它就能实时感知快照落盘时机。边界说明它不做什么❌ 不恢复能力内部状态、图节点状态、重试计数器或进行中的流式响应❌ 不自动去重重放的外部副作用需配合annotate_tool_effect自行决策❌ 默认不裁剪事件与快照也不回收已外化的媒体文件❌ 不发出 OpenTelemetry spanspydantic_ai 的Instrumentation能力已覆盖 agent run / chat / running tool 的追踪。参考资料资料路径官方文档含完整示例与 API 参考docs/step-persistence.md能力模块总览pydantic_ai_harness/step_persistence/能力实现源码pydantic_ai_harness/step_persistence/_capability.py恢复辅助函数continue/fork/annotatepydantic_ai_harness/step_persistence/_helpers.py崩溃恢复检查工具pydantic_ai_harness/step_persistence/recovery.py会话头存储与会话命名pydantic_ai_harness/step_persistence/conversations.py模块 READMEpydantic_ai_harness/step_persistence/README.md 项目处于 0.x 版本API 可能在次要版本间调整届时弃用警告与迁移指南会说明升级方法。掌握 Step Persistence 后你的 AI Agent 就从一次性进程升级为有存档、可续命、能分叉的持久会话系统——无论是崩溃恢复还是多 Agent 协作编排都多了一手底牌。赞分享【免费下载链接】pydantic-ai-harnessYour agents favorite harness, built on Pydantic AI项目地址https://gitcode.com/gh_mirrors/py/pydantic-ai-harness点击查看免费下载相关推荐3分钟上手Sketch批量文本替换神器告别繁琐手动修改3分钟上手Sketch批量文本替换神器告别繁琐手动修改还在为Sketch设计稿中的重复文本修改而烦恼吗Sketch Find And Replace插件正makesense.ai 标注数据导入指南格式支持矩阵、文件规范与源码级实现解析makesense.ai 标注数据导入指南格式支持矩阵、文件规范与源码级实现解析导读本指南以 docs/import.md https://link.giPi-Harness 故障恢复指南Checkpoint 检查点、会话恢复、分叉与重试全解析Pi Harness 故障恢复指南Checkpoint 检查点、会话恢复、分叉与重试全解析 Pi Harness 是 Pi Coding Agent 的上一篇Pensieve网络请求分析为什么它不需要互联网连接下一篇3 步配好 Blackbox Exporter 的 GET/POST/PUT 探测从最小 YAML 到告警创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Pydantic AI Harness Step Persistence指南：保存、恢复、分叉运行，一键接管AI Agent会话

相关推荐

HiGHS 求解器：LP、MIP、QP 三种模型一个开源库装齐

从原始权重到MLX格式：Tess-4-27B-8bit转换原理、生态路线与社区支持

一行命令干净禁用 Windows Defender 与防火墙，还能随时恢复

更多资讯

C++左值引用与右值引用：移动语义和完美转发实践指南

如何将7-Zip C++核心嵌入Swift应用：ShichiZip桥接层架构深度剖析

OCTO iOS 架构全景解析：6 个 CocoaPods 模块 + 3 个系统扩展如何搭出原生 IM 客户端

WoWee 测试体系揭秘：214 个单元测试与 Game Replay 机制，客户端项目如何保证质量

动态环境下多无人机协同路径规划与防撞Matlab仿真实践

别再手动比价了：SteamTradingSiteTracker 替你 24 小时盯住四平台 Steam 饰品行情

今日更新

Verilog实现FPGA密码锁：矩阵键盘与状态机设计实战

数据服务监控运维实战：从指标体系到告警治理与故障排查

FreeRTOS任务通知实战详解：内核原理、API与避坑指南

本周精选

金融AI落地指南：从调研报告到技术选型与工程实践

大模型上下文成本与注意力优化技术深度解析——为何O(n²)平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测

基于GMM的语音识别系统原理与MATLAB实现详解

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？