Google Agent Development Kit (ADK) Instrumentation

Integrate Google ADK agents into LangWatch to trace actions, tools, and interactions for structured AI agent evaluations.

The Google Agent Development Kit (ADK) builds, orchestrates, and traces generative-AI agents. For more details on ADK, refer to the official Google ADK documentation.

LangWatch captures traces generated by Google ADK through the OpenInference GoogleADKInstrumentor, which patches ADK components to emit OpenTelemetry spans.

Prerequisites

1. Install LangWatch SDK:

   pip install langwatch
   

2. Install Google ADK and OpenInference instrumentor:

   pip install google-adk "openinference-instrumentation-google-adk>=0.1.11"
   
   Use openinference-instrumentation-google-adk>=0.1.11. Google ADK 1.32 moved trace_tool_call out of google.adk.flows.llm_flows.functions, so older instrumentor versions (≤0.1.10) crash with AttributeError: module 'google.adk.flows.llm_flows.functions' has no attribute 'trace_tool_call' on ADK ≥1.32. 0.1.11+ resolves the symbol per ADK version and works across both.

3. Set up Google Cloud authentication: You’ll need to authenticate with Google Cloud. You can either:

   • Set the GOOGLE_API_KEY environment variable for Gemini API access
   • Use Application Default Credentials (ADC) if running on Google Cloud
   • Use service account keys for production deployments

Instrumentation with OpenInference

The OpenInference Google ADK instrumentor captures traces from your ADK agents and sends them to LangWatch.

Basic Setup (Automatic Tracing)

Here’s the simplest way to instrument your application:

Set LANGWATCH_API_KEY in the environment before you run this. Without it the SDK sends nothing.

import langwatch
from google.adk import Agent, Runner
from google.adk.sessions import InMemorySessionService
from google.genai import types
from openinference.instrumentation.google_adk import GoogleADKInstrumentor
import os

# Initialize LangWatch with the Google ADK instrumentor
langwatch.setup(
    instrumentors=[GoogleADKInstrumentor()]
)

# Set up environment variables
os.environ["GOOGLE_API_KEY"] = "your-gemini-api-key"

# Define your agent tools
def say_hello():
    return {"greeting": "Hello LangWatch 👋"}

def get_weather(location: str):
    return {"location": location, "temperature": "22°C", "condition": "sunny"}

# Create your agent
agent = Agent(
    name="hello_agent",
    model="gemini-2.0-flash",
    instruction="Always greet using the say_hello tool and provide weather information when asked.",
    tools=[say_hello, get_weather],
)

# Set up session service and runner
session_service = InMemorySessionService()
session_service.create_session(
    app_name="hello_app", user_id="demo-user", session_id="demo-session"
)

runner = Runner(agent=agent, app_name="hello_app", session_service=session_service)

# Use the agent as usual. Traces are sent to LangWatch automatically
def run_agent_interaction(user_message: str):
    user_msg = types.Content(role="user", parts=[types.Part(text=user_message)])
    
    for event in runner.run(user_id="demo-user", session_id="demo-session", new_message=user_msg):
        if event.is_final_response():
            return event.content.parts[0].text
    
    return "No response generated"

# Example usage
if __name__ == "__main__":
    user_prompt = "hi"
    response = run_agent_interaction(user_prompt)
    print(f"User: {user_prompt}")
    print(f"Agent: {response}")

That’s it! All Google ADK agent activity will now be traced and sent to your LangWatch dashboard automatically.

Optional: Add metadata with a decorator

To attach metadata to the trace, wrap the call in @langwatch.trace() and run the agent with Runner.run_async:

import asyncio

import langwatch
from google.adk import Agent, Runner
from google.adk.sessions import InMemorySessionService
from google.genai import types
from openinference.instrumentation.google_adk import GoogleADKInstrumentor

langwatch.setup(
    instrumentors=[GoogleADKInstrumentor()]
)

# ... agent setup code ...

@langwatch.trace(name="Google ADK Agent Run")
async def run_agent_interaction(user_message: str):
    # Update the current trace with additional metadata
    current_trace = langwatch.get_current_trace()
    if current_trace:
        current_trace.update(
            metadata={
                "user_id": "user_123",
                "thread_id": "session_abc",
                "labels": ["hello_agent"],
            }
        )

    user_msg = types.Content(role="user", parts=[types.Part(text=user_message)])

    async for event in runner.run_async(
        user_id="demo-user", session_id="demo-session", new_message=user_msg
    ):
        if event.is_final_response():
            return event.content.parts[0].text

    return "No response generated"


asyncio.run(run_agent_interaction("hi"))

Use run_async under the decorator, not the synchronous Runner.run.

Runner.run starts a new Python thread and calls asyncio.run inside it. OpenTelemetry keeps the active trace in a context variable, and a new thread starts with an empty one, so the agent spans open a second, separate trace. The metadata you set stays on the wrapper trace and the agent trace gets none of it.

run_async stays on the caller’s task, so the wrapper span is the parent of invocation, agent_run and call_llm, and all of it is one trace.

If you have to keep the synchronous Runner.run, drop the decorator and let the instrumentor own the trace.

How it Works

1. langwatch.setup(): Initializes the LangWatch SDK, which includes setting up an OpenTelemetry trace exporter. This exporter is ready to receive spans from any OpenTelemetry-instrumented library in your application.

2. GoogleADKInstrumentor(): The OpenInference instrumentor automatically patches Google ADK components to create OpenTelemetry spans for their operations, including:

   • Agent initialization
   • Tool calls
   • Model completions
   • Session management

3. Optional Decorators: You can optionally use @langwatch.trace() to add additional context and metadata to your traces, but it’s not required for basic functionality. The decorator parents the agent spans only over Runner.run_async.

With this setup, LangWatch traces all agent interactions, tool calls, and model completions.

Notes

• You do not need to set any OpenTelemetry environment variables or configure exporters manually. langwatch.setup() handles it.
• You can combine Google ADK instrumentation with other instrumentors (e.g., OpenAI, LangChain) by adding them to the instrumentors list.
• The @langwatch.trace() decorator is optional - the OpenInference instrumentor will capture all ADK activity automatically. Use it with Runner.run_async, never with the synchronous Runner.run.
• For advanced configuration (custom attributes, endpoint, etc.), see the Python integration guide.

Troubleshooting

• Make sure your LANGWATCH_API_KEY is set in the environment.
• If you see no traces in LangWatch, check that the instrumentor is included in langwatch.setup() and that your agent code is being executed.
• Ensure you have the correct Google API key set for Gemini access.
• AttributeError: module 'google.adk.flows.llm_flows.functions' has no attribute 'trace_tool_call' on langwatch.setup(): your openinference-instrumentation-google-adk is too old for your Google ADK version. ADK 1.32 removed that symbol; the fix shipped in instrumentor 0.1.11. Run pip install -U "openinference-instrumentation-google-adk>=0.1.11". If it still fails, confirm the upgrade actually applied in the running interpreter with pip show openinference-instrumentation-google-adk.
• One agent run shows up as two traces, one of them empty except for your decorator span: you wrapped the synchronous Runner.run. Switch to Runner.run_async, or drop the decorator. See the warning above.
• The metadata you set with trace.update() is on a trace with no agent spans: same cause, same fix.