> ## Documentation Index
> Fetch the complete documentation index at: https://tracevell.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Google ADK observability

> Trace Google Agent Development Kit (ADK) runs in Python: agent invocations, Gemini calls, and tool executions, readable as a conversation in Tracevell.

## Overview

Tracevell is an open-source, OpenTelemetry-native observability platform for AI agents built with [Google ADK](https://google.github.io/adk-docs/) (Agent Development Kit). Trace, debug, and monitor every agent invocation, model call, and tool execution with a single `Laminar.initialize()` call. Self-host via Helm or use managed cloud.

ADK is Google's Python framework for building agents: you define an `Agent` with a model, an instruction, and tools, then drive it with a `Runner`. ADK emits its own OpenTelemetry spans for agent invocations, LLM calls, and tool calls. Tracevell routes those spans into your project and enriches them so they read as a conversation.

What Tracevell captures:

* An `invocation` span for each `runner.run_async()` call.
* An agent span named after the agent (for example `travel_assistant`), with the ADK session ID and user ID attached as Tracevell's [session](https://tracevell.com/docs/tracing/structure/sessions.md) and [user ID](https://tracevell.com/docs/tracing/structure/user-id.md).
* A `call_llm` span for every model turn, with the model, token counts, latency, and cost.
* A tool span named after the tool (for example `get_weather`) with the tool's arguments and return value.

## Getting started

**1. Install**

Ensure you have `lmnr` version `0.7.67` or higher and `google-adk` version `2.0.0` or higher:

```bash theme={null}
pip install -U lmnr google-adk
```

**2. Set environment variables**

```bash theme={null}
export LMNR_PROJECT_API_KEY=your-tracevell-project-api-key
export GOOGLE_API_KEY=your-gemini-api-key
```

**3. Initialize Tracevell**

`Laminar.initialize()` auto-instruments ADK when `google-adk` is installed. No ADK telemetry configuration or OTLP exporter setup is needed.

```python {6,8} theme={null}
import asyncio

from google.adk.agents import Agent
from google.adk.runners import InMemoryRunner
from google.genai import types
from lmnr import Tracevell, observe

Laminar.initialize()


def get_weather(city: str) -> dict:
    """Returns the current weather for a city."""
    return {"city": city, "forecast": "sunny", "temperature_c": 22}


def get_local_time(city: str) -> dict:
    """Returns the current local time for a city."""
    return {"city": city, "time": "14:05"}


agent = Agent(
    name="travel_assistant",
    model="gemini-2.5-flash",
    instruction="You are a travel assistant. Use the tools to answer questions about a city.",
    tools=[get_weather, get_local_time],
)


@observe(name="travel-question")
async def main():
    runner = InMemoryRunner(agent=agent, app_name="travel_app")
    session = await runner.session_service.create_session(
        app_name="travel_app", user_id="user-123"
    )
    message = types.Content(
        role="user",
        parts=[types.Part(text="What's the weather and local time in Tokyo?")],
    )
    async for event in runner.run_async(
        user_id="user-123", session_id=session.id, new_message=message
    ):
        if event.is_final_response() and event.content and event.content.parts:
            print(event.content.parts[0].text)


if __name__ == "__main__":
    asyncio.run(main())
```

> [!NOTE]
>
> Wrapping your entry point in `@observe()` is optional but recommended: it creates a root span that captures inputs and outputs and makes the trace easy to find in the UI.

> [!WARNING]
>
> When `google-adk` is installed, Tracevell leaves the [Google Gen AI SDK](https://tracevell.com/docs/integrations/gemini.md) instrumentation out of the default set. ADK's `call_llm` span already records the full request and response, so tracing the underlying `generate_content` call as well would produce two LLM spans for every model turn. If you also call `google-genai` directly outside ADK in the same process and want those calls traced, pass both instruments explicitly:
>
> ```python theme={null}
> from lmnr import Tracevell, Instruments
>
> Laminar.initialize(instruments={Instruments.GOOGLE_ADK, Instruments.GOOGLE_GENAI})
> ```

## See what happened in a trace

Open the trace in Tracevell. The transcript view extracts the user message, each model turn, and every tool call with its arguments and result, so you read the conversation instead of a span tree. Switch to tree view to see how ADK nests `call_llm` and tool spans under the agent span for each `invocation`.

![Google ADK trace in Tracevell: transcript with two Gemini turns and two tool calls, and the call\_llm span's system prompt, user message, and tool calls](https://mintcdn.com/laminarai/HwOHGd8EMPgPHF1z/images/traces/google-adk-transcript.png?fit=max\&auto=format\&n=HwOHGd8EMPgPHF1z\&q=85\&s=39ccd233dbd7062ce532b15ae7b54115)

Transcript of the travel-assistant run. The first Gemini turn calls `get_weather` and `get_local_time` in parallel, the second turn answers. The selected `call_llm` span shows the system instruction, the user message, and the model's tool calls, and the session and user ID from ADK sit in the trace header.

More on the trace UX: [Viewing traces](https://tracevell.com/docs/platform/viewing-traces.md).

## Sessions and users

ADK sessions map to Tracevell sessions automatically. The `session_id` and `user_id` you pass to `runner.run_async()` are attached to each agent span, so every turn of one ADK conversation is grouped under the same [session](https://tracevell.com/docs/tracing/structure/sessions.md) and filterable by [user ID](https://tracevell.com/docs/tracing/structure/user-id.md).

## Message content and privacy

Tracevell reads model and tool content from the attributes ADK itself records, so ADK's content toggle applies to Tracevell too. Set `ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS=false` to keep prompts, responses, and tool payloads out of the trace while still recording span timing, model names, and token counts.

## Track outcomes with Signals

Traces answer *what happened on this run*. **[Signals](https://tracevell.com/docs/signals/introduction.md) answer the cross-trace question**: *how often does the agent call the wrong tool, when does it answer without calling a tool at all, how many runs end without a final response*. A Signal pairs a plain-language instruction with a JSON output schema. Tracevell runs it live on new traces (Triggers) or backfills it across history (Jobs) and records a structured event every time it matches. From there you [query](https://tracevell.com/docs/platform/sql-editor.md), [cluster](https://tracevell.com/docs/signals/clusters.md), and [alert](https://tracevell.com/docs/signals/alerts.md) on events across every trace.

> [!NOTE]
>
> Every new project ships with a **Failure Detector** Signal that categorizes issues on any trace over 1000 tokens. Open it from the Signals sidebar to see events as soon as your ADK traces arrive.

## Query across traces

* **[SQL editor](https://tracevell.com/docs/platform/sql-editor.md)** for ad-hoc queries across traces, spans, signals, and evals.
* **SQL API** for programmatic access from scripts and pipelines.
* **[CLI](https://tracevell.com/docs/platform/cli.md)** (`lmnr-cli sql query`) for terminal-driven queries and piping JSON into shell tools or coding agents.
* **[MCP server](https://tracevell.com/docs/platform/mcp.md)** to query Tracevell directly from Claude Code, Cursor, or Codex.

## Troubleshooting

> [accordion] I don't see any traces in Tracevell
>
> * Confirm `LMNR_PROJECT_API_KEY` is set in the same process that runs the agent.
> * `google-adk` must be installed when `Laminar.initialize()` runs.
> * The integration requires `lmnr >= 0.7.62` and `google-adk >= 2.0.0, < 3.0.0`. `google-adk` 2.10 and later need `lmnr >= 0.7.67` for full prompt and response capture.

> [accordion] LLM spans have no messages, only model, tokens, and cost
>
> Check your versions with `pip show lmnr google-adk`. With `google-adk` 2.10 or later, `lmnr` before 0.7.67 doesn't attach the prompt and response to `call_llm` spans: upgrade with `pip install -U lmnr`. If your versions are fine, check `ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS` (see below).

> [accordion] Tool spans have no input or output
>
> Check whether `ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS` is set to `false`. With content capture off, ADK records tool and model payloads as empty, and Tracevell keeps them empty.

> [accordion] I want to disable the Google ADK integration
>
> Pass `disabled_instruments={Instruments.GOOGLE_ADK}` to `Laminar.initialize()`. The Google Gen AI SDK instrumentation is then enabled again, so Gemini calls are still traced as plain LLM spans.
>
> ```python theme={null}
> from lmnr import Tracevell, Instruments
>
> Laminar.initialize(disabled_instruments={Instruments.GOOGLE_ADK})
> ```

> [accordion] Self-hosting Tracevell
>
> Set `base_url` and the ports of your instance when initializing. For a local OSS deployment:
>
> ```python theme={null}
> Laminar.initialize(
>     base_url="http://localhost",
>     http_port=8000,
>     grpc_port=8001,
> )
> ```

## What's next

> [card] [Viewing traces](https://tracevell.com/docs/platform/viewing-traces.md)
>
> Read the transcript view, filter, and search across traces.

> [card] [Signals](https://tracevell.com/docs/signals/introduction.md)
>
> Detect behaviors and failures across every run, then query, cluster, and alert on them.

> [card] [SQL editor and MCP server](https://tracevell.com/docs/platform/sql-editor.md)
>
> Query traces programmatically from the UI, API, or your IDE.

> [card] [Tracing structure](https://tracevell.com/docs/tracing/structure/overview.md)
>
> Sessions, metadata, and tags for deeper control.

## Related integrations

> [card] [Gemini](https://tracevell.com/docs/integrations/gemini.md)
>
> Calling the Google Gen AI SDK directly without ADK? Trace it here.

> [card] [Pydantic AI](https://tracevell.com/docs/integrations/pydantic-ai.md)
>
> Trace Pydantic AI agents and typed tool calls.

> [card] [OpenAI Agents SDK](https://tracevell.com/docs/integrations/openai-agents-sdk.md)
>
> Trace agent runs, handoffs, and tool calls.

> [card] [LangChain / LangGraph](https://tracevell.com/docs/integrations/langchain.md)
>
> Trace LangChain chains and LangGraph graphs.

> [card] [LiteLLM](https://tracevell.com/docs/integrations/litellm.md)
>
> Running ADK agents on non-Gemini models through `LiteLlm`? See how LiteLLM calls are traced.

> [card] [All integrations](https://tracevell.com/docs/integrations.md)
>
> Browse every provider, framework, coding agent, and browser integration Tracevell supports.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.