“黑盒”困境：当生产环境中的AI智能体失控时
你使用智能体开发工具包（ADK）构建了一个AI智能体。它在本地测试环境中运行完美。部署到生产环境后，头几天一切似乎都很顺利。然而，用户开始报告意外的响应、性能缓慢或直接报错。你检查了标准的应用程序日志，但它们只显示了高层级的请求/响应周期。你完全无法洞察智能体内部的决策过程。它调用了哪个工具？发送给大语言模型的确切提示词是什么？延迟峰值出现在智能体运行链的哪个环节？
这就是“黑盒”问题。没有深度可观测性，调试生产环境中的AI智能体就变成了一场令人沮丧的猜谜游戏。你只能尝试在本地复现问题，但这通常是不可能的，因为问题源于特定的用户输入、工具行为或生产环境中大语言模型的不确定性。你需要一种方法来追踪整个执行流程，记录关键的生成式AI交互，并随时间分析模式。
一个理想的解决方案应该提供：
- 分布式追踪，以可视化智能体调用的逐步执行过程，包括大语言模型调用和工具执行。
- 详细的日志记录，用于审计和调试提示词与响应，并具备可配置的隐私控制。
- 结构化分析，以聚合智能体事件，用于性能监控和评估。
- 集成灵活性，允许你使用首选的可观测性平台，无论是Google Cloud服务还是第三方工具。
目标是从“猜测”转向“确知”。你需要看到智能体采取的确切路径、它处理的数据以及它做出的决策，同时避免给开发工作流带来显著开销。
介绍一个针对ADK智能体的实用可观测性技能
如果你正在使用Google智能体开发工具包（ADK）构建智能体，并且正面临“黑盒”问题，那么 google-agents-cli-observability 技能是一个值得审视的结构化指南。它并非万能灵药，而是一套为ADK项目添加可观测性的精选实践和配置。它利用 agents-cli 工具来帮助搭建和管理必要的基础设施与代码模式。
此技能是更广泛的ADK开发套件的一部分。它专门关注“监控与调试”阶段，与用于部署或核心代码模式的技能截然不同。可以将其视为一本为已部署智能体设置“眼睛和耳朵”的参考手册。
该技能实际涵盖的内容：可观测性层级
该技能将可观测性分解为不同的层级，让你可以根据需求选择合适的详细程度。你无需一次性实施所有内容。
层级一：使用Cloud Trace进行分布式追踪
这是基础层。ADK使用OpenTelemetry自动生成每次智能体调用的追踪。你可以看到一个层级化的跨度树：顶层的 invocation，每个智能体链中智能体的子级 agent_run 跨度，以及更下级的 call_llm 和 execute_tool。
- 解决的问题： 理解执行流程，识别延迟瓶颈，并精确定位错误发生的位置。
- 设置： 对于使用脚手架项目部署到Agent Runtime、Cloud Run或GKE的智能体，追踪是自动启用的。对于本地开发，它可与
agents-cli playground配合使用。 - 查看位置： 追踪会出现在Google Cloud控制台的 Trace > Trace explorer 中。
- 关键考量： 对于脚手架部署，此层级默认始终开启。它开销低，能为调试提供即时价值。
层级二：提示词-响应日志记录
此层级捕获实际的生成式AI交互：模型名称、token计数、时间，以及可选的提示词和响应内容。数据被导出到Cloud Storage（JSONL文件）和BigQuery。
- 解决的问题： 为合规性审计大语言模型交互，调试提示词工程问题，并理解token使用情况。
- 设置： 需要基础设施配置（一个GCS存储桶、BigQuery数据集和服务账户权限）。该技能提供了一个Terraform命令来完成此设置：
agents-cli infra single-project --project PROJECT_ID。 - 隐私控制： 一个关键的环境变量
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT控制内容捕获。脚手架项目默认为NO_CONTENT（仅元数据）以保护隐私。你必须显式配置它才能捕获完整的提示词/响应。 - 关键考量： 对于本地开发，此功能默认禁用。它主要用于需要审计跟踪的已部署智能体。
层级三：BigQuery智能体分析插件
这是一个可选插件，将结构化的智能体事件（大语言模型调用、工具使用、结果）直接记录到BigQuery中，格式针对分析进行了优化。
- 解决的问题： 构建自定义仪表板，执行对话分析，以及基于历史数据运行“大语言模型作为评判者”的评估。
- 设置： 在项目脚手架阶段使用
--bq-analytics标志启用。它需要与提示词-响应日志记录相同的底层基础设施。 - 关键考量： 这适用于希望对智能体行为进行深度、基于SQL分析的团队。它比原始日志导出更具结构性。
层级四：第三方集成
ADK支持与多个外部可观测性平台集成，如AgentOps、Phoenix、MLflow等。每个平台都有不同的优势。
- 解决的问题： 使用你已合作的供应商提供的专业化可视化、团队协作功能或提示词管理工具。
- 设置： 每个平台都有其自身的设置复杂性，通常涉及添加特定的导出器或SDK。该技能提供了一个比较表来帮助你选择。
- 关键考量： 这些集成通常会替换或增强原生的Google Cloud遥测。你需要评估在成本、数据主权和功能集方面的权衡。
何时使用此技能（以及何时不用）
考虑审视此技能，如果：
- 你正在使用Google ADK构建智能体，并将其部署到Google Cloud（Agent Runtime、Cloud Run、GKE）。
- 你有一个已部署的智能体行为异常，而你缺乏对其内部操作的可见性。
- 你需要为合规性或性能监控设置结构化的日志记录和追踪管道。
- 你正在评估不同的可观测性平台，并希望了解它们与ADK的集成点。
此技能可能不适合你，如果：
- 你没有使用Google ADK。其配置和CLI命令特定于此框架。
- 你正在寻找通用的应用程序性能监控（APM）指南。这是ADK专用的。
- 你的智能体仍处于早期原型阶段，只需要基本的
print语句调试。设置完整可观测性的开销此时并不合理。 - 你需要关于部署智能体本身的指导。为此，你应该查看专注于部署的技能，如
google-agents-cli-deploy。
关键的设置上下文与操作顺序
此技能中最重要的细节之一是针对Agent Runtime部署的操作顺序。用于配置可观测性基础设施（服务账户、存储桶、数据集）的Terraform模块也同时管理着推理引擎资源本身。
- 正确顺序： 在第一次运行
agents-cli deploy之前，先运行agents-cli infra single-project。这确保Terraform从一开始就拥有该资源的所有权。 - 问题场景： 如果你先运行了
agents-cli deploy（通过SDK创建了推理引擎），然后再运行Terraform基础设施命令，就会造成状态不匹配。Terraform无法干净地将环境变量分层到一个它不管理的、由SDK部署的实例上。 - 恢复选项：
- 切换到Terraform管理： 删除现有的推理引擎，然后运行基础设施命令，再运行部署命令。这会丢失任何进行中的会话。
- 保留SDK部署的实例： 手动在运行实例上设置所需的环境变量和IAM权限。这更手动化，并且你失去了Terraform状态管理的好处。
这是一个至关重要的操作细节。顺序搞错可能导致令人沮丧的清理过程。
安全信号与仓库健康度
在评估任何开源技能或工具时，检查其出处和健康状况是明智的。
- 仓库： GitHub上的 google/agents-cli。
- 所有者： Google。这表明该工具是作为ADK生态系统的一部分得到官方支持的，降低了被弃用的风险。
- 星标与分叉： 3081颗星（截至数据快照时）表明了显著的社区兴趣和采用度。零分叉可能表明仓库非常新，或者贡献管理方式不同。
- 许可证： Apache-2.0。这是一个宽松的开源许可证，允许广泛使用和修改。
- 安全级别： 在技能元数据中标记为“低”。这可能指的是CLI工具本身的风险状况，它主要负责脚手架代码和运行Terraform。你仍然应该审查它为你的特定云环境生成的Terraform计划。
- 主题： 该仓库被标记为
google-cloud、gemini、agents、adk等，确认了其特定领域。
在运行任何命令之前， 尤其是像 agents-cli infra single-project 这样的基础设施配置命令，你应该：
- 审查脚手架项目中生成的Terraform文件，以确切了解将创建哪些云资源。
- 确保你在Google Cloud项目中拥有必要的IAM权限，以创建服务账户、存储桶和BigQuery数据集。
- 首先在非生产项目中运行该命令以验证设置。
做出决定：这是否适合你的工作流？
此技能为ADK可观测性提供了一条全面的、有明确导向的路径。如果你想要一种引导式的、基础设施即代码的方法，并与Google Cloud服务紧密集成，那么它是一个很好的选择。分层模型让你可以从简单开始（仅追踪），并根据需要添加更多细节。
然而，它要求你接受 agents-cli 工作流和使用Terraform进行基础设施管理。如果你的团队更喜欢手动配置OpenTelemetry导出器或使用不同的基础设施工具，你可能会将此技能作为参考，但以不同的方式实现其概念。
关键在于将其视为一个值得审视的实用选项，而不是一个必经步骤。阅读该技能的详细指南，理解各个层级，并检查设置先决条件。如果调试“黑盒”智能体的问题让你感同身受，并且你身处ADK生态系统中，那么此技能提供了一条清晰、结构化的前进道路。