agents-cli BigQuery Agent Analytics：用 --bq-analytics 为 ADK 智能体开启结构化事件分析

agents-cli BigQuery Agent Analytics用 --bq-analytics 为 ADK 智能体开启结构化事件分析【免费下载链接】agents-cliThe CLI and skills that turn any coding assistant into an expert at creating, evaluating, and deploying AI agents on Google Cloud.项目地址: https://gitcode.com/GitHub_Trending/ag/agents-cliBigQuery Agent Analytics Plugin 是 agents-cli 中一个面向ADK 项目的可选opt-in可观测性组件它通过 ADK 官方插件把结构化的智能体事件直接写入 BigQuery底层走 Storage Write API从而支撑会话分析、LLM-as-judge 评测、自定义仪表盘Looker Studio以及工具调用溯源LOCAL / MCP / SUB_AGENT / A2A / TRANSFER_AGENT 五种来源。读完本文你将掌握该插件的两种启用方式、scaffold 自动生成的插件代码与 Terraform 基础设施、关键配置参数含义以及事件落库后的常用 SQL 查询方式。一、插件能做什么根据 BigQuery Agent Analytics 参考文档启用后它提供四类能力会话分析Conversational analytics记录会话流转、用户交互模式LLM-as-judge 评测为评测流水线提供结构化数据自定义仪表盘可接入 Looker Studio工具调用溯源Tool provenance tracking区分工具来自 LOCAL、MCP、SUB_AGENT、A2A 还是 TRANSFER_AGENT。在 agents-cli 的可观测性分层中它与 Cloud Trace默认常开、Prompt-Response Logging、第三方平台并列为四个层级其中 BigQuery Agent Analytics 的适用范围是“ADK agents with the plugin enabled”默认状态为 Opt-in典型场景就是“会话分析、自定义仪表盘、LLM-as-judge 评测”——见 Observability Skill。相比始终开启的 Cloud Trace 遥测该插件提供更细粒度的结构化表格式数据专为离线 SQL 分析设计参见官方指南 bq-agent-analytics.md。二、两种启用方式方式操作scaffold 时启用agents-cli scaffold create project-name --bq-analytics文档简写为--bq-analyticsscaffold 后手动添加在app/agent.py中手动引入插件参考 ADK 官方文档的 BigQuery Agent Analytics 集成说明在 scaffold 时启用时Terraform 会自动供给所需基础设施BigQuery dataset、GCS 卸载存储无需手工创建。源码视角--bq-analytics标志的定义该标志定义在 create 命令f click.option( --bq-analytics, is_flagTrue, helpInclude BigQuery Agent Analytics Plugin for observability, defaultFalse, )(f)它只是一个布尔开关默认为False此外交互式创建流程中也提供可选项1. [bq-analytics] Log agent events to BigQuery for monitoring and evaluationcreate.py#L1149-L1171选择后同样置位bq_analytics。该值随后作为 cookiecutter 变量bq_analytics传入模板渲染见 template.py#L989-L1013 与 template.py#L1371决定了模板中哪些代码块与 Terraform 配置块会被渲染出来。三、scaffold 自动生成的插件代码启用标志后ADK Python 模板生成的app/agent.py会多出条件化的插件初始化代码见 adk 模板 agent.py#L23-L106{%- if cookiecutter.bq_analytics %} import os # Initialize BigQuery Analytics _plugins [] _project_id os.environ.get(GOOGLE_CLOUD_PROJECT) _dataset_id os.environ.get(BQ_ANALYTICS_DATASET_ID, adk_agent_analytics) _location os.environ.get(GOOGLE_CLOUD_LOCATION, us-east1) if _project_id: try: bq bigquery.Client(project_project_id) bq.create_dataset(f{_project_id}.{_dataset_id}, exists_okTrue) _plugins.append( BigQueryAgentAnalyticsPlugin( project_id_project_id, dataset_id_dataset_id, location_location, configBigQueryLoggerConfig( gcs_bucket_nameos.environ.get(BQ_ANALYTICS_GCS_BUCKET), connection_idos.environ.get(BQ_ANALYTICS_CONNECTION_ID), ), ) ) except Exception as e: logging.warning(fFailed to initialize BigQuery Analytics: {e}) {%- endif %}这段生成代码有几个值得注意的实现细节防御式初始化只有当GOOGLE_CLOUD_PROJECT存在时才初始化初始化失败只打 warning 而不是让应用崩溃——本地开发时没有凭证也能正常启动智能体数据集自创建启动时调用bq.create_dataset(..., exists_okTrue)自动确保目标 dataset 存在这是“auto-schema upgrade / 免迁移”体验的一部分agent_events表本身则由插件在第一条事件到达时自动创建见 官方指南 Infrastructure 一节环境变量驱动所有 GCP 相关参数都不硬编码而是从环境变量读取便于同一份代码在本地与部署环境切换。涉及的环境变量环境变量作用本地默认值Terraform 注入值GOOGLE_CLOUD_PROJECTGCP 项目 ID无无则跳过插件初始化var.project_idBQ_ANALYTICS_DATASET_ID事件写入的 datasetadk_agent_analytics{project_name}_telemetryGOOGLE_CLOUD_LOCATIONdataset 所在区域us-east1var.regionBQ_ANALYTICS_GCS_BUCKET多模态内容卸载的 GCS 桶无logs 数据桶google_storage_bucket.logs_data_bucketBQ_ANALYTICS_CONNECTION_IDGCS 访问用的 BigQuery Connection无{region}.{project_name}-genai-telemetry其中三个BQ_ANALYTICS_*变量由 deployment 模板在cookiecutter.bq_analytics开启时渲染到服务定义中例如 Cloud Run 单项目部署模板service.tf#L206-L220{%- if cookiecutter.bq_analytics %} env { name BQ_ANALYTICS_DATASET_ID value google_bigquery_dataset.telemetry_dataset.dataset_id } env { name BQ_ANALYTICS_GCS_BUCKET value google_storage_bucket.logs_data_bucket.name } env { name BQ_ANALYTICS_CONNECTION_ID # Format: {location}.{connection_id} value ${var.region}.${google_bigquery_connection.genai_telemetry_connection.connection_id} } {%- endif %}注意BQ_ANALYTICS_CONNECTION_ID的取值格式是{location}.{connection_id}——插件侧需要带区域前缀的完整连接标识而 Terraform 的google_bigquery_connection资源本身只有{project_name}-genai-telemetry这一段所以模板里显式拼接了var.region。四、Terraform 自动供给的基础设施如前所述scaffold 启用--bq-analytics后Terraform 负责供给基础设施。以 Python 基模板的 single-project 部署为例telemetry.tf#L16-L56会创建BigQuery Dataset{project_name}_telemetry连字符替换为下划线区域跟随var.regionBigQuery Connection{project_name}-genai-telemetry用于 BigQuery 侧访问 GCS并附带一段time_sleep10 秒等待连接的服务账号在 IAM 中传播生效IAM 授权把 Connection 的服务账号授予 logs 桶的roles/storage.objectViewer。官方指南同时说明Infrastructure 一节GCS 桶{project_id}-{project_name}-logs用于内容卸载agent_events表由插件在首条事件时自动创建。此外同一套 telemetry 模块还包含与 Prompt-Response Logging 共享的部分GenAI 日志 sink、completions外部表与completions_view视图telemetry.tf#L57-L191。这些不属于 BQ Analytics 插件本身的产物但它们与插件数据共处于同一个{project_name}_telemetrydataset 中方便你在 BigQuery 里把结构化事件与 prompt-response 明细做关联查询。对于agent_runtime部署还有一处特殊要求值得留意如果选择了“保留 SDK 部署实例、跳过 Terraform 接管”的路线需要手动为该实例的服务账号补上roles/bigquery.dataOwner与roles/bigquery.jobUser仅当 scaffold 时带了--bq-analytics完整角色集可参考deployment/terraform/single-project/iam.tfapp_sa_roles与telemetry.tf见 Observability Skill。五、关键特性免迁移升级、GCS 卸载、分布式追踪、SQL 可查参考文档列出的四项 Key Features逐条对应到实现机制Auto-schema upgrade自动 schema 升级新增字段无需迁移流程。从源码结构看dataset 在应用启动时以exists_okTrue创建agent_events表由插件在首条事件时自动建立后续字段扩展依赖 BigQuery 的 schema evolution 能力因此团队升级 ADK 版本、事件新增字段时不需要人工改表。GCS offloadingGCS 卸载图片、音频等多模态内容不直接塞进 BigQuery而是写入BQ_ANALYTICS_GCS_BUCKET指向的桶表中保留引用。这正是配置里gcs_bucket_nameconnection_id两个参数成对出现的原因——前者是存放位置后者授权 BigQuery 读取这些对象。分布式追踪Distributed tracing插件通过 OpenTelemetry span context 把事件挂到既有 trace 上与 agents-cli 的 Cloud Trace 体系invoke_workflow → invoke_agent → call_llm / execute_toolspan 层级天然衔接可在同一个追踪视角下对照事件表。SQL 可查询的事件日志所有智能体交互LLM 调用、工具使用、结果状态落成agent_events表可直接 SQL 分析这也是它与“日志文件式”观测方式的核心区别。六、配置参数详解BigQueryLoggerConfig如果 scaffold 后手动添加插件或想更精细地控制行为完整配置形态可参考 官方指南 Configuration 一节from google.adk.plugins.bigquery_agent_analytics_plugin import ( BigQueryAgentAnalyticsPlugin, BigQueryLoggerConfig, ) bq_config BigQueryLoggerConfig( enabledTrue, gcs_bucket_nameos.environ.get(BQ_ANALYTICS_GCS_BUCKET), connection_idos.environ.get(BQ_ANALYTICS_CONNECTION_ID), log_multi_modal_contentTrue, max_content_length500 * 1024, table_idagent_events, ) bq_analytics_plugin BigQueryAgentAnalyticsPlugin( project_idos.environ.get(GOOGLE_CLOUD_PROJECT), dataset_idos.environ.get(BQ_ANALYTICS_DATASET_ID, adk_agent_analytics), table_idbq_config.table_id, configbq_config, locationos.environ.get(GOOGLE_CLOUD_LOCATION, US), ) app App( namemy-agent, root_agentroot_agent, plugins[bq_analytics_plugin], )BigQueryLoggerConfig的关键选项参数说明enabled插件总开关gcs_bucket_name可选大对象/二进制内容卸载的 GCS 桶仅多模态数据需要connection_id可选访问 GCS 的 BigQuery Connection ID仅多模态数据需要log_multi_modal_content是否处理并把内容 part 卸载到 GCSmax_content_length文本卸载到 GCS 的长度阈值示例取 500 KBtable_id目标表名默认agent_eventsevent_allowlist/event_denylist过滤要记录的事件类型batch_size批量写入的行数阈值对比 scaffold 模板可知模板生成的代码只设置了gcs_bucket_name与connection_id两项其余取默认值table_id默认agent_events。如果你不需要多模态卸载可以删掉这两项插件仍然能把结构化文本事件写入 BigQuery。七、落库之后常用 SQL 查询事件表位置为{project_id}.{project_name}_telemetry.agent_events。以下查询来自官方指南Example Queries 一节替换YOUR_PROJECT_ID/YOUR_AGENT_NAME即可使用。查看最近事件SELECT * FROM YOUR_PROJECT_ID.YOUR_AGENT_NAME_telemetry.agent_events ORDER BY timestamp DESC LIMIT 100;工具调用与错误content 列为 JSON用 JSON_VALUE 抽取SELECT timestamp, JSON_VALUE(content, $.tool) AS tool_name, JSON_VALUE(content, $.args) AS tool_args, status, error_message FROM YOUR_PROJECT_ID.YOUR_AGENT_NAME_telemetry.agent_events WHERE event_type IN (TOOL_COMPLETED, TOOL_ERROR) ORDER BY timestamp DESC;按 agent 与模型汇总 LLM token 用量SELECT agent, JSON_VALUE(attributes, $.model) AS model, SUM(CAST(JSON_VALUE(attributes, $.usage_metadata.prompt) AS INT64)) AS total_prompt_tokens, SUM(CAST(JSON_VALUE(attributes, $.usage_metadata.completion) AS INT64)) AS total_completion_tokens FROM YOUR_PROJECT_ID.YOUR_AGENT_NAME_telemetry.agent_events WHERE event_type LLM_RESPONSE AND JSON_VALUE(attributes, $.usage_metadata.prompt) IS NOT NULL GROUP BY agent, model;从查询形态可以确认表的核心列timestamp、event_type、status、error_message、agent以及承载模型与 usage metadata 的 JSON 列attributes、承载工具名与参数的 JSON 列content——工具溯源LOCAL/MCP/SUB_AGENT/A2A/TRANSFER_AGENT即通过对content做 JSON 解析完成。需要更完整的 schema 与 Looker Studio 搭建说明时可查阅 ADK 官方文档adk.dev 的 BigQuery Agent Analytics 集成页。八、适用前提与排障适用前提官方指南 Prerequisites项目由ADK 系模板如adk生成——Go/Java/TS 模板不携带该插件代码google-adk版本 1.21.0启用插件时会自动加入依赖GCP 项目已启用 BigQuery API 与 BigQuery Storage API通常由 Terraform 处理。常见故障来自 Observability Skill 排障表现象排查方向BigQuery 中没有事件确认插件确实配置在app/agent.py模板里由cookiecutter.bq_analytics条件块生成检查BQ_ANALYTICS_DATASET_ID环境变量是否已设置本地看不到事件、部署后正常属预期行为模板代码在缺少GOOGLE_CLOUD_PROJECT时静默跳过插件初始化多模态内容未卸载检查BQ_ANALYTICS_GCS_BUCKET/BQ_ANALYTICS_CONNECTION_ID是否注入二者缺一不可以及 service account 对桶的读写权限agent_runtime部署缺权限走 SDK 部署路线时需手工授予roles/bigquery.dataOwnerroles/bigquery.jobUser九、关键路径速查内容路径本文档原始参考skills/google-agents-cli-observability/references/bigquery-agent-analytics.md官方扩展指南配置 SQL 示例docs/src/guide/observability/bq-agent-analytics.md可观测性分层与排障skills/google-agents-cli-observability/SKILL.md--bq-analytics标志定义src/google/agents/cli/scaffold/commands/create.py#L142-L147生成的插件初始化代码模板src/google/agents/cli/scaffold/agents/adk/app/agent.py#L79-L106部署环境注入Cloud Run 示例src/google/agents/cli/scaffold/deployment_targets/cloud_run/python/deployment/terraform/single-project/service.tf#L206-L220基础设施dataset / connection / IAMsrc/google/agents/cli/scaffold/base_templates/python/deployment/terraform/single-project/telemetry.tf小结BigQuery Agent Analytics 是 agents-cli 面向 ADK 智能体的“事件级”观测层——--bq-analytics一个标志即可让 scaffold 同时生成插件代码与 Terraform 基础设施事件免迁移落库到{project_name}_telemetry.agent_events配合 JSON 列解析即可支撑 token 统计、工具错误分析与 LLM-as-judge 评测。它不改变 Cloud Trace 的常开行为而是以结构化的方式把“发生了什么”沉淀为可长期查询的表数据。【免费下载链接】agents-cliThe CLI and skills that turn any coding assistant into an expert at creating, evaluating, and deploying AI agents on Google Cloud.项目地址: https://gitcode.com/GitHub_Trending/ag/agents-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考