Google ADK

Available for: Python and TypeScript.

Zespan provides first-class tracing for Google’s Agent Development Kit (ADK). Every model call, tool invocation, and agent-to-agent delegation in your ADK workflow is captured as a linked span — without modifying your agent definitions.

TypeScript

Installation

npm install @zespan/sdk @google/adk

Four integration patterns

Choose the integration pattern that fits your setup:

Pattern	Use when
`instrumentADK`	Production apps — wraps agent + runner in one call
`wrapADKRunner`	You manage the runner lifecycle separately
`ZespanADKCallbackHandler`	Native ADK callbacks — wire into `LlmAgent` config
`wrapADKAgent`	Tests and scripts — direct agent wrapping

`instrumentADK` — recommended for production

instrumentADK wraps both your coordinator agent and its runner in a single call. Use this when building production ADK applications.

import { zespan, instrumentADK } from "@zespan/sdk";
import { Agent, InMemoryRunner } from "@google/adk";

zespan.init({ apiKey: process.env.ZESPAN_API_KEY! });

// Your normal ADK setup
const policyAgent = new Agent({
  model: "gemini-3.8-flash",
  name: "PolicyAgent",
  instructions: "Check refund policies and eligibility.",
});

const orderAgent = new Agent({
  model: "gemini-3.8-flash",
  name: "OrderAgent",
  instructions: "Look up order details by order ID.",
});

const coordinator = new Agent({
  model: "gemini-3.1-pro-preview",
  name: "SupportCoordinator",
  subAgents: [policyAgent, orderAgent],
  instructions: "Route customer requests to the right specialist.",
});

const runner = new InMemoryRunner({ agent: coordinator });

// Wrap both at once — returns instrumented versions
const { coordinator: tracedCoordinator, runner: tracedRunner } = instrumentADK({
  coordinator,
  runner,
  agentName: "SupportCoordinator",
  agentRole: "coordinator",
  sessionId: req.sessionId,
});

// Use tracedRunner exactly as you would the original runner
for await (const event of tracedRunner.runEphemeral({ userId: "u1", newMessage })) {
  // handle ADK events
}

`wrapADKRunner` — runner-level wrapping

Wraps InMemoryRunner.runEphemeral() and Runner.run() by intercepting the ADK event stream. Emits one span per agent author turn, one span per tool call, and handoff spans on delegation.

import { zespan, wrapADKRunner } from "@zespan/sdk";
import { InMemoryRunner } from "@google/adk";

zespan.init({ apiKey: process.env.ZESPAN_API_KEY! });

const runner = wrapADKRunner(
  new InMemoryRunner({ agent: coordinator }),
  {
    agentName: "SupportCoordinator",
    agentRole: "coordinator",
    model: "gemini-3.1-pro-preview",
    sessionId: req.session.id,
  }
);

for await (const event of runner.runEphemeral({ userId: "u1", newMessage })) {
  if (event.content) {
    console.log(event.content.parts[0].text);
  }
}

wrapADKRunner options:

string

required

Display name for the root agent span in Zespan.

string

default:"coordinator"

Role hint for the agent registry. Use "coordinator" for orchestrators and "specialist" for sub-agents.

string

The model name used by the root agent. Shown in the trace detail panel.

string

Associates all spans from this run with a session in the Sessions view.

Record<string, string> | (agentName: string) => Record<string, string>

Extra key-value metadata merged into each span’s metadata, for example the routing surface or tier an agent runs on. Pass a function to give each agent its own values. wrapADKAgent accepts it too and passes it to sub-agents.

wrapADKAgent reads the model from the agent’s model — a string, or an ADK BaseLlm instance (its model id is used). Per-call spans record the model that actually answered when the response reports a modelVersion, for example after a failover to another model.

`ZespanADKCallbackHandler` — native ADK callbacks

Uses ADK’s built-in callback system (beforeAgentCallback, afterModelCallback, etc.). Create one handler instance and spread .callbacks into your LlmAgent config. Captures agent spans, LLM spans with full token counts, and tool call spans.

import { zespan, ZespanADKCallbackHandler } from "@zespan/sdk";
import { LlmAgent, InMemoryRunner, RunConfig } from "@google/adk";

