Respan Exporter for Pydantic AI

respan.ai · Documentation · PyPI

Instrument Pydantic AI agents with Respan: traces, spans, and metrics are sent to Respan via OpenTelemetry and standard semantic conventions. Requires respan-tracing (installed automatically).

Install

pip install respan-exporter-pydantic-ai

Environment Variables

Quickstart

import os
from pydantic_ai import Agent
from respan_tracing import RespanTelemetry
from respan_exporter_pydantic_ai.instrument import instrument_pydantic_ai

respan_api_key = os.environ["RESPAN_API_KEY"]
respan_base_url = os.getenv("RESPAN_BASE_URL", "https://api.respan.ai/api")

# Use Respan as the LLM gateway (no separate OpenAI key needed)
os.environ["OPENAI_BASE_URL"] = respan_base_url
os.environ["OPENAI_API_KEY"] = respan_api_key

# 1. Initialize Respan telemetry
telemetry = RespanTelemetry(app_name="my-app", api_key=respan_api_key)

# 2. Instrument Pydantic AI (global: all agents)
instrument_pydantic_ai()

# 3. Use your agent
agent = Agent("openai:gpt-4o")
result = agent.run_sync("What is the capital of France?")
print(result.output)

To instrument a single agent instead of globally:

agent = Agent("openai:gpt-4o")
instrument_pydantic_ai(agent=agent)

API Reference

RespanTelemetry

Initialize once before calling instrument_pydantic_ai():

instrument_pydantic_ai()

Traces appear in the Respan dashboard. Open a trace to see the workflow → task → LLM span tree.

Dev Guide

Token extraction (no OpenAI instrumentation needed)

This package extracts token usage directly from Pydantic AI's own gen_ai.usage.input_tokens / gen_ai.usage.output_tokens span attributes and promotes them to first-class prompt_tokens / completion_tokens metrics.

opentelemetry-instrumentation-openai is NOT required. Pydantic AI emits token counts for all providers (OpenAI, Anthropic, Google, etc.) natively, so a separate OpenAI instrumentor would only create duplicate spans and double-count tokens. If you have it installed and want to block it, pass block_instruments={Instruments.OPENAI} when initializing RespanTelemetry.

Setup

cd python-sdks/respan-exporter-pydantic-ai
poetry install

Tests

# Unit tests (no network)
poetry run pytest tests/test_instrument.py tests/test_extraction_functions.py -v

# All tests
poetry run pytest tests/ -v

# Integration test (real gateway, requires RESPAN_API_KEY)
IS_REAL_GATEWAY_TESTING_ENABLED=1 RESPAN_API_KEY="your-key" \
  poetry run pytest tests/test_real_gateway_integration.py -v -s

Run script (trace tree)

RESPAN_API_KEY="your-key" poetry run python scripts/run_real_gateway_test.py

Further Reading

• Pydantic AI example project — runnable integration examples
• Respan documentation
• Pydantic AI documentation
• respan-tracing on PyPI
• OpenTelemetry Semantic Conventions for LLM spans