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

# Google ADK

> Connect Google Agent Development Kit to Toqan Router via OpenTelemetry. Trace agent workflows, tool calls, and Gemini model interactions.

> [card] [Observability](#observability)
>
> Instrument your code with OpenTelemetry to capture traces, logs, and metrics for every LLM call, agent step, and tool use.

## Observability

This guide covers Python. For Java installation and examples, see the [Google ADK Java quickstart](https://google.github.io/adk-docs/get-started/java/).

### Getting Started

Google Agent Development Kit (ADK) is a flexible, model-agnostic framework for developing and deploying AI agents. ADK simplifies building complex agent architectures with workflow orchestration, tool integration, and multi-agent collaboration. Integrate with Toqan Router to monitor agent behavior, track tool usage, analyze workflows, and optimize your agent systems.

### Prerequisites

Before you begin, ensure you have:

* A Toqan Router account and API Key
* Google API key (for model access)
* Python 3.11+
* Google ADK installed in your project

### Install Dependencies

**Python:**

```bash Bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
pip install google-adk openinference-instrumentation-google-adk opentelemetry-sdk opentelemetry-exporter-otlp-proto-http opentelemetry-instrumentation-httpx opentelemetry-instrumentation-requests opentelemetry-instrumentation-aiohttp-client httpx requests aiohttp
```

### Configure Toqan Router

Set up your environment variables to connect to Toqan Router's OpenTelemetry collector:

**Unix/Linux/macOS:**

```bash Bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export OTEL_EXPORTER_OTLP_ENDPOINT="https://router.toqan.ai/eu/v2/otel"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <TOQAN_API_KEY>"
export OTEL_RESOURCE_ATTRIBUTES="service.name=google-adk-app,service.version=1.0.0"
export GOOGLE_API_KEY="your-google-api-key"
```

**Windows (PowerShell):**

```bash Bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
$env:OTEL_EXPORTER_OTLP_ENDPOINT = "https://router.toqan.ai/eu/v2/otel"
$env:OTEL_EXPORTER_OTLP_HEADERS = "Authorization=Bearer <TOQAN_API_KEY>"
$env:OTEL_RESOURCE_ATTRIBUTES = "service.name=google-adk-app,service.version=1.0.0"
$env:GOOGLE_API_KEY = "your-google-api-key"
```

**Using .env file:**

```bash Bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
OTEL_EXPORTER_OTLP_ENDPOINT=https://router.toqan.ai/eu/v2/otel
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer <TOQAN_API_KEY>
OTEL_RESOURCE_ATTRIBUTES=service.name=google-adk-app,service.version=1.0.0
GOOGLE_API_KEY=your-google-api-key
```

### Integrations

Use the OpenInference Google ADK instrumentor to capture OpenInference spans and propagate trace context to model requests.

### Instrument Google ADK

Initialize the integration before creating Gemini clients or running Agents. Pass the existing `TracerProvider` when OpenTelemetry is already configured. Call `GoogleADKInstrumentor().instrument(tracer_provider=provider)` once during startup.

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from openinference.instrumentation.google_adk import GoogleADKInstrumentor
from opentelemetry.instrumentation.httpx import HTTPXClientInstrumentor
from opentelemetry.instrumentation.requests import RequestsInstrumentor
from opentelemetry.instrumentation.aiohttp_client import AioHttpClientInstrumentor
from opentelemetry.propagate import set_global_textmap
from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator
from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor

provider = TracerProvider()
provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
trace.set_tracer_provider(provider)

GoogleADKInstrumentor().instrument(tracer_provider=provider)
set_global_textmap(TraceContextTextMapPropagator())
HTTPXClientInstrumentor().instrument(tracer_provider=provider)
RequestsInstrumentor().instrument(tracer_provider=provider)
AioHttpClientInstrumentor().instrument(tracer_provider=provider)

# Now use ADK normally - all agent operations will be traced
import google.adk as adk
from google.adk.runners import Runner
from google.adk.sessions import InMemorySessionService
from google.genai import types
import asyncio


def get_weather(location: str) -> str:
    """Return current weather for a location."""
    return f"Sunny in {location}, 22C"


async def main():
    # Create an agent with a tool
    agent = adk.Agent(
        name="Helper",
        instruction="Use the provided tool to answer questions briefly.",
        model="gemini-2.5-flash",
        tools=[get_weather],
    )

    # Create session and runner
    session_service = InMemorySessionService()
    runner = Runner(
        agent=agent,
        app_name="simple-helper",
        session_service=session_service
    )

    # Create a session (await the async call)
    session = await session_service.create_session(
        app_name="simple-helper",
        user_id="user1"
    )

    # Simple one-shot example
    question = "What's the weather in Paris?"
    content = types.Content(role='user', parts=[types.Part(text=question)])

    # Run the agent (this is also async)
    events = runner.run_async(
        user_id="user1",
        session_id=session.id,
        new_message=content
    )

    # Get the response
    async for event in events:
        if event.is_final_response():
            response = event.content.parts[0].text
            print(f"Q: {question}")
            print(f"A: {response}")

# Run the async main function
if __name__ == "__main__":
    try:
        asyncio.run(main())
    finally:
        provider.force_flush()
        provider.shutdown()
```

### Combine tracing with the AI Gateway

For model requests through `/v3/google`, follow the Google Gen AI SDK setup and keep the OTLP exporter and **AI Gateway** API keys scoped to the same Workspace and Project. The HTTP client instrumentation below propagates W3C `traceparent` and `tracestate` through HTTPX, Requests and aiohttp. Other transports need their own OpenTelemetry instrumentation. Forward these headers through any intermediate proxy.

Requests sent through these instrumented HTTP clients carry the active span context. Do not set a fixed `traceparent` header or reuse one across an Agent session. After setup, confirm that the exported model span and its **AI Gateway** request share a trace ID. Correlated calls can then be counted once in Activity while both traces remain available.

> [!NOTE]
>
> To view more examples of ADK implementation, browse the [Google ADK Samples repository](https://github.com/google/adk-samples)

### Next Steps

**Verify your Traces** in the **Toqan Router** Studio.

> [!NOTE]
>
> To learn more about the capabilities of Traces in Toqan Router, see [Traces](/docs/ai-studio/observability/traces.md)


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