Skip to main content

Installation

Quick Start

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 (e.g., gemini-2.5-flash)
  • 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

Configuration

Use setup_google_adk() to automatically patch all ADK Runner instances:

Manual wrapping

Use create_raindrop_google_adk() to wrap specific Runner instances:

Class-based API

Debug Mode

Enable verbose logging to troubleshoot integration issues:
When debug=True, internal telemetry operations (event extraction, interaction lifecycle) are logged at the DEBUG level via Python’s standard logging module.

Projects

Route events to a specific project by passing its slug as project_id:
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 create_raindrop_google_adk(...) and RaindropGoogleADK(...). Invalid slugs are ignored with a warning and no header is sent.

Multiple projects in one process

Available in raindrop-ai>=0.0.56. When one service runs several ADK runners that should report to different projects, create one RaindropGoogleADK wrapper per project. Each wrapper owns its own raindrop.Raindrop client, so the two route independently — there is no shared module-level state:
Each wrapper owns its configuration and delivery pipeline, so runners handled by different wrappers route independently. To share a single client across wrappers (or with the module-level API), construct a raindrop.Raindrop yourself and pass it via client=:
Use wrap() — not setup() — for multiple projects. setup_google_adk() / RaindropGoogleADK.setup() patches the ADK Runner class process-globally, so only the first setup()’s project owns class-wide auto-instrumentation; a second setup() with a different project keeps routing to the first and emits a warning. wrap(runner) instruments a specific runner with that wrapper’s own client, taking precedence over any class-level setup() patch for that runner — so per-runner routing stays correct even if setup() ran earlier in the process.

Identify

Associate a user with traits for downstream analysis:

Track Signal

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

Tool Call Tracking

When your agent uses tools, individual tool spans are captured automatically with name, input, output, duration, and error status:

Multi-Agent Workflows

Google ADK supports complex agent topologies — sequential agents, parallel agents, and nested sub-agents. The integration captures the top-level Runner invocations regardless of agent complexity:
The integration records one ai_generation event per Runner.run() invocation. ADK can mark one final response per participating agent, so for multi-agent invocations the event output is the last non-empty final agent response. Earlier agent responses are not merged into the displayed conversation output. Output-specific metadata such as model, author, agent name, branch, and finish reason comes from that selected response, while token and tool counts cover the full invocation.

Async Usage

The wrapper supports both sync and async runner usage:

Finish Reason Tracking

The integration captures the finish_reason from model responses, indicating why generation stopped. Common values include: This is available in event properties as google_adk.finish_reason.

Token Tracking

Token usage is accumulated across all model calls within a single Runner.run() invocation. The following fields are captured:

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:

Factory Function (backward compat)

The setup_google_adk() and create_raindrop_google_adk() factory functions return RaindropGoogleADK instances and accept the same parameters:
The RaindropGoogleADK class provides identify() and track_signal() methods directly, so you don’t need to import the core SDK separately.