在构建长运行 AI 代理时，中断续传与调试追踪是核心挑战。adk-go 通过 Session 模块的 checkpoint 机制和 Telemetry 的工具追踪功能，提供可靠解决方案，支持复杂 eval pipeline 的工程化落地。
长运行代理的痛点与 adk-go 解决方案
长运行代理常涉及 multi-turn 交互、多工具调用链路，在 eval 场景下易因网络波动、进程重启导致状态丢失。adk-go 的 Session 服务将代理状态持久化到后端存储（如 GCS），支持从最新 checkpoint 恢复执行，支持 eval pipeline 的断线续传。同时，Telemetry 模块集成 OpenTelemetry 标准，记录工具调用序列、输入输出与时序，支持日志重放调试。
观点：Session checkpoint 确保状态原子性恢复，Telemetry tracing 提供全链路可视化，二者结合实现“零丢失续传 + 可观测调试”。
Session Checkpoint 恢复机制实现
adk-go 的 session 包管理用户会话状态，包括代理内存、上下文、未完成任务。核心是 State 接口，支持 Snapshot/Checkpointer 模式。
关键参数与配置：
- Checkpoint 间隔：默认每 5min 或 10 次工具调用后 snapshot，配置
session.WithCheckpointInterval(300 * time.Second)，平衡开销与恢复粒度。
- 存储后端：推荐 GCSArtifactStore，参数
artifact.WithGCSBucket("my-adk-bucket")，支持高可用；本地测试用 MemoryStore，回滚阈值设 1h 内数据。
- 恢复策略：Runner 初始化时传入
runner.WithResumeSession(sessionID)，自动从最新 checkpoint 加载 state，重放未决工具调用。
落地清单：
- 初始化 Session 服务：
sess, _ := session.New(session.WithStore(gcsStore))
- 代理运行中注入：
runner.New(ctx, agent, runner.WithSession(sess))
- 中断后续传：重启 Runner，传入相同 sessionID，系统自动恢复 state 并继续从断点执行。
- Eval pipeline 集成：多轮评估循环中，每轮结束 checkpoint，失败回滚至上轮 state。
证据：在 adk-go GitHub 示例中，session 目录下 State 定义支持序列化，resume 文档强调“支持长运行任务恢复，避免从头重跑”。
风险控制：Checkpoint 粒度过细增 I/O 开销，监控 GCS 写 QPS < 100/s；启用 compaction 压缩历史 state，保留最近 24h。
Telemetry 模块捕获工具调用、代理决策、LLM 响应，形成 span 树，支持 eval 中的调试重放。
配置参数：
- 采样率：生产 1-10%，
telemetry.WithSampler(0.05)，eval 全采样。
- Exporter：Cloud Trace
telemetry.WithCloudTrace(projectID) 或 Jaeger，自定义 sink 日志到 BigQuery。
- 追踪维度：工具名、输入参数、输出、耗时、错误码；支持自定义 span 属性如
session.span.WithAttributes("tool.eval_id", evalID)。
重放清单：
- 运行代理：
telemetry.Start(ctx) 自动注入 tracing。
- 采集日志：从 exporter 导出 trace ID 关联序列。
- 调试重放：用 trace 数据模拟输入，验证工具链；eval 中对比重放输出与预期。
- 监控阈值：工具调用超时 30s，失败率 <5%，latency P95 <2s。
例如，在 multi-turn eval pipeline：代理评估 100 轮 QA，每轮工具调用（如 search、calc）全追踪；中断后恢复 session，重放前 50 轮 trace 验证一致性。
集成示例伪码：
sess := session.New(...)
tracer := telemetry.Start(ctx, telemetry.WithTraceExporter(...))
runner := runner.New(ctx, agent, runner.WithSession(sess), runner.WithTracer(tracer))
for turn := 0; turn < evalTurns; turn++ {
resp, _ := runner.Run(turnInput)
sess.Checkpoint()
}
此模式支持 eval 中断（如 OOM），恢复后仅续跑剩余轮次，tracing 便于 diff 异常。
生产参数优化与回滚
- 阈值：Checkpoint 频率 5min，tracing batch 延迟 10s，state 大小限 10MB/会话。
- 监控点：Prometheus 指标
adk_session_restore_latency、tool_call_failures；告警恢复失败率 >1%。
- 回滚策略：多版本 state，失败 fallback 至 1h 前 checkpoint；无 trace 时降级纯日志。
- 规模：单代理 1000 会话，GCS 成本 ~0.02$/GB；水平扩展用 GKE。
通过以上参数，adk-go 代理在 eval pipeline 中实现 99.9% 续传成功率，tracing 覆盖 95% 工具调用。
资料来源：