zespan.init({ apiKey: process.env.ZESPAN_API_KEY! });

const tracer = new ZespanADKCallbackHandler();

const agent = new LlmAgent({
  name: "SupportAgent",
  model: "gemini-3.8-flash",
  instruction: "Help customers with order questions.",
  tools: [lookupOrder],
  ...tracer.callbacks, // wires all 6 callbacks
});

const runner = new InMemoryRunner({
  agent,
  plugins: [tracer.plugin], // records a tool that throws as an error
});

for await (const event of runner.runEphemeral({ userId: "u1", newMessage })) {
  // handle events
}

ADK for TypeScript reports a tool that throws only to plugins, never to the agent callbacks. Without plugins: [tracer.plugin], a tool that throws is recorded as a successful tool span, and the SDK prints one warning the first time a tool returns nothing. Register the plugin next to the callbacks: it adds no second span, never throws into your run and leaves your tool’s error unchanged. tracer.plugin is never null. Use one handler per runner (ADK refuses two plugins with the same name). ADK does not report a thrown value that is not an Error (for example a string) to plugins, so such a tool is still recorded as successful: throw Error objects.

Python needs no plugin: ADK for Python calls the agent’s error callback, which handler.callbacks includes. For multi-agent systems, use the same handler instance across all agents so spans share the same trace:

const tracer = new ZespanADKCallbackHandler();

const policyAgent = new LlmAgent({
  name: "PolicyAgent",
  model: "gemini-3.8-flash",
  ...tracer.callbacks,
});

const coordinator = new LlmAgent({
  name: "Coordinator",
  model: "gemini-3.1-pro-preview",
  subAgents: [policyAgent],
  ...tracer.callbacks,
});

ZespanADKCallbackHandler is also exported as ADKCallbackHandler for shorter imports:

import { ADKCallbackHandler } from "@zespan/sdk";

`wrapADKAgent` — agent-level wrapping

Wraps agent.run() directly. Best for unit tests and simple scripts. Recursively wraps subAgents by default.

import { zespan, wrapADKAgent } from "@zespan/sdk";

zespan.init({ apiKey: process.env.ZESPAN_API_KEY! });

const tracedAgent = wrapADKAgent(coordinator, {
  agentName: "SupportCoordinator",
  agentRole: "coordinator",
  traceSubAgents: true, // wrap all subAgents recursively
});

const result = await tracedAgent.run("I need a refund for order #123");

What gets captured

All three wrappers capture the same data from the ADK event stream:

ADK event	Zespan span
Agent turn start/end	`span_kind: "agent"` with latency, model, token counts
Tool call	`span_kind: "tool"` with tool name, args, result
Sub-agent delegation	`span_kind: "handoff"` with target agent name
Model response	Token counts (including cached + reasoning tokens), finish reason

Capture v2 (off by default)

Turn on capture_v2=True (Python) or captureV2: true (TypeScript), or set ZESPAN_CAPTURE_V2=1, and ZespanADKCallbackHandler also records what the trace checks read:

Tool results as JSON (redacted before they are cut), instead of a text copy of an object. An empty result (None, [], {}) is kept and marked empty, and a result cut at 10,240 characters is marked as cut.
Tool definitions the model was offered, with parameter schemas, and the model’s requested tool calls with their ids, so a request can be matched to the tool span that ran it, and a request for a tool that does not exist (which ADK refuses before any tool runs) can be seen.
The conversation as structured messages (text, function calls and function responses with roles), instead of one block of role: text lines, plus the system instructions and the output schema.
Agent text: each agent span carries the text its agent received and the last text it produced, so an answer written by a sub-agent after a transfer is found. Each agent span’s parent_agent_id is its direct parent.
A small marker per span saying which of these were captured, absent, cut or unavailable.

All of it follows prompt and tool storage and goes through the same redaction as stored prompts. With v2 on and the GenAI client also instrumented, one model call is still one span. ZESPAN_CAPTURE_V2=0 turns it off. Upgrade note: older versions of the handler stored tool results as text copies of Python objects; with v2 on, new traces store JSON. See Capture fields.

Agent steps and handoffs

