Maple agent tracing: Google ADK (Python and TypeScript)

Goal: one conversation = one ADK session id = one Maple Agent Session, with the transcript (user, assistant, tool calls and results), model calls, tool calls with arguments/results, failures, and tokens.

ADK emits its own OTel spans (scope gcp.vertex.agent): invocation > invoke_agent {agent} > call_llm > generate_content {model}, plus execute_tool {tool}. No instrumentation package is needed. You add: a tracer provider (Runner apps only), the env vars below, one plugin, one span processor.

TypeScript (@google/adk in package.json): follow references/typescript.md instead of Steps 0-7 below. Step 1 (key and region) applies to both. ADK for TypeScript records content differently (Gemini-shaped JSON on gcp.vertex.agent.* attributes, no generate_content span), so the Python env switches and plugin do not apply there.

Step 0: Detect versions and existing setup

• Read pyproject.toml / requirements*.txt / uv.lock. Require google-adk>=2.10; upgrade if lower (before 2.7, gen_ai.system is always gemini and failed tools are not marked ERROR).
• ADK caps opentelemetry-sdk<=1.42.1. Never pin a newer OTel package; let the resolver choose.
• Find how ADK runs:
  • adk web / adk api_server (CLI): ADK builds the tracer provider from OTEL_EXPORTER_OTLP_* env. Do NOT register another provider.
  • Runner(...) in the app's own code (FastAPI, worker, script, notebook): nothing is exported unless the app registers a provider. You must add one.
• Grep for an existing OTel setup: set_tracer_provider, TracerProvider(, logfire.configure, sentry_sdk.init, maybe_set_otel_providers, opentelemetry-instrument. If one exists, add the Maple processor to that provider instead of creating a second one.
• Grep for double instrumentation and remove it if it only exists for tracing: litellm.callbacks containing "otel", openinference-instrumentation-google-adk / GoogleADKInstrumentor, openinference-instrumentation-litellm, openinference-instrumentation-openai, opentelemetry-instrumentation-openai-v2. Ask the user before removing something another backend relies on.

Step 1: Key and region