diff --git a/docs/integrations/assets/respan.svg b/docs/integrations/assets/respan.svg new file mode 100644 index 0000000000..583392a044 --- /dev/null +++ b/docs/integrations/assets/respan.svg @@ -0,0 +1,6 @@ + + + + + + diff --git a/docs/integrations/respan.md b/docs/integrations/respan.md new file mode 100644 index 0000000000..d6358eab86 --- /dev/null +++ b/docs/integrations/respan.md @@ -0,0 +1,195 @@ +--- +catalog_title: Respan +catalog_description: Trace, debug, and monitor ADK agents with Respan observability +catalog_icon: /integrations/assets/respan.svg +catalog_tags: ["observability"] +--- + +# Respan observability for ADK + +
+ Supported in ADKPython +
+ +[Respan](https://www.respan.ai/) captures Google ADK runner, agent, model, and +tool spans so you can inspect complete agent workflows in the Respan platform. +The ADK integration uses `respan-instrumentation-google-adk`, which wraps the +OpenInference Google ADK instrumentor and adds Respan-specific span +normalization before traces are exported. + +## Overview + +Use Respan with ADK to: + +- **Trace agent runs**: Capture runner invocations, agent execution, model calls, + and tool calls in one trace. +- **Debug failures**: Inspect span inputs, outputs, timing, and errors across + nested ADK workflows. +- **Track production metadata**: Attach customer, thread, environment, and custom + metadata to all spans from a request. +- **Route models through the Respan gateway**: Use ADK's LiteLLM adapter with + Respan's OpenAI-compatible gateway when you want centralized model routing. + +## Prerequisites + +- Python 3.11, 3.12, or 3.13. +- A [Respan API key](https://platform.respan.ai/platform/api/api-keys). +- A Google API key if your ADK agent calls Gemini directly. + +## Installation + +Install the Respan SDK, the ADK instrumentor, and ADK: + +```bash +pip install respan-ai respan-instrumentation-google-adk "google-adk[extensions]" +``` + +Set the required environment variables: + +```bash +export RESPAN_API_KEY="YOUR_RESPAN_API_KEY" +export GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY" +``` + +`RESPAN_API_KEY` sends traces to Respan. `GOOGLE_API_KEY` is used by direct +Gemini model calls. + +## Trace an ADK agent + +Initialize Respan before running the ADK agent. All ADK runs started after +initialization are traced automatically. + +```python +import asyncio + +from google.adk.agents import Agent +from google.adk.runners import Runner +from google.adk.sessions import InMemorySessionService +from google.genai import types +from respan import Respan +from respan_instrumentation_google_adk import GoogleADKInstrumentor + +respan = Respan( + instrumentations=[GoogleADKInstrumentor()], + environment="development", +) + +agent = Agent( + name="assistant", + model="gemini-2.0-flash", + instruction="You are a concise assistant.", +) + + +async def main(): + session_service = InMemorySessionService() + session = await session_service.create_session( + app_name="respan-adk-demo", + user_id="user_1", + ) + runner = Runner( + agent=agent, + app_name="respan-adk-demo", + session_service=session_service, + ) + message = types.Content( + role="user", + parts=[types.Part(text="Say hello in one sentence.")], + ) + + async for event in runner.run_async( + user_id="user_1", + session_id=session.id, + new_message=message, + ): + if event.is_final_response(): + print(event.content.parts[0].text) + + respan.flush() + respan.shutdown() + + +asyncio.run(main()) +``` + +Open the [Respan traces page](https://platform.respan.ai/platform/traces) to see +the ADK workflow with runner, agent, model, and tool spans. + +## Add request metadata + +Use `propagate_attributes()` to add per-request identifiers and metadata to all +spans produced inside the context. + +```python +from respan import Respan, propagate_attributes +from respan_instrumentation_google_adk import GoogleADKInstrumentor + +respan = Respan(instrumentations=[GoogleADKInstrumentor()]) + + +async def handle_user_request(user_id: str, message: str): + with propagate_attributes( + customer_identifier=user_id, + thread_identifier="conversation_123", + metadata={"source": "web"}, + ): + return await run_adk_agent(message) +``` + +## Trace tool calls + +ADK tools are captured as child tool spans with serialized inputs, outputs, and +timing. + +```python +from google.adk.agents import Agent + + +def get_weather(city: str) -> str: + """Return a deterministic weather report for a city.""" + return f"{city}: sunny, 72F, light wind" + + +agent = Agent( + name="weather_agent", + model="gemini-2.0-flash", + instruction="Use the get_weather tool when weather is requested.", + tools=[get_weather], +) +``` + +## Use the Respan gateway + +ADK can route model calls through the Respan gateway with its LiteLLM adapter. +This is useful when you want one OpenAI-compatible endpoint for multiple model +providers. + +```bash +export RESPAN_API_KEY="YOUR_RESPAN_API_KEY" +export RESPAN_BASE_URL="https://api.respan.ai/api" +export RESPAN_MODEL="openai/gpt-5-mini" +``` + +```python +import os + +from google.adk.agents import Agent +from google.adk.models.lite_llm import LiteLlm + +agent = Agent( + name="assistant", + model=LiteLlm( + model=os.getenv("RESPAN_MODEL", "openai/gpt-5-mini"), + api_key=os.environ["RESPAN_API_KEY"], + api_base=os.getenv("RESPAN_BASE_URL", "https://api.respan.ai/api"), + ), + instruction="You are a concise assistant.", +) +``` + +## Resources + +- [Respan Google ADK tracing docs](https://www.respan.ai/docs/integrations/google-adk) +- [Respan Google ADK gateway docs](https://www.respan.ai/docs/integrations/gateway/google-adk) +- [Respan Python examples](https://github.com/respanai/respan-example-projects/tree/main/python/tracing/google-adk) +- [Respan platform](https://platform.respan.ai/platform/traces)