# adk-go 中 Agent 检查点恢复与工具追踪 > 基于 adk-go ResumabilityConfig 实现 Agent 长任务断点续传，结合 Session State 与 Cloud Trace 追踪工具调用，提供恢复参数、追踪配置与生产可靠性清单。 ## 元数据 - 路径: /posts/2025/11/30/adk-go-agent-checkpoint-recovery-tool-tracing/ - 发布时间: 2025-11-30T14:48:29+08:00 - 分类: [ai-systems](/categories/ai-systems/) - 站点: https://blog.hotdry.top ## 正文 在 adk-go 构建生产级 AI Agent 时，长任务中断（如网络波动或服务重启）会导致执行丢失，严重影响可靠性。通过 ResumabilityConfig 配置 Agent 检查点恢复机制，能从 Session State 精确续传断点；同时集成工具追踪，利用事件日志与 Cloud Trace 实现调用调试，提升工程化水平。 ### 检查点恢复机制核心原理 adk-go 的 Resume 功能依赖事件（Events）和 Agent 状态（BaseAgentState）记录执行轨迹，支持 Sequential、Loop 和 Parallel Agent 自动续传。根据官方文档，当工作流中断后，使用 Invocation ID 重启 Runner，系统加载已完成事件，重置未完 Agent 状态，从当前子 Agent 或循环迭代继续执行。例如，Sequential Agent 通过 saved state 中的 current_sub_agent 定位下一个子 Agent，避免从头重跑。 恢复流程参数配置： - **ResumabilityConfig**：在 App 初始化设置 `is_resumable: true`，启用检查点自动记录。 - **SessionService**：生产选 DatabaseSessionService 或 VertexAiSessionService，确保 State 持久化。InMemoryService 仅测试用，重启丢失。 - **State 管理**：用 `user:` 前缀存用户级进度（如 `user:task_step: 3`），`temp:` 前缀存单 Invocation 临时数据（如 `temp:tool_params`），避免跨调用污染。 - **恢复阈值**：Invocation 超时设 300s，事件批次 ≤50，避免 State 膨胀。回滚策略：若恢复失败，fallback 到初始 State，重置 `end_of_agent: false`。 落地清单： 1. App 定义：`app := adk.NewApp("resumable-agent", rootAgent, &adk.ResumabilityConfig{IsResumable: true})` 2. Runner 续传：`runner.RunAsync(ctx, userID, sessionID, invocationID="中断 ID")`，自动加载 State。 3. Custom Agent 适配：扩展 BaseAgentState，定义 WorkflowStep Enum（如 INITIAL=1, LOOP=2），在 run_async_impl 中 `_load_agent_state(ctx)` 检查点，yield AgentStateEvent 保存步进。 4. 监控点：Checkpoint Lag < 5s，State 大小 < 10KB，恢复成功率 >99%。 ### 工具追踪集成实现 工具调用是 Agent 可靠性痛点，adk-go 通过 Callbacks、Events 和 OpenTelemetry 实现全链路追踪。每个 Tool 执行产生 execute_tool Span，LLM 调用为 call_llm Span，聚合到 invocation Span，支持 Cloud Trace 水落图分析瓶颈。 追踪配置参数： - **Callbacks**：注册 `on_tool_start/end`，记录参数/结果到 State，如 `ctx.State().Set("tool:weather.result", result)`。 - **Cloud Trace**：部署 Cloud Run/GKE 时 `--trace_to_cloud`，自动导出 Span 到 GCP 项目。Span 名：agent_run、execute_tool，属性含工具名、输入输出。 - **EventActions**：Tool 返回后 append Event，state_delta 记录 `tool_trace: {name: "get_weather", input: {...}, duration_ms: 150}`。 生产追踪清单： 1. 工具幂等：恢复时 Tool 至少执行一次，检查 `temp:tool_id` 防重入（如支付场景）。 2. 追踪粒度：工具 >100ms 告警，Trace Explorer 筛选 latency >1s，分析 LLM/Tool 占比。 3. 回滚策略：Trace 异常 >3 次，暂停 Invocation，通知运维。 4. 集成 Phoenix/Monocle：本地调试用，生产 Cloud Trace 为主。 ### 生产可靠性提升案例 长任务如多 Agent 协作生成报告，中途 Pod 重启，使用 VertexAiSessionService 持久 State，恢复后仅重跑 Parallel 未完分支，节省 80% 时间。工具追踪发现 get_weather 延迟峰值源于 API 限流，优化为缓存 `user:weather_cache`。 风险控制： - 禁止恢复中改工作流（加/删 Agent）。 - Tool 侧效检查：恢复前验证 State 一致性。 - 容量阈值：Session >1k 归档，清理 idle >7 天。 参数调优表： | 参数 | 推荐值 | 说明 | |------|--------|------| | resumability.is_resumable | true | 全局启用 | | session.ttl | 30d | 会话存活 | | trace.sampling_rate | 0.1 | 生产采样 | | state.max_size | 1MB | 防 OOM | 资料来源： - https://google.github.io/adk-docs/runtime/resume/ - https://google.github.io/adk-docs/observability/cloud-trace/ - https://pkg.go.dev/google.golang.org/adk ## 同分类近期文章 ### [NVIDIA PersonaPlex 双重条件提示工程与全双工架构解析](/posts/2026/04/09/nvidia-personaplex-dual-conditioning-architecture/) - 日期: 2026-04-09T03:04:25+08:00 - 分类: [ai-systems](/categories/ai-systems/) - 摘要: 深入解析 NVIDIA PersonaPlex 的双流架构设计、文本提示与语音提示的双重条件机制，以及如何在单模型中实现实时全双工对话与角色切换。 ### [ai-hedge-fund：多代理AI对冲基金的架构设计与信号聚合机制](/posts/2026/04/09/multi-agent-ai-hedge-fund-architecture/) - 日期: 2026-04-09T01:49:57+08:00 - 分类: [ai-systems](/categories/ai-systems/) - 摘要: 深入解析GitHub Trending项目ai-hedge-fund的多代理架构，探讨19个专业角色分工、信号生成管线与风控自动化的工程实现。 ### [tui-use 框架：让 AI Agent 自动化控制终端交互程序](/posts/2026/04/09/tui-use-ai-agent-terminal-automation/) - 日期: 2026-04-09T01:26:00+08:00 - 分类: [ai-systems](/categories/ai-systems/) - 摘要: 详解 tui-use 框架如何通过 PTY 与 xterm headless 实现 AI agents 对 REPL、数据库 CLI、交互式安装向导等终端程序的自动化控制与集成参数。 ### [tui-use 框架：让 AI Agent 自动化控制终端交互程序](/posts/2026/04/09/tui-use-ai-agent-terminal-automation-framework/) - 日期: 2026-04-09T01:26:00+08:00 - 分类: [ai-systems](/categories/ai-systems/) - 摘要: 详解 tui-use 框架如何通过 PTY 与 xterm headless 实现 AI agents 对 REPL、数据库 CLI、交互式安装向导等终端程序的自动化控制与集成参数。 ### [LiteRT-LM C++ 推理运行时：边缘设备的量化、算子融合与内存管理实践](/posts/2026/04/08/litert-lm-cpp-inference-runtime-quantization-fusion-memory/) - 日期: 2026-04-08T21:52:31+08:00 - 分类: [ai-systems](/categories/ai-systems/) - 摘要: 深入解析 LiteRT-LM 在边缘设备上的 C++ 推理运行时，聚焦量化策略配置、算子融合模式与内存管理的工程化实践参数。