raindrop-google-adk

Raindrop integration for Google ADK (Agent Development Kit) — Google's framework for building AI agents powered by Gemini models.

Wraps Google ADK Runner objects to automatically capture agent invocations, tool calls, and multi-step reasoning, shipping telemetry to Raindrop.

Installation

pip install raindrop-google-adk google-adk

Quick Start

from raindrop_google_adk import setup_google_adk
from google.adk import Runner
from google.adk.agents import LlmAgent
from google.adk.sessions import InMemorySessionService
from google.genai import types

# Enable automatic tracing for all ADK Runner interactions
rd = setup_google_adk(api_key="your-write-key")

# Create your ADK agent as normal
def get_weather(city: str) -> dict:
    """Get weather for a city."""
    return {"temperature": 72, "condition": "sunny", "city": city}

agent = LlmAgent(
    name="weather_assistant",
    tools=[get_weather],
    model="gemini-2.5-flash",
    instruction="You are a helpful assistant that can check weather.",
)

# Create session and runner
session_service = InMemorySessionService()
runner = Runner(app_name="weather_app", agent=agent, session_service=session_service)

# Use the runner as normal — all interactions are automatically traced
user_msg = types.Content(
    parts=[types.Part(text="What's the weather in New York?")],
    role="user",
)
for event in runner.run(user_id="user123", session_id="session123", new_message=user_msg):
    print(event)

What Gets Traced

The Google ADK integration automatically captures:

• Runner invocations — input message, user_id, session_id, app_name
• Agent responses — final output text from the agent
• Token usage — prompt_tokens, completion_tokens, total_tokens from usage metadata
• Tool calls — individual tool spans with name, input, output, duration, and error
• Model info — model version when available
• Agent identity — agent name, author from events
• Finish reason — why generation stopped (e.g., STOP, SAFETY, MAX_TOKENS)
• Errors — captured (with error message) and re-raised to the caller
• Async support — both run() (sync) and run_async() (async) are instrumented

Tool catalog capture (ai.prompt.tools)

Every model span produced under an instrumented Runner.run() / Runner.run_async() records the tools the model was given for that call as ai.prompt.tools. The wrapper registers an ADK plugin on the runner (plugin_manager, name raindrop_prompt_tools) whose before_model_callback reads LlmRequest.config.tools — the exact request ADK then hands to the model — and binds it for the duration of that model call. Capture is exact: ADK builds config.tools per request from the agent's tool processors (function declarations plus built-ins such as google_search), and the callback sees that finished request; the OpenLLMetry google_generativeai / vertexai instrumentors emit no tool definitions themselves. Each function_declarations entry becomes a function tool and other keys (google_search, code_execution, retrieval, url_context, ...) become provider-defined tools. Each tool is one JSON document in an OTLP string array: {"type":"function","name","description","inputSchema"} for function tools (parameters or parameters_json_schema recorded as given — properties, enums, required and per-field descriptions intact) or {"type":"provider-defined","id","name","args"} for provider-owned tools, which get no invented schema. A model call whose request carries no tool list records no attribute; a request with an empty list records [].

Pass tools= to RaindropGoogleADK(...) / setup_google_adk(...) / create_raindrop_google_adk(...) to record a different catalog instead: it replaces the inferred list for every model span of that wrapper's runs (never merges), and tools=[] records an empty catalog. Runner.run() takes no per-call metadata, so there is no per-call override; with setup() the class patch is keep-first, so a second setup() with a different tools warns and keeps the first. Runner.run_live() runs no before_model_callback, so the live flow records only an explicit override (held for the whole stream); without one the attribute stays absent. Tool definitions are prompt content and follow the same switch as prompts: with TRACELOOP_TRACE_CONTENT=false they are never recorded. Model spans only exist when ADK's own tracer is wired to a provider or library instrumentation is enabled (disable_auto_instrument=False), and capture requires raindrop-ai>=0.0.70 (older cores log at debug and record nothing).

Configuration

Auto-instrumentation (recommended)

from raindrop_google_adk import setup_google_adk

rd = setup_google_adk(
    api_key="your-write-key",      # Required: your Raindrop API key. If None, telemetry is disabled.
    user_id="user-123",            # Optional: default user ID for all events
    convo_id="convo-456",          # Optional: conversation/thread ID
    project_id="support-prod",     # Optional: route events to a specific project (slug)
    tracing_enabled=True,          # Optional: enable/disable OTEL tracing (default: True)
    bypass_otel_for_tools=True,    # Optional: bypass OTEL for tool calls (default: True)
    disable_auto_instrument=True,  # Optional: library auto-instrumentation is opt-in (default: True)
    tools=None,                    # Optional: override for the ai.prompt.tools catalog ([] = no tools)
)

# All Runner.run() and Runner.run_async() calls are now automatically traced
# Call rd.shutdown() before process exit

Library auto-instrumentation is opt-in

As of 0.0.10, disable_auto_instrument defaults to True: the integration no longer lets Traceloop monkey-patch every LLM/tool client library it recognizes in your process (Gemini SDK, MCP client, etc.). The wrapper captures input/output, token usage, model name, and tool calls directly from ADK Runner events, so no library patching is needed for full dashboards.

If you specifically want LLM-call-level spans from library instrumentation and have verified compatibility in your environment, opt back in with disable_auto_instrument=False.

Manual wrapping

from raindrop_google_adk import create_raindrop_google_adk

rd = create_raindrop_google_adk(
    api_key="your-write-key",
    user_id="user-123",
)

# Wrap a specific runner instance
wrapped_runner = rd.wrap(runner)

# Use wrapped_runner as normal
for event in wrapped_runner.run(...):
    print(event)

rd.shutdown()

Class-based API

from raindrop_google_adk import RaindropGoogleADK

rd = RaindropGoogleADK(
    api_key="your-write-key",
    user_id="user-123",
    tracing_enabled=True,
    bypass_otel_for_tools=True,
    debug=False,
)

# Auto-patch all Runner instances
rd.setup()

# Or wrap a specific runner
wrapped = rd.wrap(runner)

# Cleanup
rd.shutdown()

Projects

Route events to a specific project by passing its slug as project_id:

rd = setup_google_adk(
    api_key="your-write-key",
    project_id="support-prod",
)

project_id sets the X-Raindrop-Project-Id header on every event. Omit it (or pass "default") to use your org's default Production project, which is the existing behavior. The same option is accepted by the create_raindrop_google_adk(...) factory and the RaindropGoogleADK(...) class. Invalid slugs are ignored with a warning and no header is sent.

Debug Mode

Enable verbose logging to troubleshoot integration issues:

rd = RaindropGoogleADK(
    api_key="your-write-key",
    debug=True,  # Enables DEBUG-level logging
)

Identify

Associate a user with traits for downstream analysis:

rd.identify(
    user_id="user-123",
    traits={"plan": "pro", "company": "Acme"},
)

Track Signal

Track feedback, edits, or custom signals tied to a specific event:

rd.track_signal(
    event_id="evt-abc123",
    name="thumbs_up",
    signal_type="feedback",
    sentiment="POSITIVE",
    comment="Great response!",
)

Async Usage

The wrapper supports both sync and async runner usage:

import asyncio

async def main():
    user_msg = types.Content(
        parts=[types.Part(text="What's the weather?")],
        role="user",
    )
    async for event in runner.run_async(
        user_id="user123",
        session_id="session123",
        new_message=user_msg,
    ):
        if event.is_final_response():
            print(event.content.parts[0].text)

    rd.shutdown()

asyncio.run(main())

For multi-agent runs, one Raindrop ai_generation event is recorded per Runner.run() invocation. Since ADK can produce a final response for each participating agent, the event output uses the last non-empty final response; earlier agent responses are not merged into the conversation output. Model and agent metadata describe that selected response, while token and tool counts cover the full invocation.

Captured Properties

Each event includes the following properties when available:

Flushing and Shutdown

Always call shutdown() before your process exits to ensure all telemetry is shipped:

rd.flush()     # flush pending events without releasing resources
rd.shutdown()  # flush + release resources

Full Documentation

See the full documentation for detailed API reference, configuration options, and advanced usage.

Application Git metadata

RaindropGoogleADK(...), create_raindrop_google_adk(...), and setup_google_adk(...) accept the keyword-only app_git option. It defaults to True: explicit Raindrop Git environment or deployment context is applied immediately, and the base SDK may perform one bounded background local-Git lookup from the process working directory. Event capture, flush, and shutdown never wait for that lookup. Pass False to disable enrichment, or pass an AppGitOptions mapping with commit_sha, commit_dirty, branch, source_directory, detect_branch, and/or auto_detect. Automatic branch discovery remains opt-in through detect_branch=True (or RAINDROP_GIT_DETECT_BRANCH=true).

For an ordinary in-process application, the process working directory is treated as the application-under-test checkout. A remote, coding, workflow, or observer process must not rely on its own checkout: pass app_git=False, provide explicit revision values, or set source_directory to the actual application checkout. Canonical per-operation properties remain authoritative. When supplying client=, configure app_git while constructing that Raindrop client; the supplied client is authoritative and the wrapper's app_git argument does not reconfigure it.

Release order is deliberate: first publish the base SDK feature, then publish the wrapper feature release with its minimum dependency coordinated to that base release. The existing raindrop-ai lower bound remains compatible, but application Git metadata is unavailable on an older core and must not be claimed complete until the base is upgraded. Until coordination assigns a released version, the wrapper checks for an explicit base app_git parameter and omits the option when unsupported. Explicit non-default configuration is debug-logged and omitted. Unsupported app_git is determined by signature inspection before construction, not by retrying initialization after a TypeError; Git configuration adds no initialization attempts and does not change any existing framework-specific initialization fallback.

Testing

cd packages/google-adk-python
pip install -e ".[dev]"
pytest   # unit tests (no external services)

End-to-end behavior is verified by the cross-SDK conformance harness. This package ships a thin conformance driver at conformance/driver.py that maps the shared scenario corpus onto the wrapper's public API; known gaps are tracked as ticket-linked entries in conformance/failures.txt. The fault lane runs on every PR touching packages/*-python/** (.github/workflows/conformance-wrappers-python.yml) against a local capture server; the prod lane verifies delivery by reading back through the public Query API. The harness is pinned by commit SHA (HARNESS_REF). See the harness docs: HOW-IT-WORKS · AGENTS · README.