Skip to main content
If you are building AI systems with Google Agent Development Kit (ADK) and want to evaluate multi-agent conversations, handoffs, and tool usage, you can use the SDKs to make Openlayer part of your workflow. This integration guide shows how you can comprehensively trace and monitor your multi-agent systems powered by Gemini models.

Choosing an integration path

Openlayer supports two ways to instrument Google ADK. Both land traces in the same Openlayer pipeline; pick the one that fits your stack. The rest of this page walks through each path. If you’re not sure, start with the Openlayer tracer. Do not enable both paths in the same process. See Don’t combine both paths. A single init() call auto-instruments Google ADK (it runs trace_google_adk() under the hood) along with any other installed LLM SDKs.

Monitoring

To use the monitoring mode, you must instrument your code to publish the requests your AI system receives to the Openlayer platform. To set it up, you must follow the steps in the code snippet below:
Python

See full Python example

Once the code is instrumented, all your Google ADK interactions are automatically published to Openlayer, including:
  • Agent execution with agent names, descriptions, and instructions
  • LLM calls to Gemini models with messages and configurations
  • Token usage including prompt tokens, completion tokens, and totals
  • Tool calls with function names, arguments, and results
  • Agent transfers and handoffs between sub-agents with proper hierarchy
  • Session context including user IDs, session IDs, and invocation tracking
  • Metadata such as latency and timestamps for all operations
If you navigate to the “Data” page of your Openlayer data source, you can see the complete traces for each multi-agent conversation.
The Google ADK integration automatically captures the full agent workflow, including sub-agent handoffs and tool usage. You can use this together with tracing to monitor complex multi-agent systems as part of larger AI workflows. Make sure to call init() before creating any agents.
After your AI system requests are continuously published and logged by Openlayer, you can create tests that run at a regular cadence on top of them. Refer to the Monitoring overview, for details on Openlayer’s monitoring mode, to the Publishing data guide, for more information on setting it up, or to the Tracing guide, to understand how to trace more complex systems.

Path 2 — ADK OpenTelemetry

As of ADK 1.17.0, the framework ships its own OpenTelemetry instrumentation (ADK traces, Cloud Observability) and can export traces over OTLP to any backend — including Openlayer. This is the path to use when you already run an OTel collector, or when application code is not allowed to depend on a vendor tracing SDK. Openlayer ingests the spans via its OpenTelemetry endpoint. ADK emits GenAI semantic-convention spans such as invoke_agent, execute_tool, and generate_content, which Openlayer maps onto agent, tool, and chat-completion steps.

Install packages

Openlayer’s OTel endpoint accepts OTLP HTTP/protobuf (not gRPC). Install opentelemetry-exporter-otlp-proto-http, not the gRPC exporter Google’s Cloud Trace samples use. See the OpenTelemetry integration page for the full endpoint reference.
The Google GenAI and Vertex AI instrumentors enrich the underlying model calls (tokens, model name, messages). ADK itself emits the agent and tool spans.

Configure the environment

Set the following environment variables before constructing any ADK agents. You can put them in the process environment, a dotenv file, or os.environ at process start.
Replace YOUR_OPENLAYER_API_KEY and YOUR_OPENLAYER_PIPELINE_ID with values from your Openlayer workspace. The x-bt-parent header is what routes traces to the correct inference pipeline — not OTEL_SERVICE_NAME.
Do not set OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true when using the latest GenAI semantic conventions. true is not a valid value for that mode. The GenAI instrumentor silently captures no prompt or response content — traces still arrive, but Input / Output in Openlayer are empty. Use SPAN_ONLY (for Openlayer) or EVENT_ONLY (for log-oriented backends such as Cloud Logging).
Google’s Cloud Observability docs recommend OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=EVENT_ONLY and ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS=false, which keep prompts and responses off span attributes (they go to log records instead). Openlayer’s OTel endpoint ingests traces, not logs, and tests need Input / Output on those traces. Use SPAN_ONLY and ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS=true so content lands on the spans Openlayer maps (gen_ai.input.messages / gen_ai.output.messages and ADK’s own span attributes).
Openlayer does not ingest OTLP logs or metrics, so OTEL_LOGS_EXPORTER=none and OTEL_METRICS_EXPORTER=none avoid failed export attempts. Google’s OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED setting is for Cloud Logging and is not needed here.

Wire the exporter

Call ADK’s maybe_set_otel_providers() before importing or constructing agents. It reads the OTEL_EXPORTER_OTLP_* environment variables and installs HTTP OTLP exporters.
Python
If you already configure a global TracerProvider (for example via opentelemetry-instrument or an in-process collector), skip maybe_set_otel_providers() — ADK will use the provider that is already set. If you call Vertex AI through the vertexai SDK rather than google.genai, also run VertexAIInstrumentor().instrument() from opentelemetry.instrumentation.vertexai. To send traces through an existing OpenTelemetry Collector instead of exporting from the app, keep ADK pointed at the collector and add an OTLP/HTTP exporter on the collector to https://api.openlayer.com/v1/otel/v1/traces with the same Authorization and x-bt-parent headers.

adk web / adk api_server

You do not need Google’s --otel_to_cloud flag. That flag wires GCP exporters specifically. For an arbitrary OTLP backend, set the environment variables above and run:
ADK picks up OTEL_EXPORTER_OTLP_TRACES_ENDPOINT (or OTEL_EXPORTER_OTLP_ENDPOINT) and exports spans over OTLP HTTP.

What the traces look like

A typical ADK OTel trace is hierarchical, not flat: Sub-agents appear as nested invoke_agent spans under the parent agent. That maps onto Openlayer’s agent-trace hierarchy the same way other GenAI OTel sources do.

Don’t combine both paths

The Openlayer tracer replaces ADK’s own OpenTelemetry tracer with a no-op so ADK does not emit a second copy of agent and tool spans. The Google GenAI / Vertex AI instrumentors patch the model SDK independently, so LLM spans can still be duplicated. Enable either init() or ADK’s OTel exporters pointed at Openlayer — not both. init() already calls trace_google_adk(), so running it together with Path 2 duplicates traces in Openlayer. If you switch from the native tracer to OTel, call unpatch_google_adk() (or restart the process without init()).

Comparison: which path produces what

Development

In development mode, Openlayer becomes a step in your CI/CD pipeline, and your tests get automatically evaluated after being triggered by some events. Openlayer tests often rely on your AI system’s outputs on a validation dataset. As discussed in the Configuring output generation guide, you have two options:
  1. either provide a way for Openlayer to run your AI system on your datasets, or
  2. before pushing, generate the model outputs yourself and push them alongside your artifacts.
For AI systems built with Google ADK, if you are not computing your system’s outputs yourself, you must provide your API credentials for Google’s Gemini models. To do so, navigate to “Workspace settings” -> “Environment variables,” and click on “Add secret” to add the required Google API credentials (such as GOOGLE_API_KEY or appropriate service account credentials). If you don’t add the required API credentials, you’ll encounter a “Missing API key” error when Openlayer tries to run your AI system to get its outputs.