ADK 的 Respan 可观测性¶

Supported in ADKPython

Respan 捕获 ADK 运行器、智能体、模型和工具跨度，以便你可以在 Respan 平台中检查完整的智能体工作流。ADK 集成使用 respan-instrumentation-google-adk，它包装了 OpenInference ADK 仪表化器，并在追踪导出之前添加了 Respan 特定的跨度规范化。

概述¶

将 Respan 与 ADK 配合使用：

追踪智能体运行：在一个追踪中捕获运行器调用、智能体执行、模型调用和工具调用。
调试失败：检查嵌套 ADK 工作流中的跨度输入、输出、时间和错误。
跟踪生产元数据：将客户、线程、环境和自定义元数据附加到请求中的所有跨度。
通过 Respan 网关路由模型：当你想要集中式模型路由时，使用 ADK 的 LiteLLM 适配器配合 Respan 的 OpenAI 兼容网关。

前置条件¶

Python 3.11、3.12 或 3.13。
Respan API 密钥。
如果你的 ADK 智能体直接调用 Gemini，则需要 Google API 密钥。

安装¶

安装 Respan SDK、ADK 仪表化器和 ADK：

pip install respan-ai respan-instrumentation-google-adk "google-adk[extensions]"

设置所需的环境变量：

export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"
export GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY"

RESPAN_API_KEY 将追踪发送到 Respan。GOOGLE_API_KEY 由直接的 Gemini 模型调用使用。

追踪 ADK 智能体¶

在运行 ADK 智能体之前初始化 Respan。初始化后启动的所有 ADK 运行都会被自动追踪。

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-flash-latest",
    instruction="你是一个简洁的助手。",
)


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="用一句话打招呼。")],
    )

    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())

打开 Respan 追踪页面查看带有运行器、智能体、模型和工具跨度的 ADK 工作流。

添加请求元数据¶

使用 propagate_attributes() 将每个请求的标识符和元数据添加到上下文中产生的所有跨度。

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)

追踪工具调用¶

ADK 工具被作为带有序列化输入、输出和计时的子工具跨度捕获。

from google.adk.agents import Agent


def get_weather(city: str) -> str:
    """返回城市的确定性天气报告。"""
    return f"{city}: 晴朗，72°F，微风"


agent = Agent(
    name="weather_agent",
    model="gemini-flash-latest",
    instruction="当请求天气时使用 get_weather 工具。",
    tools=[get_weather],
)

使用 Respan 网关¶

ADK 可以通过其 LiteLLM 适配器将模型调用路由到 Respan 网关。当你想要一个 OpenAI 兼容端点用于多个模型提供者时，这很有用。

export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"
export RESPAN_BASE_URL="https://api.respan.ai/api"
export RESPAN_MODEL="openai/gpt-5-mini"

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="你是一个简洁的助手。",
)