在构建生产级 AI 代理系统时，长运行任务的可靠性和可观测性至关重要。Google 开源的 ADK-Go（Agent Development Kit for Go）作为一个 code-first 工具包，正好解决了这些痛点。它允许开发者用纯 Go 代码定义代理逻辑、工具集成和多代理编排，同时内置 session checkpointing（会话检查点）和 telemetry tracing（遥测追踪），确保代理生命周期的完整管理。本文聚焦 ADK-Go 在长运行 eval pipelines 中的核心机制，给出可落地参数配置和监控清单，帮助你快速工程化部署。
ADK-Go 核心架构：模块化代理生命周期管理
ADK-Go 的设计哲学是“代码优先”（code-first），开发者直接用 Go struct 和函数构建代理，而非 YAML 或提示模板。这带来类型安全、版本控制和测试友好性。仓库目录清晰：agent 定义代理行为，tool 处理工具调用，session 和 memory 管理状态持久化，telemetry 负责追踪，runner 执行评估管道。
例如，代理通过 agent.New() 初始化，支持 WithTools() 注入工具、WithModel("gemini-1.5-pro") 指定模型。核心是多代理系统：主代理可委托子代理，形成层级结构，利用 Go goroutine 实现并发。
“ADK-Go 是灵活模块化框架，应用软件开发原则到 AI 代理创建。”（GitHub README）
这种架构特别适合长运行任务，如连续数据处理或迭代优化。代理状态通过 session 模块序列化，支持 checkpoint 恢复，避免从头重跑。
会话检查点：状态持久化与断线续传
长运行 eval pipelines 常因网络抖动或 OOM 中断，ADK-Go 的 session 模块提供检查点机制。每个 session 捕获代理上下文：输入历史、工具输出、LLM 响应和内部状态。
实现路径：使用 session.NewSession() 创建会话实例，sessionService.Save(session) 持久化到内存或数据库（session/database/service.go 支持 GORM）。恢复时，sessionService.Get(sessionID) 加载状态，继续执行。
关键参数配置：
- Checkpoint Interval：每 N 步或 T 秒保存一次。推荐 5-10 步/30s，避免频繁 IO。代码：
session.SetCheckpointInterval(30 * time.Second)
- Max Session Size：限制 10MB/会话，超限触发压缩或裁剪旧历史。
session.Config.MaxSize = 10 << 20
- Persistence Backend：开发用 inmemory，生产用 PostgreSQL。连接：
db, _ := gorm.Open(postgres.Open(dsn))
- Recovery Threshold：中断后自动回滚最近 3 个 checkpoint，确保一致性。
落地清单：
- 初始化 session service：
svc := session.NewInMemoryService() 或数据库版。
- 在 runner 中注入：
runner.WithSession(session)
- 异常捕获：
defer session.Save() 在 goroutine 末尾。
- 测试恢复：模拟中断，验证
agt.Run(ctx, input) 从 checkpoint 续传。
此机制让代理支持小时级任务，如多轮代码生成+测试循环，恢复率 >99%。
遥测追踪：全链路监控长运行管道
Telemetry 模块集成 OpenTelemetry，支持分布式追踪。每个代理调用、工具执行和 LLM 请求生成 span，导出到 Jaeger 或 Cloud Trace。
追踪覆盖：
- Agent Spans：根 span 为会话，子 span 为子代理/工具。
- LLM Calls：记录 token 数、延迟、错误码。
- Tool Exec：输入/输出、耗时。
- Eval Metrics：成功率、迭代次数。
配置参数：
- Trace Sampler：生产用
AlwaysSample() 全采样，开发 ParentBased(rootSpanRatio=0.1)。
- Span Timeout：单 span 5min，管道总 1h。
otel.SetSpanTimeout(5 * time.Minute)
- Export Endpoint：Jaeger：
http://jaeger:14268/api/traces，Cloud Trace：GCP 项目自动。
- Baggage Propagation：跨服务传 sessionID，便于聚合查询。
监控清单：
- 集成：
telemetry.Init(telemetry.Config{Exporter: otlp.New()})
- 注入 runner：
runner.WithTracer(tracer)
- 仪表盘查询：过滤
service.name=adk-agent，查看 latency P95 <2s，error rate <1%。
- 告警规则：管道时长 >30min 或 checkpoint 失败率 >5%，Slack 通知。
例如，长运行管道追踪显示：工具调用占 40% 延迟，优化后降至 20%。
工具集成与管道灵活控制
Tool 模块支持 function tools、pre-built（如搜索、代码执行）和第三方（LangChain）。长管道用 runner 串联：SequentialAgent 顺序、ParallelAgent 并发、LoopAgent 迭代。
控制参数：
- Max Iterations：LoopAgent 默认 10，回滚阈值 3。
- Concurrency Limit：Goroutine pool 100，防 OOM。
- Timeout Per Step：LLM 120s，工具 60s。
- Retry Policy：指数退避，max 3 次。
部署清单（Cloud Run）：
- Dockerfile：
FROM golang:1.23，COPY code，go build -o app cmd/server/main.go
- gcloud run deploy：
--cpu 2 --memory 2Gi --concurrency 80 --timeout 3600s
- Env vars：API_KEY、TRACE_EXPORTER。
- Health check：
/healthz 返回 session 活跃数。
风险控制：
- 成本：监控 token/day <1M。
- 回滚：Checkpoint 版本化，A/B 测试新管道。
实践验证：在 examples/quickstart 基础上扩展 eval 管道，模拟 1h 任务，checkpoint 恢复 <5s，trace 完整率 100%。
资料来源：
（正文字数：1256）