Pydantic AI | Respan Docs

Overview

respan-instrumentation-pydantic-ai enables Pydantic AI’s native OpenTelemetry emission and maps Pydantic AI v2 GenAI attributes into Respan conventions.

The plugin registers a local span processor and calls Pydantic AI’s Agent.instrument_all(...) by default, so model requests, agent runs, and tools are normalized before export.

$ pip install respan-instrumentation-pydantic-ai

Version: 0.1.0 | Python: >=3.11, <3.14

Dependencies

Package	Version
`respan-tracing`	^2.16.1
`respan-sdk`	>=2.5.0
`pydantic-ai`	>=0.2.0

Quick start

1 import os
2 
3 from pydantic_ai import Agent
4 from respan import Respan
5 from respan_instrumentation_pydantic_ai import PydanticAIInstrumentor
6 
7 respan_api_key = os.environ["RESPAN_API_KEY"]
8 respan_base_url = os.getenv("RESPAN_BASE_URL", "https://api.respan.ai/api").rstrip("/")
9 os.environ["OPENAI_BASE_URL"] = os.getenv("RESPAN_GATEWAY_BASE_URL", respan_base_url).rstrip("/")
10 os.environ["OPENAI_API_KEY"] = os.getenv("RESPAN_GATEWAY_API_KEY", respan_api_key)
11 
12 respan = Respan(
13     api_key=respan_api_key,
14     base_url=respan_base_url,
15     instrumentations=[PydanticAIInstrumentor()],
16 )
17 
18 agent = Agent(
19     model="openai:gpt-4o",
20     system_prompt="You are a helpful assistant.",
21 )
22 
23 result = agent.run_sync("Write a one-line haiku about tracing.")
24 print(result.output)
25 respan.flush()

Public API

PydanticAIInstrumentor

1 from respan_instrumentation_pydantic_ai import PydanticAIInstrumentor

Parameter	Type	Default	Description
`agent`	`Agent \| None`	`None`	Instrument a single Pydantic AI agent. If omitted, all agents are instrumented globally.
`include_content`	`bool`	`True`	Include message content in telemetry.
`include_binary_content`	`bool`	`True`	Include binary content in telemetry.
`version`	`int`	`4`	Pydantic AI `InstrumentationSettings` version used for emitted GenAI semantic conventions.

Attribute/Method	Type	Description
`name`	`str`	`"pydantic-ai"` — unique plugin identifier.
`activate()`	`() -> None`	Registers the Respan normalizing span processor and enables Pydantic AI instrumentation globally or on the provided agent.
`deactivate()`	`() -> None`	Restores previous Pydantic AI instrumentation settings and removes the normalizing span processor.

Captured data

The plugin captures agent spans, chat/model request spans, tool spans, model names, token usage, tool definitions, tool calls, response formats, and prompt/response content when content capture is enabled.

Structured message parts and tool payloads are serialized into JSON-safe string attributes before export so Pydantic AI v2 payloads render correctly in Respan.

Gateway

For a Respan-key-only runtime setup, see Pydantic AI gateway setup.