ZespanADKCallbackHandler records on each agent span the number of model calls the agent made (zespan.agent.step), how many sub-agents it could hand to (zespan.agent.route_candidates) and, when the model asked to transfer to another agent, zespan.agent.stop_reason: handoff with the target in zespan.agent.route. wrapADKRunner and, in Python, wrap_adk_agent record a handoff span when work passes from one agent to another (in Python, when a wrapped agent runs inside another wrapped agent; the span carries both agents’ names). See Agent steps.

Tool calls join the tool’s trace

With the callback handler, a model, MCP or HTTP call made inside a tool belongs to the tool’s span and to the run’s trace: the handler makes the tool’s span the current context in beforeToolCallback / before_tool_callback and restores it in the after callback. In Python, a tool that raises is handled by on_tool_error_callback, which is included in handler.callbacks when your ADK version has that callback. In TypeScript the plugin (plugins: [handler.plugin]) does this for a tool that throws, because ADK for TypeScript calls its error hook only on plugins. Tools running in parallel each see their own span.

Prompt storage off

With storePrompts: false (TypeScript) or store_prompts=False (Python), the Google ADK integration sends no content from your agents — the same in both SDKs:

No prompt or completion text
No tool-call arguments, tool results, or the model’s decision rationale
On an agent error event, only the error class name (for example RateLimitError) instead of the provider’s error text, which can quote the prompt. The error is still classified.

Tool names are still sent, so tool usage still shows in the dashboard. With prompt storage on (the default), content is sent as before, and ADK error messages go through the same redaction as stored prompts. See PII redaction.

Python

Installation

pip install zespan google-adk

Three integration patterns

Pattern	Use when
`ZespanADKCallbackHandler`	Native ADK callbacks — wire into `LlmAgent` constructor
`ZespanADKTracer`	Class-based — attach to an existing agent instance
`wrap_adk_agent`	Functional — wrap and return the agent in one call

`ZespanADKCallbackHandler` — native ADK callbacks

Uses ADK’s built-in callback system. Create one handler and spread .callbacks into each LlmAgent constructor. Captures agent spans, LLM spans with full token counts, and tool spans. ADK Python is async — run agents with InMemoryRunner inside asyncio.run(). Single agent:

import asyncio
import zespan
from google.adk.agents import LlmAgent
from google.adk.runners import InMemoryRunner
from google.genai.types import Content, Part
from zespan import ZespanADKCallbackHandler

zespan.init(api_key="zsp_your_api_key_here")

def lookup_order(order_id: str) -> dict:
    """Look up an order by ID to get status and delivery details."""
    return {"orderId": order_id, "status": "delivered", "total": 49.99}

handler = ZespanADKCallbackHandler()

agent = LlmAgent(
    name="SupportAgent",
    model="gemini-3.8-flash",
    instruction="Help customers with order questions.",
    tools=[lookup_order],
    **handler.callbacks,  # wires all 6 callbacks
)

async def run(message: str) -> str:
    runner = InMemoryRunner(agent=agent, app_name="my-app")
    session = await runner.session_service.create_session(
        app_name="my-app", user_id="user-123",
    )
    new_message = Content(role="user", parts=[Part(text=message)])
    response = ""
    async for event in runner.run_async(
        user_id="user-123",
        session_id=session.id,
        new_message=new_message,
    ):
        if event.is_final_response() and event.content:
            response = "".join(p.text for p in event.content.parts if getattr(p, "text", ""))
    return response

result = asyncio.run(run("What is the status of order #ORD-123?"))
print(result)

Multi-agent system: Use the same handler instance across all agents — ADK shares the same invocation_id across coordinator and sub-agents, so all spans are automatically linked under one trace.

import asyncio
import zespan
from google.adk.agents import LlmAgent
from google.adk.runners import InMemoryRunner
from google.genai.types import Content, Part
from zespan import ZespanADKCallbackHandler

zespan.init(api_key="zsp_your_api_key_here")

def lookup_order(order_id: str) -> dict:
    """Look up an order by ID."""
    return {"orderId": order_id, "status": "delivered", "total": 49.99}

