Google Agents Cli Observability
Turn on BigQuery agent analytics, Cloud Trace, and prompt-response logging for scaffolded Google ADK agents.
Overview
Google Agents CLI Observability is an agent skill most often used in Operate (also Grow, Ship) that wires BigQuery analytics, OpenTelemetry traces, and prompt logging for scaffolded Google ADK agents.
Install
npx skills add https://github.com/google/agents-cli --skill google-agents-cli-observabilityWhat is this skill?
- Optional BigQuery Agent Analytics plugin via --bq-analytics at scaffold or manual app/agent.py wiring
- Logs structured events with tool provenance: LOCAL, MCP, SUB_AGENT, A2A, TRANSFER_AGENT
- Supports LLM-as-judge eval pipelines, conversational analytics, and Looker Studio dashboards
- GCS offloading for multimodal payloads plus OpenTelemetry span context for distributed traces
- Cloud Trace via otel_to_cloud in Terraform-provisioned scaffolded projects
- 5 tool provenance categories: LOCAL, MCP, SUB_AGENT, A2A, TRANSFER_AGENT
- BigQuery plugin uses auto-schema upgrade so new event fields avoid manual migrations
Adoption & trust: 12.4k installs on skills.sh; 2.7k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your ADK agent works locally but you cannot see session flows, tool sources, or prompt traces once it runs on Vertex without a structured observability stack.
Who is it for?
Builders who scaffolded with agents-cli and want GCP-native analytics instead of ad-hoc print logging.
Skip if: Greenfield projects with no Terraform scaffold or no willingness to provision BigQuery and GCS in GCP.
When should I use this skill?
You need production visibility for a scaffolded ADK agent and want BigQuery analytics, tracing, or eval-ready structured logs on GCP.
What do I get? / Deliverables
You enable queryable BigQuery event logs, distributed Cloud Trace, and provenance-aware analytics so evals and on-call debugging use the same telemetry spine.
- BigQuery event stream suitable for SQL and dashboards
- Distributed traces and prompt-response logging configuration path
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Operate is the canonical shelf because the skill centers on running telemetry, traces, and SQL-queryable event logs after the agent exists in GCP. Monitoring matches distributed tracing, session analytics, and ongoing visibility—not one-off deploy steps.
Where it fits
You scaffold with --bq-analytics so launch day already streams events into a Terraform-provisioned dataset.
You slice conversational funnels in Looker Studio to see which tools drive retention-related user paths.
An incident spike triggers Cloud Trace spans tied to specific MCP versus LOCAL tool invocations.
How it compares
GCP-first agent telemetry skill—not a generic OpenTelemetry snippet pack unrelated to ADK plugins.
Common Questions / FAQ
Who is google-agents-cli-observability for?
Solo builders running Google ADK agents on Vertex who need SQL analytics, tracing, and eval-friendly structured logs without building a custom observability platform.
When should I use google-agents-cli-observability?
Use it in Operate for monitoring live traffic; in Grow to study session patterns and lifecycle funnels; and in Ship when enabling --bq-analytics during scaffold or first production wiring.
Is google-agents-cli-observability safe to install?
Enabling analytics writes agent content to GCP services you control; review IAM, data retention, and the Security Audits panel on this page before turning on BigQuery logging in production.
Workflow Chain
Requires first: google agents cli scaffold
Then invoke: google agents cli eval
SKILL.md
READMESKILL.md - Google Agents Cli Observability
# BigQuery Agent Analytics Plugin > **Opt-in.** Enable with `--bq-analytics` at scaffold time, or add manually to `app/agent.py`. An optional plugin that logs structured agent events directly to BigQuery via the Storage Write API. Enables: - **Conversational analytics** — session flows, user interaction patterns - **LLM-as-judge evals** — structured data for evaluation pipelines - **Custom dashboards** — Looker Studio integration - **Tool provenance tracking** — LOCAL, MCP, SUB_AGENT, A2A, TRANSFER_AGENT ## Enabling | Method | How | |--------|-----| | **At scaffold time** | `agents-cli scaffold create <project-name> --bq-analytics` | | **Post-scaffold** | Add the plugin manually to `app/agent.py` (see ADK docs) | Infrastructure (BigQuery dataset, GCS offloading) is provisioned automatically by Terraform when enabled at scaffold time. ## Key Features - Auto-schema upgrade (new fields added without migration) - GCS offloading for multimodal content (images, audio) - Distributed tracing via OpenTelemetry span context - SQL-queryable event log for all agent interactions For full schema, SQL query examples, and Looker Studio setup, fetch `https://adk.dev/integrations/bigquery-agent-analytics/index.md`. # Cloud Trace & Prompt-Response Logging (Scaffolded Projects) > **Assumes `/google-agents-cli-scaffold` scaffolding.** Observability infrastructure is provisioned by Terraform in scaffolded projects. ## Cloud Trace Always-on distributed tracing via `otel_to_cloud=True` in the FastAPI app. Tracks requests through LLM calls and tool executions with latency analysis and error visibility. View traces: **Cloud Console → Trace → Trace explorer** No configuration required. Works in local dev (`agents-cli playground`) and all deployed environments. ## Prompt-Response Logging Infrastructure All provisioned automatically by `deployment/terraform/telemetry.tf`: - **Log sinks** — Route GenAI inference logs and feedback logs directly to BigQuery (partitioned tables) - **BigQuery dataset** — Telemetry dataset with external tables over GCS data and pre-created log export table - **Pre-created log export table** — `gen_ai_client_inference_operation_details` table with Cloud Logging BQ export schema (labels flattened: dots become underscores) - **GCS logs bucket** — Stores completions as NDJSON - **BigQuery connection** — Service account for GCS access from BigQuery - **Completions view** — Joins BQ log export data with GCS-stored prompt/response data Check `deployment/terraform/telemetry.tf` for exact configuration. IAM bindings grant log sink service accounts `roles/bigquery.dataEditor` on the telemetry dataset. ## Environment Variables Set automatically by Terraform on the deployed service: | Variable | Purpose | |----------|---------| | `LOGS_BUCKET_NAME` | GCS bucket for completions and logs. Required to enable prompt-response logging | | `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` | Controls logging state and content capture | | `BQ_ANALYTICS_DATASET_ID` | BigQuery dataset for telemetry | | `BQ_ANALYTICS_CONNECTION_ID` | BigQuery connection for GCS access | | `GENAI_TELEMETRY_PATH` | Optional: override upload path within bucket (default: `completions`) | ## Enabling / Disabling ### Enable Locally Set these before running `agents-cli playground`: ```bash export LOGS_BUCKET_NAME="your-bucket-name" export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT="NO_CONTENT" ``` ### Disable in Deployed Environments Set `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=false` in `deployment/terraform/service.tf` and re-apply Terraform. ## BigQuery Dataset Naming Convention BigQuery dataset names **cannot contain hyphens**. Terraform automatically converts hyphens to underscores when creating dataset names from your project name: - Project name `my-agent` → BQ dataset `my_agent_telemetry` One dataset is created: - **`{name}_telemetry`** — Contains external tables over GCS completions data (NDJSON), the pre-create