Python SDK

Integrate tracing into your Google ADK agents

Installation

pip install watchtower-adk

Quick Start

import os
from google.adk import Agent
from watchtower import AgentTracePlugin

# Create the plugin
plugin = AgentTracePlugin(
    # Enable stdout streaming for live tail
    enable_stdout=os.environ.get("WATCHTOWER_LIVE") == "1",
    # Use run ID from CLI if provided
    run_id=os.environ.get("WATCHTOWER_RUN_ID"),
)

# Add to your agent
agent = Agent(
    name="my_agent",
    model="gemini-2.0-flash",
    plugins=[plugin],
)

# Run your agent as normal
result = agent.run("Hello, world!")

AgentTracePlugin

The main class for integrating with Google ADK:

from watchtower import AgentTracePlugin

plugin = AgentTracePlugin(
    # Enable writing to stdout (for live streaming)
    enable_stdout: bool = False,

    # Enable writing to file
    enable_file: bool = True,

    # Custom run ID (auto-generated if not provided)
    run_id: str | None = None,

    # Custom output directory
    output_dir: str | None = None,  # Default: ~/.watchtower/traces

    # Fields to sanitize from events
    sanitize_fields: list[str] = ["api_key", "password", "secret"],
)

Configuration Options

Option	Type	Default	Description
enable_stdout	bool	False	Write events to stdout for live streaming
enable_file	bool	True	Write events to trace file
run_id	str \| None	None	Custom run identifier
output_dir	str \| None	~/.watchtower/traces	Directory for trace files
sanitize_fields	list[str]	["api_key", ...]	Fields to redact from events

Environment Variables

The SDK respects these environment variables:

Variable	Description
WATCHTOWER_LIVE	Set to "1" to enable stdout streaming
WATCHTOWER_RUN_ID	Override the run ID
WATCHTOWER_TRACE_DIR	Override the trace output directory

Event Types

The SDK emits the following event types:

run.start

Agent execution started

run.end

Agent execution completed

llm.request

LLM API call initiated

llm.response

LLM API response received

tool.start

Tool execution started

tool.end

Tool execution completed

error

Error occurred during execution

Trace File Format

Traces are stored as JSONL (newline-delimited JSON) files:

{"type":"run.start","run_id":"abc123","timestamp":1705329121000,"agent":"my_agent"}
{"type":"llm.request","run_id":"abc123","timestamp":1705329121012,"model":"gemini-2.0-flash"}
{"type":"llm.response","run_id":"abc123","timestamp":1705329121847,"tokens":1203,"duration_ms":835}
{"type":"run.end","run_id":"abc123","timestamp":1705329125234,"success":true}

Security

The SDK automatically sanitizes sensitive fields from trace events. You can customize which fields are sanitized:

plugin = AgentTracePlugin(
    sanitize_fields=[
        "api_key",
        "password",
        "secret",
        "token",
        "authorization",
        "my_custom_secret_field",
    ],
)

Next: Troubleshooting →