OpenInference PydanticAI Instrumentation

Common errors

• ModuleNotFoundError: No module named 'pydantic_ai'

  cause The `pydantic-ai` library, which this instrumentation targets, is not installed in your environment.
  fix Install `pydantic-ai` using `pip install pydantic-ai`.

• ModuleNotFoundError: No module named 'openinference.instrumentation.pydantic_ai'

  cause The `openinference-instrumentation-pydantic-ai` library itself is not installed.
  fix Install the instrumentation package using `pip install openinference-instrumentation-pydantic-ai`.

• TypeError: 'ABCMeta' object is not subscriptable

  cause This error can occur if you have a version conflict between `pydantic` and `pydantic-ai`, or if `pydantic-ai` is installed with an unsupported `pydantic` version. `pydantic-ai` often has strict Pydantic version requirements.
  fix Check the `pydantic-ai` package's dependencies for its compatible `pydantic` versions and ensure your environment matches. You might need to reinstall `pydantic-ai` or `pydantic` with specific versions, e.g., `pip install 'pydantic<2.0.0'` if `pydantic-ai` is not Pydantic V2 compatible.

• No traces appear in the console or exporter logs.

  cause OpenTelemetry is either not correctly configured, or the `instrument()` method was called too late. The `TracerProvider` and `SpanProcessor` must be set up before `PydanticAIInstrumentor().instrument()` and before any `pydantic-ai` calls are made.
  fix Verify that `trace.set_tracer_provider()` is called with a configured `TracerProvider` and `SpanProcessor` early in your application's startup. Ensure `PydanticAIInstrumentor().instrument()` is called directly after OpenTelemetry setup.

Warnings

• gotcha OpenTelemetry must be configured (TracerProvider, SpanProcessor, Exporter) before `PydanticAIInstrumentor().instrument()` is called to ensure traces are captured and exported correctly. Failure to do so will result in no telemetry data being emitted.
  Fix: Initialize `TracerProvider`, `SpanProcessor`, and an `Exporter` (e.g., `OTLPSpanExporter` or `ConsoleSpanExporter`) and set it as the global tracer provider via `trace.set_tracer_provider()` early in your application's lifecycle, before any `pydantic-ai` calls.
• breaking The `pydantic-ai` library itself is in early development and can have breaking changes, as indicated by its minor version increments. `openinference-instrumentation-pydantic-ai` explicitly pins `pydantic-ai` to a narrow version range (`>=0.0.17,<0.0.21`). Upgrading `pydantic-ai` outside this range without upgrading the instrumentation package may lead to unexpected behavior or `AttributeError`.
  Fix: Always check the `install_requires` or `project.dependencies` in the `pyproject.toml` or `setup.py` of `openinference-instrumentation-pydantic-ai` for the supported `pydantic-ai` version range. Ensure your `pydantic-ai` installation adheres to this range. Upgrade both instrumentation and `pydantic-ai` together if newer versions are available.
• gotcha Instrumentation might not capture all details if the underlying `pydantic-ai` model uses custom or unsupported LLM providers or complex callbacks that are not directly patched by the instrumentor. The instrumentation primarily targets the core `pydantic-ai` generation methods.
  Fix: Review the OpenInference documentation and source code for the exact methods being patched. For custom scenarios, consider adding manual OpenTelemetry spans around your `pydantic-ai` calls or contributing to the OpenInference project to extend coverage.

Install

• pip install openinference-instrumentation-pydantic-ai Install package
• pip install pydantic-ai openai opentelemetry-sdk opentelemetry-exporter-otlp Install required dependencies for quickstart

Imports

• PydanticAIInstrumentor

  from openinference.instrumentation.pydantic_ai import PydanticAIInstrumentor

Quickstart

This quickstart demonstrates how to instrument `pydantic-ai` calls using `OpenInferencePydanticAIInstrumentor`. It sets up a console exporter for OpenTelemetry, instruments `pydantic-ai`, and then uses a simple `AIModel` to generate a recipe. Ensure `OPENAI_API_KEY` is set in your environment or replace the placeholder. You'll need `pydantic-ai`, `openai`, `opentelemetry-sdk`, and `opentelemetry-exporter-otlp` installed for this to run.

import os
from opentelemetry import trace
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import SimpleSpanProcessor, ConsoleSpanExporter
from openinference.instrumentation.pydantic_ai import PydanticAIInstrumentor

# Configure OpenTelemetry to print traces to the console
resource = Resource.create({"service.name": "my-pydantic-ai-app"})
tracer_provider = TracerProvider(resource=resource)
span_processor = SimpleSpanProcessor(ConsoleSpanExporter())
tracer_provider.add_span_processor(span_processor)
trace.set_tracer_provider(tracer_provider)

# Instrument pydantic-ai
PydanticAIInstrumentor().instrument()

# Ensure an OpenAI API key is available for pydantic-ai to function
os.environ["OPENAI_API_KEY"] = os.environ.get("OPENAI_API_KEY", "sk-YOUR_OPENAI_KEY_HERE")

# Use pydantic-ai
from pydantic import BaseModel
from pydantic_ai import AIModel

class Recipe(AIModel):
    ingredients: list[str]
    instructions: list[str]
    prep_time_minutes: int

def main():
    print("\n--- Generating a recipe with PydanticAI ---\n")
    with trace.get_tracer(__name__).start_as_current_span("generate_recipe"):
        try:
            recipe = Recipe.generate("A simple pasta dish for two.")
            print(f"Ingredients: {recipe.ingredients}")
            print(f"Instructions: {recipe.instructions}")
            print(f"Prep time: {recipe.prep_time_minutes} minutes\n")
        except Exception as e:
            print(f"Error generating recipe: {e}")
            print("Please ensure OPENAI_API_KEY is set and valid, and required dependencies are installed.")

if __name__ == "__main__":
    main()