google-agents-cli-observability
installsforks
How to install google-agents-cli-observability?
google/agents-cli/google-agents-cli-observability
$npx -y skills add google/agents-cli --skill google-agents-cli-observabilitygoogle-agents-cli-observability is an agent skill published from google/agents-cli, installable through the skills CLI.
SKILL.md
| 1 | # ADK Observability Guide |
| 2 | |
| 3 | > **Cloud Trace** works out of the box — no infrastructure needed. **Prompt-response logging** and **BigQuery Agent Analytics** require Terraform-provisioned infrastructure (service account, GCS bucket, BigQuery dataset). Run `agents-cli infra single-project --project PROJECT_ID` to provision these resources. See `references/cloud-trace-and-logging.md` for details, env vars, and verification commands. If your project isn't scaffolded yet, see `/google-agents-cli-scaffold` first. |
| 4 | |
| 5 | ### Order of operations for `agent_runtime` deployments |
| 6 | |
| 7 | For `deployment_target = agent_runtime`, run `agents-cli infra single-project` **before** the first `agents-cli deploy`. The Terraform module owns the entire Reasoning Engine resource (display_name, service account, deployment spec, env vars), so applying it after a SDK-based deploy creates a state mismatch — Terraform has no record of the SDK-deployed instance and cannot layer env vars onto it without taking ownership of the whole resource. |
| 8 | |
| 9 | If you have already run `agents-cli deploy`, you have two options: |
| 10 | |
| 11 | 1. **Switch to Terraform-managed.** Delete the SDK-deployed Reasoning Engine, then run `agents-cli infra single-project` followed by `agents-cli deploy`. Sessions and any in-flight state on the previous instance are lost. |
| 12 | 2. **Keep the SDK-deployed instance.** Skip `infra single-project` and set the observability env vars on the running instance directly via the `vertexai` client `update` API. You will also need to grant the instance's service account the IAM permissions required to emit telemetry — writing to the logs GCS bucket, BigQuery dataset access, log writer, etc. See `deployment/terraform/single-project/iam.tf` and `telemetry.tf` in your scaffolded project for the full set of bindings the Terraform module would otherwise provision. Terraform-managed env vars are not available in this mode. |
| 13 | |
| 14 | ### Reference Files |
| 15 | |
| 16 | | File | Contents | |
| 17 | |------|----------| |
| 18 | | `references/cloud-trace-and-logging.md` | Scaffolded project details — Terraform-provisioned resources, environment variables, verification commands, enabling/disabling locally | |
| 19 | | `references/bigquery-agent-analytics.md` | BQ Agent Analytics plugin — enabling, key features, GCS offloading, tool provenance | |
| 20 | |
| 21 | --- |
| 22 | |
| 23 | ## Observability Tiers |
| 24 | |
| 25 | Choose the right level of observability based on your needs: |
| 26 | |
| 27 | | Tier | What It Does | Scope | Default State | Best For | |
| 28 | |------|-------------|-------|---------------|----------| |
| 29 | | **Cloud Trace** | Distributed tracing — execution flow, latency, errors via OpenTelemetry spans | All templates, all environments | Always enabled | Debugging latency, understanding agent execution flow | |
| 30 | | **Prompt-Response Logging** | GenAI interactions exported to GCS, BigQuery, and Cloud Logging | ADK agents only | Disabled locally, enabled when deployed | Auditing LLM interactions, compliance | |
| 31 | | **BigQuery Agent Analytics** | Structured agent events (LLM calls, tool use, outcomes) to BigQuery | ADK agents with plugin enabled | Opt-in (`--bq-analytics` at scaffold time) | Conversational analytics, custom dashboards, LLM-as-judge evals | |
| 32 | | **Third-Party Integrations** | External observability platforms (AgentOps, Phoenix, MLflow, etc.) | Any ADK agent | Opt-in, per-provider setup | Team collaboration, specialized visualization, prompt management | |
| 33 | |
| 34 | **Ask the user** which tier(s) they need — they can be combined. Cloud Trace is always on; the others are additive. |
| 35 | |
| 36 | --- |
| 37 | |
| 38 | ## Cloud Trace |
| 39 | |
| 40 | ADK uses OpenTelemetry to emit distributed traces. Every agent invocation produces spans that track the full execution flow. |
| 41 | |
| 42 | ### Span Hierarchy |
| 43 | |
| 44 | ``` |
| 45 | invocation |
| 46 | └── agent_run (one per agent in the chain) |
| 47 | ├── call_llm (model request/response) |
| 48 | └── execute_tool (tool execution) |
| 49 | ``` |
| 50 | |
| 51 | ### Setup by Deployment Type |
| 52 | |
| 53 | | Deployment | Setup | |
| 54 | |-----------|-------| |
| 55 | | **Agent Runtime** | Automatic — traces are exported to Cloud Trace by default | |
| 56 | | **Cloud Run (scaffolded)** | Automatic — `setup_telemetry()` configures Cloud Trace/Logging exporters | |
| 57 | | **GKE (scaffolded)** | Automatic — `setup_telemetry()` configures Cloud Trace/Logging exporters | |
| 58 | | **Cloud Run / GKE (manual)** | Configure OpenTele |
People who liked this also viewed
6 picksType
- hyperframes-cliUse the HyperFrames CLI development loop: init, add, catalog, capture, lint, check, snapshot, compare, grade-compare, preview, play, present, beats, keyframes, single or batch render, publish, cloud, SkillsJul 2026
- request-refactor-planSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026
- analyze-projectRigor Analyze / Rigor Audit read-only skill for deep learning research repositories. Use when the user wants to read and understand a repository, inspect model structure and training or inference entrSkillsMay 2026
- explore-codeRigor Improve implementation leaf skill for auditable candidate implementation in deep learning research repositories. Use when the researcher explicitly authorizes exploratory work on an isolated braSkillsMay 2026
- ubiquitous-languageSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026
- scaffold-exercisesSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026
