在构建复杂的 AI 代理系统时，模块化和可扩展性是关键挑战。Google 的 ADK-Go 工具包采用代码优先方法，在 Go 语言中提供灵活的框架，用于工程化代理编排。这种方法允许开发者直接在代码中定义代理逻辑、工具和流程，避免了配置驱动的复杂性，从而提升了测试性和版本控制的便利性。通过 ADK-Go，开发者可以轻松构建从简单任务到多代理协作的系统，支持 Gemini 等模型，同时保持模型无关性。
工具集成是 ADK-Go 实现代理能力的基石。观点上，工具使代理能够与外部系统交互，如搜索、API 调用或自定义函数，这扩展了代理的实用性。证据显示，ADK-Go 支持内置工具（如 Google Search）、自定义函数工具和第三方集成。例如，在快速启动示例中，使用 geminitool.GoogleSearch{} 即可集成搜索功能。进一步地，通过 AgentTool 可以将其他代理包装成工具，实现代理间的显式调用。这在多代理系统中特别有用，例如一个协调代理可以调用子代理作为工具来处理子任务。
要落地工具集成，提供以下参数和清单：
- 定义自定义工具：实现 tool.Tool 接口，包括 Name、Description 和 Run 方法。参数包括输入 schema（如 JSON 结构）和输出处理逻辑。示例：func (t *CustomTool) Run(ctx tool.Context, args any) (any, error) { ... }。
- 集成到代理：在 llmagent.Config 的 Tools 字段传入 []tool.Tool{newTool}。监控工具调用次数，设置超时阈值如 30 秒，避免无限循环。
- 安全参数：启用工具确认（confirmation），要求代理在调用前生成确认事件；限制工具调用深度为 5 层，防止滥用。
- 清单：1. 验证工具输入 schema 与代理指令一致；2. 测试工具在并发环境下的线程安全；3. 记录工具使用日志，用于调试。
状态持久化确保多轮交互的连续性，避免代理遗忘上下文。观点是，共享状态是多代理协作的核心，允许代理间传递数据而不依赖全局变量。ADK-Go 通过 Session 对象管理状态，SessionService（如 InMemorySessionService 或 VertexAiSessionService）处理创建、追加事件和检索。证据：在 InvocationContext 中，ctx.Session().State() 提供 map[string]any 的状态访问，事件追加时自动更新状态。例如，在 SequentialAgent 中，前一代理的输出可通过 output_key 保存到状态，后一代理读取 {key} 占位符。
落地状态持久化参数：
- 选择服务：开发阶段用 InMemory（无持久化）；生产用 VertexAi（需 GCP 项目和 Reasoning Engine ID）。
- 状态管理：限制状态大小 < 10KB，避免内存溢出；使用 temp: 前缀标记临时数据，仅当前转有效。
- 持久化钩子：在回调中实现 OnStateChange，序列化状态到数据库；设置 last_update_time 阈值，过期会话自动清理（e.g., 24 小时）。
- 清单：1. 初始化状态：CreateSession 时传入初始 map；2. 并发安全：使用 mutex 保护状态读写；3. 回滚策略：事件失败时回滚状态到上一个快照。
评估钩子是确保代理可靠性和可扩展部署的关键。观点上，代理的非确定性要求持续监控轨迹和响应质量，ADK-Go 通过回调和内置评估框架支持此。证据：Callbacks 接口允许在事件点（如 BeforeToolCall、AfterResponse）注入自定义逻辑；评估使用 criteria 如 tool_trajectory_avg_score（轨迹匹配）和 response_match_score（响应相似度）。支持 pytest 集成和 CLI 运行 evalset 文件。
落地评估参数：
- 回调实现：注册 callback.Handler，参数包括 ctx 和 event 类型；示例：OnToolCall(ctx, event) { logToolUsage(event.Name) }。
- 评估配置：在 test_config.json 中设置阈值，如 {"tool_trajectory_avg_score": 1.0, "response_match_score": 0.8}；使用 rubric_based_tool_use_quality_v1 自定义评分 rubric（e.g., "工具顺序正确"）。
- 监控点：集成 Cloud Trace，追踪延迟 > 5s 的调用；设置警报：轨迹匹配率 < 90% 时通知。
- 清单：1. 准备 evalset：使用 Web UI 捕获会话，导出 .evalset.json；2. 运行 pytest tests/ --criteria=hallucinations_v1；3. 部署前 CI/CD 运行 adk eval agent_module evalset.json；4. 回滚：如果评估失败率 > 20%，回退到上版本模型。
对于可扩展部署，ADK-Go 支持容器化：构建 Docker 镜像，暴露 REST API server；部署到 Cloud Run 时，设置 CPU=2, Memory=1Gi，自动缩放 min=1 max=10。参数包括环境变量 GOOGLE_API_KEY 和模型名称 gemini-1.5-flash。清单：1. 测试负载：模拟 100 并发会话；2. 监控：集成 telemetry 模块，追踪 QPS 和错误率；3. 安全：启用 Vertex AI 安全过滤。
总之，ADK-Go 通过工具集成、状态持久化和评估钩子，提供工程化路径构建可靠的 AI 代理系统。开发者可从简单代理起步，逐步扩展到多代理编排，确保在生产环境中稳定运行。
资料来源：