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

# Trace PydanticAI with BotGauge

> Trace PydanticAI agents with BotGauge in code or zero-code. Python 3.11+ install line, the 3.10 fallback, and the token-count caveat.

Records PydanticAI agent runs. PydanticAI instruments itself, so the in-code sample turns that on and adds OpenInference's span processor.

| | |
| - | - |
| Extra | `[pydantic-ai]` |
| Verified framework versions | pydantic-ai 1.25.1 and 2.57.0 |
| Instrumentor installed by the extra | `openinference-instrumentation-pydantic-ai 0.1.30` |
| Zero-code run | Traced |

Also verified: pydantic-ai 1.25.1 with instrumentor 0.1.27. The extra no longer installs that older instrumentor. See [supported frameworks](https://www.botgauge.com/docs/integrations/overview.md) for how verification works.

## In code

Call `tracing.init()`, attach the framework instrumentor to the provider it returns, and wrap the work in `tracing.turn()` and `tracing.agent()`.

> [!NOTE]
>
> The install line uses PydanticAI 2.57, which needs Python 3.11 or newer and no other pins.

> **Python 3.10: use PydanticAI 1.25**
>
> On Python 3.10, use the tested PydanticAI 1.25 instead. It needs OpenTelemetry 1.39 and `genai-prices` older than 0.1 to record token counts, because PydanticAI before 2.17 records none with `genai-prices` 0.1.0 or newer, and the trace would then show zero cost. In code, pass `version=3` to `InstrumentationSettings` on PydanticAI 1.x and `version=5` on 2.x.
>
> ```bash terminal theme={null}
> pip install "botgauge[pydantic-ai]" pydantic-ai==1.25.1 \
>   opentelemetry-api==1.39.1 opentelemetry-sdk==1.39.1 \
>   opentelemetry-exporter-otlp-proto-http==1.39.1 genai-prices==0.0.73
> ```

**1. Install**

```bash terminal theme={null}
pip install "botgauge[pydantic-ai]" pydantic-ai==2.57.0
```

**2. Add the code**

```python app.py theme={null}
import os

from botgauge import tracing
from openinference.instrumentation.pydantic_ai import OpenInferenceSpanProcessor
from pydantic_ai import Agent
from pydantic_ai.models.instrumented import InstrumentationSettings
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.openai import OpenAIProvider

provider = tracing.init()
Agent.instrument_all(InstrumentationSettings(tracer_provider=provider, version=5))
provider.add_span_processor(OpenInferenceSpanProcessor())

openai_provider = OpenAIProvider(
    base_url=os.environ["OPENAI_BASE_URL"], api_key=os.environ["OPENAI_API_KEY"]
)
model = OpenAIChatModel(os.environ["OPENAI_MODEL"], provider=openai_provider)
agent = Agent(model, name="assistant")

with tracing.turn(session_id="ses_pydantic_ai"), tracing.agent("pydantic-ai-agent"):
    result = agent.run_sync("In one sentence, what is OpenTelemetry?")
print(result.output)

tracing.shutdown()
```

**3. Run**

```bash terminal theme={null}
python app.py
```

Needs `BOTGAUGE_API_KEY`, `OPENAI_BASE_URL`, `OPENAI_API_KEY`, `OPENAI_MODEL`.

## Zero-code

Leave your app unchanged and start it with `botgauge instrument`. The sample still wraps the work in `tracing.turn()` and `tracing.agent()` so spans carry session and agent ids.

> [!NOTE]
>
> The install line uses PydanticAI 2.57, which needs Python 3.11 or newer and no other pins.

> **Python 3.10: use PydanticAI 1.25**
>
> On Python 3.10, use the tested PydanticAI 1.25 instead. It needs OpenTelemetry 1.39 and `genai-prices` older than 0.1 to record token counts, because PydanticAI before 2.17 records none with `genai-prices` 0.1.0 or newer, and the trace would then show zero cost. `botgauge instrument` picks the right instrumentation version for you.
>
> ```bash terminal theme={null}
> pip install "botgauge[pydantic-ai]" pydantic-ai==1.25.1 \
>   opentelemetry-api==1.39.1 opentelemetry-sdk==1.39.1 \
>   opentelemetry-exporter-otlp-proto-http==1.39.1 genai-prices==0.0.73
> ```

**1. Install**

```bash terminal theme={null}
pip install "botgauge[pydantic-ai]" pydantic-ai==2.57.0
```

**2. Add the code**

```python app.py theme={null}
import os

from botgauge import tracing
from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.openai import OpenAIProvider

openai_provider = OpenAIProvider(
    base_url=os.environ["OPENAI_BASE_URL"], api_key=os.environ["OPENAI_API_KEY"]
)
model = OpenAIChatModel(os.environ["OPENAI_MODEL"], provider=openai_provider)
agent = Agent(model, name="assistant")

with tracing.turn(session_id="ses_pydantic_ai"), tracing.agent("pydantic-ai-agent"):
    result = agent.run_sync("In one sentence, what is OpenTelemetry?")
print(result.output)
```

**3. Run**

```bash terminal theme={null}
botgauge instrument python app.py
```

Needs `BOTGAUGE_API_KEY`, `OPENAI_BASE_URL`, `OPENAI_API_KEY`, `OPENAI_MODEL`.

View PydanticAI spans liveWatch your PydanticAI agent runs with token counts appear in [BotGauge](https://cloud.botgauge.com).

[Try BotGauge →](https://cloud.botgauge.com)

## Related

See [versions not verified](https://www.botgauge.com/docs/integrations/versions-not-verified.md) if you run a different version, [capture and redaction](https://www.botgauge.com/docs/tracing/capture-and-redaction.md) to control exported content, and [troubleshooting](https://www.botgauge.com/docs/tracing/troubleshooting.md) if spans are missing.


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