# ADK-Go 代码优先代理工具包：会话检查点与遥测追踪实战 > Google ADK-Go 通过代码优先方式构建 AI 代理，重点实现会话检查点持久化、遥测追踪与长运行评估管道控制，提供工程参数与监控清单。 ## 元数据 - 路径: /posts/2025/12/01/adk-go-code-first-agent-toolkit-with-session-checkpointing-and-tracing/ - 发布时间: 2025-12-01T04:09:20+08:00 - 分类: [ai-systems](/categories/ai-systems/) - 站点: https://blog.hotdry.top ## 正文 在构建生产级 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，确保一致性。 落地清单： 1. 初始化 session service：`svc := session.NewInMemoryService()` 或数据库版。 2. 在 runner 中注入：`runner.WithSession(session)` 3. 异常捕获：`defer session.Save()` 在 goroutine 末尾。 4. 测试恢复：模拟中断，验证 `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，便于聚合查询。 监控清单： 1. 集成：`telemetry.Init(telemetry.Config{Exporter: otlp.New()})` 2. 注入 runner：`runner.WithTracer(tracer)` 3. 仪表盘查询：过滤 `service.name=adk-agent`，查看 latency P95 <2s，error rate <1%。 4. 告警规则：管道时长 >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）： 1. Dockerfile：`FROM golang:1.23`，COPY code，`go build -o app cmd/server/main.go` 2. gcloud run deploy：`--cpu 2 --memory 2Gi --concurrency 80 --timeout 3600s` 3. Env vars：API_KEY、TRACE_EXPORTER。 4. Health check：`/healthz` 返回 session 活跃数。 风险控制： - 成本：监控 token/day <1M。 - 回滚：Checkpoint 版本化，A/B 测试新管道。 实践验证：在 examples/quickstart 基础上扩展 eval 管道，模拟 1h 任务，checkpoint 恢复 <5s，trace 完整率 100%。 资料来源： - GitHub: https://github.com/google/adk-go - Docs: https://google.github.io/adk-docs/ - Examples: https://github.com/google/adk-go/tree/main/examples （正文字数：1256） ## 同分类近期文章 ### [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++ 推理运行时，聚焦量化策略配置、算子融合模式与内存管理的工程化实践参数。