Pydantic AI

Pydantic AI is a Python agent framework for building typed LLM applications with tools, dependency injection, structured outputs, and validation. It can use the OpenAI Responses API through OpenAIResponsesModel and OpenAIProvider.

Use this setup when a Pydantic AI application should keep its agent and validation workflow while routing model requests through AISIX.

This guide uses Pydantic AI with the OpenAI Responses model. You will configure OpenAIProvider with an AISIX proxy URL, caller API key, and model alias.

Prerequisites

Before starting, prepare the following:

• A Python environment supported by Pydantic AI.
• A running AISIX gateway with the proxy listener available.
• An AISIX caller API key.
• A model alias the caller API key can access through the Responses API.

Configure Pydantic AI

Install Pydantic AI if the application does not already include it:

pip install pydantic-ai

Set the values that the Pydantic AI application will use:

# Replace with your values
export AISIX_BASE_URL="http://127.0.0.1:3000/v1"
export AISIX_API_KEY="YOUR_CALLER_API_KEY"
export AISIX_MODEL="gpt-4o-prod"

Create an OpenAI Responses model with the AISIX values:

import os

from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIResponsesModel
from pydantic_ai.providers.openai import OpenAIProvider

model = OpenAIResponsesModel(
  os.environ["AISIX_MODEL"],
  provider=OpenAIProvider(
    base_url=os.environ["AISIX_BASE_URL"],
    api_key=os.environ["AISIX_API_KEY"],
  ),
)

agent = Agent(model)
response = agent.run_sync("Write one sentence about typed AI applications.")

print(response.output)

The model value is the AISIX model alias, not the upstream provider model ID. AISIX governs the model request path, while Pydantic AI still owns agent execution, tool calls, dependency injection, structured outputs, and validation.

Pydantic AI also provides OpenAIChatModel for Chat Completions. Use that model when a workflow needs broad OpenAI-compatible chat support.

Verify the Integration

Run the script from the shell where the AISIX environment variables are set.

When the request succeeds, verify the following results:

• The script prints an agent response.
• AISIX records a successful POST /v1/responses request for the selected model alias.

If you use AISIX Cloud or an on-premises managed control plane, verify the request in the managed gateway logs. For self-hosted gateways, use your configured logs, metrics, or upstream provider logs.

If the request fails, first confirm that the caller API key can access the selected model alias and that base_url points to the AISIX proxy API root with /v1.

Pydantic AI supports multiple OpenAI model surfaces. Use OpenAIResponsesModel for Responses workflows and OpenAIChatModel for broad OpenAI-compatible Chat Completions support through AISIX. Validate structured outputs, tool definitions, and retries with the exact alias before relying on gateway policy or telemetry for that workflow.

Next Steps

• Responses API: review gateway-facing Responses behavior.
• OpenAI-Compatible API: use Chat Completions when a workflow needs broad OpenAI-compatible support.
• Tool Calling: confirm tool-call behavior before enabling Pydantic AI tools.
• Budgets: account for retries or validation loops in spend controls.