From 06429e867bdf0239a951b7e29f9735a97daacfd9 Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Wed, 1 Oct 2025 18:14:09 -0700 Subject: [PATCH 1/3] docs: add agent observability with opik --- docs/observability/opik.md | 105 +++++++++++++++++++++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 106 insertions(+) create mode 100644 docs/observability/opik.md diff --git a/docs/observability/opik.md b/docs/observability/opik.md new file mode 100644 index 000000000..1bf778066 --- /dev/null +++ b/docs/observability/opik.md @@ -0,0 +1,105 @@ +# Agent Observability with Opik + +[Opik](https://www.comet.com/opik/) is Comet's observability, evaluation, and optimization platform for LLM and agent workloads. It captures the full execution context of your Google ADK applications—including agent runs, tool invocations, model calls, and custom business logic—so you can debug faster, monitor cost and latency, and ship production-ready agents with confidence. + +## Why Opik for ADK? + +Opik extends ADK's native OpenTelemetry support with: + +- **Rich span data** – Every agent, tool, and LLM call is logged with prompts, responses, metadata, and token usage for all model calls. +- **Automatic cost tracking** – Built-in cost calculators let you surface spend per span, per agent, or per project without additional code. +- **Multi-agent visualization** – The `track_adk_agent_recursive` helper renders hierarchical graphs of complex agent workflows directly in the UI. +- **Thread-aware tracing** – ADK session IDs are automatically mapped to Opik threads so multi-turn conversations stay grouped together. +- **Error analytics** – Exceptions raised inside agents, models, or tools are captured with stack traces and surfaced in the Opik dashboard. + +## Installation + +Install Opik alongside Google ADK: + +```bash +pip install opik google-adk +``` + +## Configure Opik + +Initialize the Opik Python SDK using whichever method fits your deployment. The quickest way during development is: + +```bash +opik configure +``` + +You can also call `opik.configure()` from code or set the `OPIK_API_KEY`, `OPIK_WORKSPACE`, and `OPIK_PROJECT_NAME` environment variables. See the [Python SDK configuration guide](https://www.comet.com/docs/opik/tracing/sdk_configuration/) for the full matrix covering cloud, enterprise, and self-hosted deployments. + +## Configure Google ADK + +Opik works with any ADK-supported model provider. For the example below we authenticate to Gemini through Google AI Studio: + +```bash +export GOOGLE_GENAI_USE_VERTEXAI=FALSE +export GOOGLE_API_KEY="" +``` + +If you deploy on Vertex AI instead, set `GOOGLE_GENAI_USE_VERTEXAI=TRUE` and configure `GOOGLE_CLOUD_PROJECT` plus `GOOGLE_CLOUD_LOCATION` (or use Application Default Credentials). + +## Basic agent setup with OpikTracer + +The `OpikTracer` automatically captures agent execution, tool calls, and model interactions. Attach it to your ADK agents as shown below: + +```python +from google.adk.agents import LlmAgent +from google.adk import runners +from opik.integrations.adk import OpikTracer + +weather_agent = LlmAgent( + name="weather_agent", + instruction="You provide friendly weather updates.", + model="gemini-2.0-flash", +) + +tracer = OpikTracer(project_name="adk-weather-demo") + +runner = runners.Runner( + agent=weather_agent, + app_name="weather_app", + before_agent_callback=tracer.before_agent_callback, + after_agent_callback=tracer.after_agent_callback, + before_model_callback=tracer.before_model_callback, + after_model_callback=tracer.after_model_callback, +) + +response = runner.run(user_request="What's the weather in New York?") +tracer.flush() # ensure spans are delivered before the script exits +``` + +Open the Opik dashboard and navigate to your project to inspect the trace. You will see the agent span, the downstream LLM call, tool invocations (if any), token usage, and cost estimates. + +## Multi-agent and session workflows + +For complex graphs, instrument your root agent with `track_adk_agent_recursive` to automatically trace every nested ADK agent: + +```python +from opik.integrations.adk import track_adk_agent_recursive + +track_adk_agent_recursive(weather_agent) +``` + +When you run ADK sessions, Opik maps the `session_id` to a thread so multi-turn conversations stay grouped. Metadata such as `user_id` and `app_name` is recorded automatically. + +## Hybrid tracing with `@track` + +The Opik tracer is fully compatible with the [`@opik.track`](https://www.comet.com/docs/opik/tracing/log_traces/#track) decorator. You can: + +- Call ADK agents from inside tracked functions and keep parent/child span relationships intact. +- Decorate tool functions to capture custom business logic alongside ADK-managed spans. + +## Troubleshooting + +- Always await all events when using `Runner.run_async`. Exiting early prevents the tracer from closing spans. +- Call `tracer.flush()` before your script exits to guarantee that buffered spans are delivered. +- Keep `opik` and `google-adk` up to date to benefit from the latest integration improvements. + +## Additional resources + +- [Opik ADK integration reference](https://www.comet.com/docs/opik/python-sdk-reference/integrations/adk/overview/) +- [Opik tracing overview](https://www.comet.com/docs/opik/tracing/log_traces) +- [Opik self-host installation guide](https://www.comet.com/docs/opik/self-host/overview) diff --git a/mkdocs.yml b/mkdocs.yml index 059ab98d9..0ed854eee 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -180,6 +180,7 @@ nav: - Logging: observability/logging.md - Cloud Trace: observability/cloud-trace.md - AgentOps: observability/agentops.md + - Opik: observability/opik.md - Arize AX: observability/arize-ax.md - Phoenix: observability/phoenix.md - W&B Weave: observability/weave.md From 049e0402715e419d4b7e4f6482de24562dd8bb3e Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Fri, 3 Oct 2025 08:05:35 -0700 Subject: [PATCH 2/3] Update opik.md --- docs/observability/opik.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/observability/opik.md b/docs/observability/opik.md index 1bf778066..85b4e7f1a 100644 --- a/docs/observability/opik.md +++ b/docs/observability/opik.md @@ -100,6 +100,6 @@ The Opik tracer is fully compatible with the [`@opik.track`](https://www.comet.c ## Additional resources -- [Opik ADK integration reference](https://www.comet.com/docs/opik/python-sdk-reference/integrations/adk/overview/) +- [Opik ADK integration reference](https://www.comet.com/docs/opik/integrations/adk) - [Opik tracing overview](https://www.comet.com/docs/opik/tracing/log_traces) - [Opik self-host installation guide](https://www.comet.com/docs/opik/self-host/overview) From bec24bf29616594be8136f2298fd092302e41138 Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Fri, 3 Oct 2025 08:14:54 -0700 Subject: [PATCH 3/3] Update opik.md --- docs/observability/opik.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/observability/opik.md b/docs/observability/opik.md index 85b4e7f1a..711e3fca8 100644 --- a/docs/observability/opik.md +++ b/docs/observability/opik.md @@ -2,6 +2,8 @@ [Opik](https://www.comet.com/opik/) is Comet's observability, evaluation, and optimization platform for LLM and agent workloads. It captures the full execution context of your Google ADK applications—including agent runs, tool invocations, model calls, and custom business logic—so you can debug faster, monitor cost and latency, and ship production-ready agents with confidence. +![Comet Opik Agent Observability Dashboard](https://raw.githubusercontent.com/comet-ml/opik/refs/heads/main/apps/opik-documentation/documentation/fern/img/cookbook/adk_trace_cookbook.png) + ## Why Opik for ADK? Opik extends ADK's native OpenTelemetry support with: @@ -92,6 +94,15 @@ The Opik tracer is fully compatible with the [`@opik.track`](https://www.comet.c - Call ADK agents from inside tracked functions and keep parent/child span relationships intact. - Decorate tool functions to capture custom business logic alongside ADK-managed spans. +## Agent Graph +Opik automatically generates visual representations of your agent workflows using Mermaid diagrams. This includes agent hierarchy and relationships, tool calling, parallel processing and sub-tasks too. + +![Comet Opik Google ADK graph view](https://raw.githubusercontent.com/comet-ml/opik/refs/heads/main/apps/opik-documentation/documentation/fern/img/tracing/adk/adk_error_propagation_screenshot.png) + +This also supports more complex agent graphs too. + +![Comet Opik Google ADK advanced graph view](https://raw.githubusercontent.com/comet-ml/opik/refs/heads/main/apps/opik-documentation/documentation/fern/img/tracing/adk/adk_code_assistant_graph_screenshot.png) + ## Troubleshooting - Always await all events when using `Runner.run_async`. Exiting early prevents the tracer from closing spans.