在 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。
落地清单:
- App 定义:
app := adk.NewApp("resumable-agent", rootAgent, &adk.ResumabilityConfig{IsResumable: true})
- Runner 续传:
runner.RunAsync(ctx, userID, sessionID, invocationID="中断 ID"),自动加载 State。
- Custom Agent 适配:扩展 BaseAgentState,定义 WorkflowStep Enum(如 INITIAL=1, LOOP=2),在 run_async_impl 中
_load_agent_state(ctx) 检查点,yield AgentStateEvent 保存步进。
- 监控点: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}。
生产追踪清单:
- 工具幂等:恢复时 Tool 至少执行一次,检查
temp:tool_id 防重入(如支付场景)。
- 追踪粒度:工具 >100ms 告警,Trace Explorer 筛选 latency >1s,分析 LLM/Tool 占比。
- 回滚策略:Trace 异常 >3 次,暂停 Invocation,通知运维。
- 集成 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 |
资料来源: