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",            # Required: events without a user id are not sent
    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!",
)

Per-call properties and identity

Runner.run() / run_async() / run_live() has no channel for your own event properties, so wrap the call in event_context. Its properties merge into every event captured inside the block, and user_id / convo_id replace the run's user and session for those events:

from raindrop_google_adk import event_context

with event_context(properties={"plan": "pro"}):
    for event in runner.run(user_id="user-123", session_id="s1", new_message=message):
        ...

Updating the last event

last_event_id is the event_id of the most recent event this wrapper captured. Use it to attach a signal, or reopen the event with resume_interaction() (defaults to last_event_id) and update it through the core SDK's Interaction:

interaction = rd.resume_interaction()
if interaction is not None:
    interaction.set_properties({"reviewed": True})
    interaction.finish()

Key clashes. If one of your properties has the same key as one the wrapper derives itself, your value wins, whichever update carries it (a debug-level log line names the key). The wrapper's own keys are ai.* (for example ai.usage.prompt_tokens), error/error.* and google_adk.*; avoid them unless you mean to replace the wrapper's value.

Key clashes. If one of your properties has the same key as one the wrapper derives itself, your value wins, whichever update carries it (a debug-level log line names the key). The wrapper's own keys are ai.* (for example ai.usage.prompt_tokens), error/error.* and google_adk.*; avoid them unless you mean to replace the wrapper's value.

Property-only updates need raindrop-ai 0.0.76 or newer; older core versions drop an update that carries no input or output; the wrapper logs one warning when it resumes an event on such a core.

last_event_id is per wrapper instance; under concurrent calls it is whichever event was captured last, so pass event_id= when you need to correlate concurrent calls. Inside a run, get_active_interaction() returns the in-flight interaction instead.

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

Standard options and flush results

When the wrapper builds its own client, it accepts the core SDK's standard options by the same names and passes them on:

raindrop = RaindropGoogleADK(
    api_key="rk_...",
    user_id="user-123",
    redact_pii=True,        # local PII redaction of event input/output
    flush_timeout=5,        # seconds; deadline for flush() and shutdown()
    debug=True,             # also raises the core SDK's log verbosity
    max_queue_size=5_000,   # any other option `Raindrop(...)` declares
)

result = raindrop.flush()   # the core's FlushResult; safe to ignore

• An option the installed raindrop-ai does not support is ignored with a debug log, never an error. flush_timeout and the FlushResult return value need raindrop-ai 0.0.76 or later; on older releases flush() and shutdown() return None.
• With client= (a Raindrop you built), configure these options on that client; the wrapper ignores them (debug log).
• flush() and shutdown() never raise. The result is truthy when everything was delivered, and reports pending, dropped and timed_out.

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.

User id

Every event needs a real user id: set user_id= on the wrapper or per call with event_context(user_id=...). Without one (missing, blank, or a placeholder such as "unknown" or "anonymous"), the event is not sent and the wrapper logs one warning; it never raises. Updating an event you resumed with resume_interaction(event_id=...) needs no user id, since ingest keeps the one it stored.

Model spans

With tracing on (the default), the wrapper records each model response of a run as a google_adk.model_call span on the Raindrop client's tracing, emitted when the response arrives: it starts at its request, ends at its response, and carries that request's tool catalog and the usage the response reported. Its provider and client come from the agent that made the request (a sub-agent included), so an instrumentation that already traced that request suppresses only its span. A custom BaseLlm counts as traced by an SDK's instrumentation only when it holds that SDK's client where the wrapper can see it; otherwise it keeps its span. A run whose events report no per-response usage gets one google_adk.run span with the run's total instead. Each span carries:

• the model: gen_ai.provider.name (canonical name, such as openai or amazon-bedrock), gen_ai.request.model and gen_ai.response.model;
• the token usage the provider reports: gen_ai.usage.input_tokens, output_tokens, cache_read_input_tokens, cache_write_input_tokens and reasoning_tokens;
• the event it belongs to: ai.telemetry.metadata.raindrop.eventId and the traceloop.association.properties.* keys.

Token usage also stays on the event as ai.usage.* properties. When an OpenTelemetry auto-instrumentation already records the model calls (for example with auto_instrument=True on the client), the wrapper adds no span of its own, so a call is never counted twice.

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.