在构建长运行 AI 代理系统时，检查点恢复（checkpoint recovery）和工具追踪（tool tracing）是确保可靠性和可观测性的核心机制。Google 开源的 ADK-Go 作为 code-first Go SDK，提供原生支持这些功能。通过 session 包管理状态持久化、telemetry 包集成 OpenTelemetry，以及 runner 的 resume 能力，开发者可以轻松实现断线续传和全链路追踪。本文聚焦单一技术点：如何在 ADK-Go 中配置检查点恢复与工具追踪，并给出工程化参数与监控清单。
检查点恢复：状态持久化与断线续传
长运行代理任务（如多代理协作评估管道）易受网络波动、进程崩溃影响。ADK-Go 通过 session 包实现会话级状态管理，支持从检查点恢复执行，避免从头重跑。
核心观点：使用 SessionService 持久化 agent 状态（包括工具输出、内存快照），结合 Runner 的 ResumeAgents 配置，实现精确恢复。
证据与实现：
可落地参数/清单：
-
配置 SessionService：
import "google.golang.org/adk/session"
svc := session.NewService(session.Config{
Backend: "gcs",
Bucket: "my-agent-checkpoints",
TTL: 24 * time.Hour,
})
- TTL 参数控制过期：生产设 7 天，避免存储爆炸。
- 启用压缩：State.Compact() 阈值设 80% 上下文长度。
-
Runner 中启用 Resume：
cfg := runner.Config{
Resume: true,
SessionID: "eval-pipeline-uuid",
MaxResumeAge: 7 * 24 * time.Hour,
}
events, err := runner.New(ctx, agent, cfg).Run()
- MaxResumeAge 防 stale checkpoint：超过阈值强制重启。
- 恢复清单：检查事件流完整性，若缺失 >20% 事件，回滚至上个完整检查点。
-
部署管道集成：
- CI/CD 中：Kubernetes Job with checkpoint volume (PVC)，Pod 重启时 mount session state。
- 参数：CheckpointInterval=5min（每 5 分钟快照），MinEventsBeforeCheckpoint=10（至少 10 事件后保存）。
风险监控：
- 状态膨胀：监控 State.Size() > 1MB 时压缩。
- 恢复失败率：Prometheus 指标 <1%，否则警报。
工具追踪：全链路遥测与可视化
工具调用是代理行为的核心，追踪其输入/输出、延迟、错误是评估管道的关键。ADK-Go 的 telemetry 包集成 OpenTelemetry，支持自动插桩至 Cloud Trace。
核心观点：无需改代码，--trace-to-cloud 标志启用追踪；自定义 SpanExporter 捕获工具级指标。
证据与实现：
可落地参数/清单：
-
启用 Telemetry：
import "google.golang.org/adk/internal/telemetry"
telemetry.Setup(telemetry.Config{
ProjectID: "my-project",
TraceEnabled: true,
SampleRate: 0.1,
})
- SampleRate：开发 1.0，生产 0.05-0.2。
-
工具追踪配置（tool/functiontool 等）：
- 每个 Tool 执行注入 span：name="execute_tool:func_name"，attributes={input, output, latency_ms}。
- 自定义：实现 toolinternal.SpanHandler，追踪嵌套调用（如 agenttool）。
-
Cloud Trace 集成：
- 部署 Cloud Run：
gcloud run deploy --set-env-vars=TRACE_TO_CLOUD=true。
- 监控清单：
| 指标 |
阈值 |
行动 |
| Tool Latency P99 |
<5s |
优化工具 |
| Error Rate |
<0.5% |
回滚 |
| Token/Trace |
<10k |
压缩上下文 |
| Parent-Child Spans |
完整率>95% |
检查插桩 |
-
评估管道追踪：
- 多代理：事件图（EventGraphHandler）可视化调用链。
- BigQuery Agent Analytics：聚合追踪数据，计算成功率。
风险监控：
- 追踪开销：CPU <5%，否则降采样。
- 数据隐私：敏感工具 output 匿名化。
工程化最佳实践
在长运行管道中，结合检查点与追踪：
- 清单：1. 初始化 Session+Telemetry；2. Runner cfg 设 resume+trace；3. 部署时 volume mount + OTEL env；4. Dashboard：Cloud Trace + Prometheus。
- 参数调优：CheckpointFreq=1min（高频任务），TraceSample=0.1；回滚策略：3 次恢复失败 → 重启。
- 测试：examples/ 目录模拟中断，验证恢复准确率 >99%。
这些机制使 ADK-Go 代理管道 resilient，支持生产部署。
资料来源：
（正文字数：1256）