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

# Fiddler Google ADK SDK

> Native monitoring for Google ADK agents with Fiddler's purpose-built SDK

[![PyPI](https://img.shields.io/pypi/v/fiddler-adk)](https://pypi.org/project/fiddler-adk/)

Monitor Google ADK (Agent Development Kit) applications with Fiddler's purpose-built SDK. Get deep visibility into agent reasoning, LLM interactions, and tool execution for ADK-based agent applications.

**Platform Compatibility:** Works with ADK agents using either Google Gemini API keys or Vertex AI authentication.

## What You'll Need

* Fiddler account (cloud or on-premises)
* Google ADK agent application
* Python 3.10 or higher
* Fiddler API key
* Google Gemini API key or Vertex AI credentials

## Quick Start

```bash theme={null}
# Step 1: Install (uv recommended)
uv add fiddler-adk
# or: pip install fiddler-adk
```

```python theme={null}
# Step 2: Set up instrumentation
from fiddler_otel import FiddlerClient
from fiddler_adk import GoogleADKInstrumentor

client = FiddlerClient(
    api_key="YOUR_FIDDLER_API_KEY",
    application_id="YOUR_APPLICATION_UUID",
    url="https://your-fiddler-instance.com",
)
GoogleADKInstrumentor(client).instrument()

# Step 3: Create your ADK agent as usual
from google.adk.agents.llm_agent import Agent

agent = Agent(
    model="gemini-2.5-flash",
    name="my_agent",
    description="A helpful assistant",
    instruction="You are a helpful assistant. Be concise.",
)

# Step 4: Agent calls are automatically traced
# (use Runner to execute the agent — see Quick Start Guide for full example)
```

## What Gets Monitored

### ADK Agent Operations

* **Agent Invocations** (`invoke_agent`) - Full agent execution with timing and session tracking
* **LLM Calls** (`call_llm`) - LLM request/response capture with input, output, system instructions, and tool definitions
* **Tool Execution** (`execute_tool`) - Tool call arguments and return values
* **Model Inference** (`generate_content`) - Token usage, model name, and finish reasons

### Captured Attributes

* **LLM Input/Output** - User prompt text, model response text, system instructions
* **Tool I/O** - Tool call arguments (JSON) and tool response payloads
* **Token Usage** - Input tokens, output tokens, reasoning tokens
* **Agent Identity** - Agent name, agent ID, session/conversation ID
* **Finish Reasons** - LLM stop reason per generation

## Configuration Options

### Programmatic Configuration

```python theme={null}
from fiddler_otel import FiddlerClient
from fiddler_adk import GoogleADKInstrumentor

client = FiddlerClient(
    api_key="YOUR_FIDDLER_API_KEY",
    application_id="YOUR_APPLICATION_UUID",  # UUID4 from Fiddler GenAI Applications
    url="https://your-fiddler-instance.com",
)
GoogleADKInstrumentor(client).instrument()

# All agents created after this point are automatically instrumented
```

### Google Authentication

ADK supports two authentication methods for accessing Gemini models:

```bash theme={null}
# Option A: Gemini API key
export GOOGLE_API_KEY="your-gemini-api-key"

# Option B: Vertex AI (uses gcloud Application Default Credentials)
export GOOGLE_GENAI_USE_VERTEXAI=1
export GOOGLE_CLOUD_PROJECT="your-gcp-project-id"
export GOOGLE_CLOUD_LOCATION="us-central1"
```

### Content Capture

ADK includes full LLM request/response payloads in span attributes by default. To disable payload capture (e.g., for PII protection):

```bash theme={null}
export ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS=false
```

## Example Applications

### Document Processing Agent with Tools

```python theme={null}
import asyncio
from fiddler_otel import FiddlerClient
from fiddler_adk import GoogleADKInstrumentor
from google.adk.agents.llm_agent import Agent
from google.adk.runners import Runner
from google.adk.sessions import InMemorySessionService
from google.genai import types

# Set up Fiddler instrumentation
client = FiddlerClient(
    api_key="YOUR_FIDDLER_API_KEY",
    application_id="YOUR_APPLICATION_UUID",
    url="https://your-fiddler-instance.com",
)
GoogleADKInstrumentor(client).instrument()


# Define tools
def classify_document(doc_type: str, content: str) -> dict:
    """Classify a document into a known category."""
    return {"category": "Credit Memo", "confidence": 0.95}


def extract_fields(document_id: str) -> dict:
    """Extract structured fields from a document."""
    return {"supplier": "McKesson", "total": "$12,450.00"}


# Create agent with tools
agent = Agent(
    model="gemini-2.5-flash",
    name="doc_processor",
    description="Document processing assistant",
    instruction="You classify and extract fields from medical documents.",
    tools=[classify_document, extract_fields],
)


async def main():
    session_service = InMemorySessionService()
    runner = Runner(agent=agent, app_name="demo", session_service=session_service)
    session = await session_service.create_session(app_name="demo", user_id="user1")

    message = types.Content(
        role="user",
        parts=[types.Part(text="Classify this credit memo: supplier McKesson, amount $5000")],
    )

    async for event in runner.run_async(
        user_id="user1", session_id=session.id, new_message=message
    ):
        if hasattr(event, "content") and event.content:
            parts = getattr(event.content, "parts", []) or []
            text = "".join(p.text for p in parts if getattr(p, "text", None))
            if text:
                print(f"Agent: {text}")

    # Flush traces to Fiddler before exit
    client.force_flush(timeout_millis=5000)


asyncio.run(main())
```

[**View complete example -->**](https://github.com/fiddler-labs/fiddler-examples/blob/main/quickstart/latest/Fiddler_Quickstart_Google_ADK_Integration.ipynb)

## Viewing Your Data

Navigate to Fiddler UI to analyze Google ADK agent performance:

1. **Trace Explorer** - View full span trees: agent > LLM > tool hierarchy
2. **Session Analysis** - Multi-turn conversation flows grouped by session
3. **LLM Performance** - Input/output content, token usage, latency
4. **Tool Metrics** - Tool call arguments, responses, and execution time
5. **Cost Tracking** - Token usage per agent session

### Span Types

| ADK Operation      | Fiddler Span Type | Content                                                         |
| ------------------ | ----------------- | --------------------------------------------------------------- |
| `call_llm`         | LLM               | User input, model output, system instructions, tool definitions |
| `invoke_agent`     | Agent             | Agent name, session ID                                          |
| `execute_tool`     | Tool              | Tool arguments, tool response                                   |
| `generate_content` | Span              | Token counts, model name, finish reason                         |
| `invocation`       | Span              | Root span per turn                                              |

## How It Works

Google ADK emits OpenTelemetry spans natively through a tracer named `gcp.vertex.agent`. The `fiddler-adk` SDK:

1. **Sets up an isolated tracing pipeline** via `FiddlerClient` (provider, processor, OTLP exporter) and promotes it to the global tracer provider so ADK's tracer resolves to it.
2. **Propagates session identity** by backfilling `gen_ai.conversation.id` from child spans onto the root `invocation` span, ensuring all spans in a turn share the same session ID.
3. **Delegates content extraction to the Fiddler backend**, which parses ADK's JSON span attributes (`gcp.vertex.agent.llm_request`, etc.) into human-readable fields.

The SDK operates in standalone mode -- it does not interact with customer-configured tracers or providers.

## Troubleshooting

### Traces Not Appearing in Fiddler

**Verify credentials:**

```python theme={null}
from fiddler_otel import FiddlerClient

client = FiddlerClient(
    api_key="YOUR_KEY",
    application_id="YOUR_APP_UUID",
    url="https://your-instance.com",
)
# If credentials are wrong, you'll see 401 errors in logs
```

**Check instrumentation is active:**

```python theme={null}
import logging
logging.basicConfig(level=logging.INFO)
# Look for: "Google ADK instrumentation enabled"
```

**Ensure traces are flushed before exit:**

```python theme={null}
# ADK agents run async — ensure flush before process exits
client.force_flush(timeout_millis=10000)
```

### Missing Content on Spans

Content extraction (LLM input/output, tool I/O) is handled by the Fiddler backend. If you see raw JSON instead of extracted text, ensure your Fiddler instance has the Google ADK backend mapper deployed.

### Orphan Root Spans

If `invocation` root spans appear disconnected from their children, update to the latest `fiddler-adk` version. The `ADKSpanProcessor` backfills `gen_ai.conversation.id` to root spans automatically.

## Related Documentation

* [**Google ADK Quick Start**](/developers/quick-starts/google-adk-quick-start) - Detailed setup guide
* [**Fiddler Evals SDK**](/integrations/agentic-ai/evals-sdk) - Evaluate agent quality
* [**Google ADK SDK Reference**](/sdk-api/adk/google-adk-instrumentor) - Complete class and method documentation