Skip to content
Pydantic Docs

Pydantic AI

See what your Pydantic AI agents do: every model call, every tool they invoke, and every retry, as a trace (the full journey of one agent run, made of nested spans, where each span is one unit of work with a name, a start, and a duration) in Logfire.

What you’ll capture

  • Each agent run as a trace, with the model it used and how long it took
  • The full conversation with the model, rendered so you can read it like a transcript
  • Every tool call the agent made, as a child span with its arguments and result
  • Retries, including the failed attempt that triggered each one
  • Token usage for each model call, and any errors raised along the way

Before you start

You’ll need a Logfire project. Open Add data in your project (top navigation) and follow the setup for your language: it signs your machine in with logfire auth (a browser sign-in, no token to copy) and, for production or other languages, creates a write token (the credential your app uses to send data). New to Logfire? Start with Getting Started.

Your agent runs call a model provider (OpenAI, Anthropic, and others) using your own API key, so each run costs money on that provider account.

Installation

Install logfire:

Terminal
pip install logfire

This integration works with your existing Pydantic AI install; there’s no extra to add. If you don’t have it yet, pip install pydantic-ai.

Usage

Add two lines to your app: logfire.configure() to connect to your project, and logfire.instrument_pydantic_ai() to record every agent run.

from __future__ import annotations

from pydantic_ai import Agent, RunContext

import logfire

logfire.configure()
logfire.instrument_pydantic_ai()

roulette_agent = Agent(
    'openai:gpt-5-mini',
    deps_type=int,
    output_type=bool,
    system_prompt=(
        'Use the `roulette_wheel` function to see if the customer has won based on the number they provide.'
    ),
)


@roulette_agent.tool
async def roulette_wheel(ctx: RunContext[int], square: int) -> str:
    """Check if the square is a winner."""
    return 'winner' if square == ctx.deps else 'loser'


# Run the agent
success_number = 18
result = roulette_agent.run_sync('Put my money on square eighteen', deps=success_number)
print(result.output)
#> True

result = roulette_agent.run_sync('I bet five is the winner', deps=success_number)
print(result.output)
#> False

You can use Pydantic AI with a large variety of models; the example just happens to show gpt-5-mini.

Verify it worked

Run your program, then open the Live view. Within a few seconds you’ll see a trace for the agent run. Click it to read the conversation, expand the roulette_wheel tool call, and see the token count and duration.

The example above displays like this in Logfire:

Logfire instrumentation of the agent run — View in Logfire

Advanced

Instrument a single agent

To instrument one agent rather than all of them, pass it to the call:

logfire.instrument_pydantic_ai(roulette_agent)

Troubleshooting

Not seeing data? Check that logfire.configure() ran before instrument_pydantic_ai(), that your write token is set, and that you called the instrument function exactly once.

Reference