Instrument Google ADK agents

​

Overview

• Python
• The ADK building blocks: agents, runners, tools, sessions, and the adk command-line interface
• Environment variables and package installation

• Initialize Arize AX tracing so ADK is instrumented before it runs
• Capture agent runs, model calls, and tool calls as traces with no changes to your agent logic
• Group traces by conversation using ADK sessions
• Verify and read the trace tree in Arize AX

​

Before you start

• An existing agent built with Google ADK
• Python 3.10 or later
• An Arize AX account (sign up)
• Credentials for the model your agent uses. For Gemini, get a GOOGLE_API_KEY from Google AI Studio. ADK also runs other providers, including Anthropic and OpenAI through LiteLlm; see the ADK models guide for what your agent supports.

​

Get your Arize AX credentials

pip install arize-otel \
  openinference-instrumentation-google-adk \
  google-adk

health_coach/
├── __init__.py          # imports tracing first, then the agent
├── agent.py             # your existing agent (unchanged)
└── instrumentation.py   # new: Arize AX tracing setup

import os

from arize.otel import register
from openinference.instrumentation.google_adk import GoogleADKInstrumentor

tracer_provider = register(
    space_id=os.environ["ARIZE_SPACE_ID"],
    api_key=os.environ["ARIZE_API_KEY"],
    project_name=os.environ.get("ARIZE_PROJECT_NAME", "google-adk-app"),
)

# Patch Google ADK so every run, model call, and tool call is traced.
GoogleADKInstrumentor().instrument(tracer_provider=tracer_provider)

from . import instrumentation  # noqa: F401 - configure tracing first
from . import agent  # noqa: F401

from google.adk.agents import Agent


def get_daily_calories(age: int, activity_level: str) -> dict:
    """Recommend a daily calorie target for an age and activity level.

    Args:
        age: The person's age in years.
        activity_level: One of "low", "moderate", or "high".
    """
    base = {"low": 1800, "moderate": 2200, "high": 2600}.get(activity_level, 2000)
    # Metabolism eases with age, so trim the target slightly for older adults.
    if age >= 50:
        base -= 200
    return {"status": "success", "recommended_calories": base}


root_agent = Agent(
    name="health_coach",
    model="gemini-2.5-flash",
    description="A friendly health coach that gives nutrition guidance.",
    instruction=(
        "You are a friendly health coach. Use get_daily_calories to answer "
        "questions about calorie targets. Reply in two concise sentences."
    ),
    tools=[get_daily_calories],
)

ARIZE_SPACE_ID=<your-space-id>
ARIZE_API_KEY=<your-api-key>
ARIZE_PROJECT_NAME=google-adk-app
GOOGLE_API_KEY=<your-gemini-api-key>

# Browser interface, served from the folder containing your agent package.
adk web

# Or run in the terminal, pointed at the agent package.
adk run health_coach

​

Run programmatically

from health_coach import instrumentation  # noqa: F401 - configure tracing first
from health_coach.agent import root_agent

import asyncio

from google.adk.runners import InMemoryRunner
from google.genai import types


async def main() -> None:
    runner = InMemoryRunner(agent=root_agent, app_name="health_coach")
    await runner.session_service.create_session(
        app_name="health_coach", user_id="u1", session_id="s1"
    )
    async for event in runner.run_async(
        user_id="u1",
        session_id="s1",
        new_message=types.Content(
            role="user",
            parts=[types.Part(text="I'm 34 and moderately active. What's my daily calorie target?")],
        ),
    ):
        if event.is_final_response():
            print(event.content.parts[0].text.strip())

    # Short-lived script: flush batched spans before the process exits.
    instrumentation.tracer_provider.force_flush()


asyncio.run(main())

​

What gets captured

• Invocation and agent spans. An invocation CHAIN span wraps each run, and an agent_run AGENT span carries the agent name, input, and final output. Sub-agents nest under the parent agent.
• Model spans. One call_llm LLM span per model call, with the prompt, response, model name, and token counts.
• Tool spans. One execute_tool TOOL span per tool invocation, with the tool name, inputs, and outputs, so you can see what the agent decided to do and what each tool returned.
• Session grouping. The ADK session id, emitted as session.id, which threads related runs into one conversation.

​

Troubleshooting

• No traces in Arize AX. Confirm ARIZE_SPACE_ID and ARIZE_API_KEY are available to the agent, either in the agent folder’s .env or in the shell that runs it. Enable OpenTelemetry debug logs with export OTEL_LOG_LEVEL=debug and rerun.
• ADK spans missing. The tracing module must be imported before the agent module in the package’s __init__.py, so GoogleADKInstrumentor().instrument(...) runs before ADK executes the agent.
• A short-lived script exports nothing. Spans are batched by default, so a script that exits right after the run can quit before they flush. Call tracer_provider.force_flush() before the process exits. adk web and adk run handle this for you.
• 401 or 403 from the model. Verify the credentials for your model provider are set and valid, and that the key has access to the model your agent requests.
• 404 or model-not-found from the model. Providers occasionally rename or retire model aliases. Swap the model set in your agent for one your key can call.
• No traces from a remote runtime Local instrumentation does not propagate to a remote runtime. Run register(...) and GoogleADKInstrumentor().instrument(...) inside the deployed agent module, not the local driver, and confirm the remote environment has your Arize credentials.

​

Next steps