> ## Documentation Index > Fetch the complete documentation index at: https://arize-ax.mintlify.site/docs/llms.txt > Use this file to discover all available pages before exploring further. # Pydantic AI > Trace Pydantic AI agents with OpenInference and send spans to Arize AX for LLM observability. [Pydantic AI](https://ai.pydantic.dev/) is an agent framework from the Pydantic team that emphasises type-safe agents, Pydantic-validated outputs, and tool use. Arize AX captures every Pydantic AI agent run — model calls, tool invocations, and structured-output validation — via the [`openinference-instrumentation-pydantic-ai`](https://github.com/Arize-ai/openinference/tree/main/python/instrumentation/openinference-instrumentation-pydantic-ai) package. Pydantic AI emits OpenTelemetry spans natively once instrumentation is enabled with `Agent.instrument_all()`; the OpenInference span processor reshapes them into the OpenInference format that Arize AX understands. ## Prerequisites * Python 3.10+ * An Arize AX account ([sign up](https://arize.com/sign-up/)) * An `OPENAI_API_KEY` from the [OpenAI Platform](https://platform.openai.com/api-keys) ## Launch Arize AX 1. Sign in to your [Arize AX account](https://app.arize.com/). 2. From **Space Settings**, copy your **Space ID** and **API Key**. You will set them as `ARIZE_SPACE_ID` and `ARIZE_API_KEY` below. ## Install ```bash theme={null} pip install arize-otel \ openinference-instrumentation-pydantic-ai \ pydantic-ai openai ``` ## Configure credentials ```bash theme={null} export ARIZE_SPACE_ID="" export ARIZE_API_KEY="" export ARIZE_PROJECT_NAME="pydantic-ai-tracing-example" export OPENAI_API_KEY="" ``` ## Setup tracing ```python theme={null} # instrumentation.py import os from arize.otel import BatchSpanProcessor, GRPCSpanExporter, register from openinference.instrumentation.pydantic_ai import OpenInferenceSpanProcessor space_id = os.environ["ARIZE_SPACE_ID"] api_key = os.environ["ARIZE_API_KEY"] tracer_provider = register( space_id=space_id, api_key=api_key, project_name=os.environ["ARIZE_PROJECT_NAME"], ) # add_span_processor replaces register()'s default OTLP processor, so we # add it back explicitly. The two-call pattern gives us: # OpenInferenceSpanProcessor (reshapes spans) → # GRPCSpanExporter (sends to Arize). tracer_provider.add_span_processor(OpenInferenceSpanProcessor()) tracer_provider.add_span_processor( BatchSpanProcessor(GRPCSpanExporter(space_id=space_id, api_key=api_key)) ) print("Arize AX tracing initialized for Pydantic AI.") ``` ## Run Pydantic AI ```python theme={null} # example.py # Importing instrumentation first ensures tracing is set up # before `pydantic_ai` is imported. from instrumentation import tracer_provider from pydantic import BaseModel from pydantic_ai import Agent from pydantic_ai.models.openai import OpenAIChatModel class CityFact(BaseModel): city: str fact: str # Enable instrumentation for every agent. In pydantic-ai 2.x this replaces # the old `Agent(..., instrument=True)` constructor argument. Agent.instrument_all() # OpenAIChatModel reads OPENAI_API_KEY from the environment. model = OpenAIChatModel("gpt-5.5") agent = Agent(model, output_type=CityFact) result = agent.run_sync("Give me one short fact about Paris.") print(f"city={result.output.city} fact={result.output.fact}") ``` ### Expected output ```text wrap theme={null} Arize AX tracing initialized for Pydantic AI. city=Paris fact=The Eiffel Tower was completed in 1889 for the World's Fair. ``` ## Verify in Arize AX 1. Open your Arize AX space and select project **`pydantic-ai-tracing-example`**. 2. You should see a new trace within \~30 seconds containing an `agent run` parent span wrapping a nested OpenAI chat-completion LLM span, with the prompt, response, and the validated `CityFact` output attached. 3. If no traces appear, see [Troubleshooting](#troubleshooting). ### Check from the skill, CLI, or SDK Confirm spans are actually reaching your Arize AX project. Use whichever fits your workflow — the skill and CLI work for any framework; the SDK check is shown for each language. Install the [Arize Skills](https://github.com/Arize-ai/arize-skills) plugin and let your coding agent check for you: ```bash theme={null} npx skills add Arize-ai/arize-skills ``` Then prompt your agent: > Use the `arize-trace` skill to export and analyze recent traces from my project. Confirm spans are arriving, and summarize any errors or latency issues. Export recent spans for your project — any rows mean traces are landing: ```bash theme={null} ax spans export "$ARIZE_PROJECT_NAME" --space "$ARIZE_SPACE_ID" \ --limit 5 --stdout | jq 'length' ``` A non-zero count confirms spans reached Arize AX. Run `ax auth login` first if you have not authenticated. See the [`ax spans` reference](/docs/api-clients/cli/spans). Query the project's spans and check that at least one came back. ```python Python theme={null} import os from arize import ArizeClient client = ArizeClient(api_key=os.environ["ARIZE_API_KEY"]) resp = client.spans.list( project=os.environ["ARIZE_PROJECT_NAME"], space=os.environ["ARIZE_SPACE_ID"], limit=5, ) count = len(resp.spans) print( f"{count} span(s) found" if count else "No spans yet — recheck setup" ) ``` ```typescript TypeScript theme={null} // Reads ARIZE_API_KEY from the environment. import { listSpans } from "@arizeai/ax-client"; const { data: spans } = await listSpans({ project: process.env.ARIZE_PROJECT_NAME!, space: process.env.ARIZE_SPACE_ID!, limit: 5, }); const count = spans.length; console.log( count ? `${count} span(s) found` : "No spans yet — recheck setup", ); ``` ```go Go theme={null} client, err := arize.NewClient( arize.Config{APIKey: os.Getenv("ARIZE_API_KEY")}, ) if err != nil { log.Fatal(err) } resp, err := client.Spans.List(ctx, spans.ListRequest{ Project: os.Getenv("ARIZE_PROJECT_NAME"), Space: os.Getenv("ARIZE_SPACE_ID"), Limit: 5, }) if err != nil { log.Fatal(err) } fmt.Printf("%d span(s) found\n", len(resp.Spans)) ``` SDK span references: [Python](/docs/api-clients/python/version-8/client-resources/spans) · [TypeScript](/docs/api-clients/typescript/version-1/client-resources/spans) · [Go](/docs/api-clients/go/version-2/client-resources/spans). ## Troubleshooting * **No traces in Arize AX.** Confirm `ARIZE_SPACE_ID` and `ARIZE_API_KEY` are set in the same shell that runs `example.py`. Enable OpenTelemetry debug logs with `export OTEL_LOG_LEVEL=debug` and re-run. * **Agent ran but no spans appear.** Pydantic AI only emits OTel spans once instrumentation is enabled. Call `Agent.instrument_all()` before running any agent. (In pydantic-ai 1.x this was the per-agent `Agent(..., instrument=True)` argument, which was removed in 2.0 — `Agent.instrument_all()` is the replacement.) * **`401` from OpenAI.** Verify `OPENAI_API_KEY` is set and has access to `gpt-5.5`. Swap for a model your key can call. * **Output validation errors.** When the model returns content that doesn't satisfy the `output_type` Pydantic model, Pydantic AI raises a validation error and may retry. Both the failed and successful attempts surface as separate spans. ## Resources