def process_refund(order_id: str, reason: str) -> dict:
    """Process a refund for an order."""
    return {"success": True, "refundId": f"ref_{order_id}", "eta": "3-5 business days"}

# One handler for the entire agent system
handler = ZespanADKCallbackHandler()

order_agent = LlmAgent(
    name="OrderAgent",
    model="gemini-3.8-flash",
    description="Handles order lookups.",
    instruction="Look up order details and answer questions about order status.",
    tools=[lookup_order],
    **handler.callbacks,
)

refund_agent = LlmAgent(
    name="RefundAgent",
    model="gemini-3.8-flash",
    description="Handles refund requests.",
    instruction="Process refund requests. Always look up the order first.",
    tools=[lookup_order, process_refund],
    **handler.callbacks,
)

coordinator = LlmAgent(
    name="SupportCoordinator",
    model="gemini-3.8-flash",
    description="Routes customer support requests.",
    instruction=(
        "Route requests to the correct specialist:\n"
        "- OrderAgent: order status, tracking\n"
        "- RefundAgent: refunds, returns\n"
        "Always delegate — do not answer directly."
    ),
    sub_agents=[order_agent, refund_agent],
    **handler.callbacks,
)

async def run(message: str, user_id: str) -> str:
    runner = InMemoryRunner(agent=coordinator, app_name="support")
    session = await runner.session_service.create_session(
        app_name="support", user_id=user_id,
    )
    new_message = Content(role="user", parts=[Part(text=message)])
    response = ""
    async for event in runner.run_async(
        user_id=user_id,
        session_id=session.id,
        new_message=new_message,
    ):
        if event.is_final_response() and event.content:
            response = "".join(p.text for p in event.content.parts if getattr(p, "text", ""))
    return response

result = asyncio.run(run("I need a refund for order #ORD-456", user_id="user-123"))
print(result)

Tool functions are plain Python functions with type hints and docstrings — ADK auto-generates the function declarations. Return dict or any JSON-serializable value.

`ZespanADKTracer` — attach to an existing agent

Pass your ADK agent to ZespanADKTracer after creating it. The tracer intercepts agent.run to capture every model call, tool invocation, and agent session as hierarchical spans.

import zespan
from google.adk import Agent
from zespan import ZespanADKTracer

zespan.init(api_key="zsp_your_api_key_here")

def lookup_order(order_id: str) -> dict:
    """Look up an order by ID."""
    return {"id": order_id, "status": "delivered", "total": 49.99}

agent = Agent(
    model="gemini-3.1-pro-preview",
    tools=[lookup_order],
    instructions="Help customers with order questions.",
)

# Attach the tracer — all subsequent runs are instrumented
ZespanADKTracer(agent)

response = await agent.run("What is the status of order #ORD-123?")
print(response.text)

`wrap_adk_agent` — callback-handler style

wrap_adk_agent is the functional equivalent: it attaches tracing and returns the same agent. Use this when you want a one-liner or are composing agents inline.

import zespan
from google.adk import Agent
from zespan import wrap_adk_agent

zespan.init(api_key="zsp_your_api_key_here")

agent = wrap_adk_agent(
    Agent(
        model="gemini-3.1-pro-preview",
        tools=[lookup_order],
        instructions="Help customers with order questions.",
    )
)

response = await agent.run("What is the status of order #ORD-123?")

wrap_adk_agent is deprecated and warns once. Current ADK agents do not have the method it patches, and it never sent the agent’s instructions. Use ZespanADKCallbackHandler.

Both ZespanADKTracer and wrap_adk_agent accept an optional guardrails argument:

from zespan import wrap_adk_agent

agent = wrap_adk_agent(agent, guardrails={"pre": True, "post": True})

Multi-agent systems

from google.adk import Agent
from zespan import ZespanADKTracer

# Sub-agents
policy_agent = Agent(model="gemini-3.8-flash", name="PolicyAgent")
order_agent = Agent(model="gemini-3.8-flash", name="OrderAgent")

# Coordinator
coordinator = Agent(
    model="gemini-3.1-pro-preview",
    name="SupportCoordinator",
    sub_agents=[policy_agent, order_agent],
)

# Attach tracer to the coordinator — sub-agents are traced automatically
ZespanADKTracer(coordinator)

