> ## Documentation Index
> Fetch the complete documentation index at: https://traceroot.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Pydantic AI

> Auto-instrument Pydantic AI agent runs, LLM calls, and tool invocations

Automatically capture agent runs, LLM calls, and tool invocations within the [Pydantic AI](https://ai.pydantic.dev) framework via its native OpenTelemetry instrumentation.

## Install

> [tab] Python
>
> ```bash theme={null}
> pip install traceroot pydantic-ai
> ```

## Set up

> [tab] Python
>
> ```python theme={null}
> import traceroot
> from traceroot import Integration
>
> traceroot.initialize(integrations=[Integration.PYDANTIC_AI])
> ```

## Usage

Once initialized, all Pydantic AI agent runs and tool invocations are captured automatically:

```python theme={null}
import traceroot
from traceroot import Integration
from pydantic_ai import Agent

traceroot.initialize(integrations=[Integration.PYDANTIC_AI])

agent = Agent(
    "openai:gpt-4o-mini",
    system_prompt="You are a helpful assistant.",
)

result = agent.run_sync("What is the capital of France?")
print(result.output)

traceroot.flush()
```

## Verify

Run your code and confirm the trace arrives:

1. **In the traceroot UI**: Navigate to **Tracing > Traces** in [traceroot Cloud](https://app.traceroot.ai). You should see a trace with root span `invoke_agent agent`, named after the agent — Pydantic AI infers `agent` from the variable name unless you pass `Agent(name=...)`.
2. **Via the CLI**: Run `traceroot traces list` to inspect your recent traces from the terminal.

## What gets captured

| Attribute | Description |
| - | - |
| Agent runs | Each `agent.run()` / `agent.run_sync()` / `agent.run_stream()` invocation |
| Tool calls | Each tool invocation with input arguments and results |
| LLM calls | Raw completion requests with input messages, output messages, and model name |
| Tokens & Cost | Input and output token counts; cost when the model ID matches traceroot's pricing table |
| Cache tokens | Cache read and write token counts when reported by the provider |
| Latency | Duration per agent run and per span |

## Limitations

None known.

## Run the example

Clone the repo and run a complete agent end-to-end.

> [card] [Python](https://github.com/traceroot-ai/traceroot/tree/main/examples/python/pydantic-ai-tool-agent)
>
> Run the Python example

## Next steps

> [card] [Python SDK Reference](https://traceroot.ai/docs/tracing/python-sdk.md)
>
> Explore the full Python SDK reference and instrumentation options.

> [card] [Cost Tracking](https://traceroot.ai/docs/tracing/cost-tracking.md)
>
> Learn how traceroot calculates token costs and tracks model spend.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.