Pydantic AI

Setup

Install the Braintrust SDK and Pydantic AI:

pip install braintrust pydantic-ai

Tracing Pydantic AI 2.0 or later requires the Braintrust Python SDK v0.26.0 or later.

Auto-instrumentation

To trace Pydantic AI without modifying each agent call, call init_logger() and auto_instrument() once at startup. auto_instrument() patches Pydantic AI’s agent and model APIs along with every other supported library.

import braintrust
from pydantic_ai import Agent

braintrust.init_logger(project="my-pydantic-project")  # Replace with your project name
braintrust.auto_instrument()

# Use agents as normal - they're automatically traced
agent = Agent("openai:gpt-5-mini", system_prompt="You are a helpful assistant.")
result = await agent.run("What is the capital of France?")

Instrument only Pydantic AI

To patch Pydantic AI without enabling Braintrust’s other integrations, call setup_pydantic_ai() instead. It initializes a logger for you when one isn’t already active.

from braintrust.wrappers.pydantic_ai import setup_pydantic_ai
from pydantic_ai import Agent

# Initialize Braintrust tracing for Pydantic AI
setup_pydantic_ai(project_name="my-pydantic-project")

# Use agents as normal - they're automatically traced
agent = Agent("openai:gpt-5-mini", system_prompt="You are a helpful assistant.")
result = await agent.run("What is the capital of France?")

Tools and streaming

Tools and streaming responses are traced without extra configuration:

import braintrust
from pydantic_ai import Agent, ModelSettings

braintrust.init_logger(project="my-pydantic-project")  # Replace with your project name
braintrust.auto_instrument()

agent = Agent(
    "openai:gpt-5-mini",
    model_settings=ModelSettings(max_tokens=500),
)

@agent.tool_plain
def get_weather(city: str) -> str:
    """Get the current weather for a city."""
    return f"22°C and sunny in {city}"

# Streaming is fully traced, including time-to-first-token
async with agent.run_stream("What's the weather in Paris?") as result:
    async for text in result.stream_text(delta=True):
        print(text, end="", flush=True)

Nest under existing spans

If you already have a Braintrust span context (e.g., from @traced or start_span), Pydantic AI traces nest under it:

import braintrust
from pydantic_ai import Agent

braintrust.init_logger(project="my-pydantic-project")  # Replace with your project name
braintrust.auto_instrument()

agent = Agent("openai:gpt-5-mini")

@braintrust.traced
async def my_workflow(question: str):
    # Agent traces appear as children of this span
    result = await agent.run(question)
    return result.output

OpenTelemetry

To trace Pydantic AI through an existing OpenTelemetry pipeline, attach a BraintrustSpanProcessor and enable Pydantic AI’s built-in instrumentation.

Install packages

Install the Braintrust SDK with the OpenTelemetry extra, alongside Pydantic AI:

pip install "braintrust[otel]" pydantic-ai

Configure tracing

Register the BraintrustSpanProcessor with your tracer provider, then call Agent.instrument_all() to emit Pydantic AI’s instrumentation to Braintrust:

from braintrust.otel import BraintrustSpanProcessor
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from pydantic_ai import Agent

provider = TracerProvider()
trace.set_tracer_provider(provider)
provider.add_span_processor(BraintrustSpanProcessor())

Agent.instrument_all()

What Braintrust traces

Braintrust captures:

Agent run spans (agent_run, agent_run_sync, agent_run_stream, agent_run_stream_sync, agent_to_cli_sync), with the run input, agent metadata, output, and timing.
Direct model-request spans (model_request, model_request_sync), for pydantic_ai.direct API calls.
Model call spans (chat <model>), for the underlying LLM calls made during a run.
Tool call spans, for tools invoked during an agent run.

AI providers

SDKs

Developer tools

Setup

Auto-instrumentation

Tools and streaming

Nest under existing spans

OpenTelemetry

What Braintrust traces

Resources

​Setup

​Auto-instrumentation

​Tools and streaming

​Nest under existing spans

​OpenTelemetry

​What Braintrust traces

​Resources

Setup

Auto-instrumentation

Tools and streaming

Nest under existing spans

OpenTelemetry

What Braintrust traces

Resources