response = await coordinator.run("I want to return my order from last week.")

Attach ZespanADKTracer (or call wrap_adk_agent) after the agent is fully configured. Attaching before sub_agents are set means sub-agent spans won’t be linked correctly.

How multi-agent traces look in the dashboard

A coordinator + specialist ADK run produces a trace like this:

SupportCoordinator (agent)        ──────────────────────────────── 3.2s
  ├── gemini-3.1-pro-preview (llm)  ──────────── 1.1s
  │     → tool_calls: [OrderAgent.run]
  ├── OrderAgent → handoff        ─ 4ms
  ├── OrderAgent (agent)          ────────────────── 1.8s
  │   ├── gemini-3.8-flash (llm)  ─────── 820ms
  │   └── lookup_order (tool)     ── 12ms
  └── gemini-3.1-pro-preview (llm)  ──── 280ms  finish_reason: stop

Each agent’s total token cost is shown separately in the agent registry view, which also maps the coordinator-specialist hierarchy visually.

Multi-agent trace visualization in Zespan showing coordinator and specialist agent spans

Session and user context

To associate ADK traces with a user session for the Sessions dashboard view, set sessionId and userId in the wrapper options (TypeScript) or via with_zespan_context (Python):

TypeScript
Python

const { runner: tracedRunner } = instrumentADK({
  coordinator,
  runner,
  agentName: "SupportCoordinator",
  sessionId: req.session.id, // links to Sessions view
});

from zespan import with_zespan_context

async def handle_request(user_id: str, session_id: str, message: str):
    with with_zespan_context(user_id=user_id, session_id=session_id):
        return await agent.run(message)

Next steps

Capture fields — what each check reads and which switch controls it.
MCP — tool spans from an ADK MCP toolset carry the tool and server name, and the calls the toolset makes through the MCP client are traced.
Agent tracing — add agent identity, tool roles and approvals.

Overview

CLI

TypeScript SDK

Python SDK

Advanced SDK Configuration

Integrations

LLM Providers

Agent Frameworks

RAG Frameworks

Gateways

Vector Databases

Custom / Other

Guides

TypeScript

Installation

Four integration patterns

`instrumentADK` — recommended for production

`wrapADKRunner` — runner-level wrapping

`ZespanADKCallbackHandler` — native ADK callbacks

`wrapADKAgent` — agent-level wrapping

What gets captured

Capture v2 (off by default)

Agent steps and handoffs

Tool calls join the tool’s trace

Prompt storage off

Python

Installation

Three integration patterns

`ZespanADKCallbackHandler` — native ADK callbacks

`ZespanADKTracer` — attach to an existing agent

`wrap_adk_agent` — callback-handler style

Multi-agent systems

How multi-agent traces look in the dashboard

Session and user context

Next steps

​TypeScript

​Installation

​Four integration patterns

​instrumentADK — recommended for production

​wrapADKRunner — runner-level wrapping

​ZespanADKCallbackHandler — native ADK callbacks

​wrapADKAgent — agent-level wrapping

​What gets captured

​Capture v2 (off by default)

​Agent steps and handoffs

​Tool calls join the tool’s trace

​Prompt storage off

​Python

​Installation

​Three integration patterns

​ZespanADKCallbackHandler — native ADK callbacks

​ZespanADKTracer — attach to an existing agent

​wrap_adk_agent — callback-handler style

​Multi-agent systems

​How multi-agent traces look in the dashboard

​Session and user context

​Next steps

TypeScript

Installation

Four integration patterns

`instrumentADK` — recommended for production

`wrapADKRunner` — runner-level wrapping

`ZespanADKCallbackHandler` — native ADK callbacks

`wrapADKAgent` — agent-level wrapping

What gets captured

Capture v2 (off by default)

Agent steps and handoffs

Tool calls join the tool’s trace

Prompt storage off

Python

Installation

Three integration patterns

`ZespanADKCallbackHandler` — native ADK callbacks

`ZespanADKTracer` — attach to an existing agent

`wrap_adk_agent` — callback-handler style

Multi-agent systems

How multi-agent traces look in the dashboard

Session and user context

Next steps