How to beginner · 3 min read

Pydantic AI model retry explained

Q: Pydantic AI model retry explained

In pydantic_ai, retry logic for model calls can be implemented by wrapping the Agent.run_sync() or Agent.run() method in a retry loop or using external retry libraries. pydantic_ai itself does not provide built-in retry parameters, so you handle retries manually to ensure robustness against transient API failures.

Quick answer

In pydantic_ai, retry logic for model calls can be implemented by wrapping the Agent.run_sync() or Agent.run() method in a retry loop or using external retry libraries. pydantic_ai itself does not provide built-in retry parameters, so you handle retries manually to ensure robustness against transient API failures.

PREREQUISITES

Python 3.8+
OpenAI API key (free tier works)
pip install pydantic-ai openai>=1.0

Setup

Install the pydantic-ai package along with openai for API access. Set your OpenAI API key as an environment variable.

Install packages: pip install pydantic-ai openai
Set environment variable: export OPENAI_API_KEY='your_api_key' (Linux/macOS) or setx OPENAI_API_KEY "your_api_key" (Windows)

bash

pip install pydantic-ai openai

output

Collecting pydantic-ai
Collecting openai
Successfully installed openai-1.x.x pydantic-ai-x.x.x

Step by step

This example shows how to implement retry logic manually around a pydantic_ai.Agent call to handle transient API errors gracefully.

python

import os
import time
from pydantic_ai import Agent
from pydantic import BaseModel
from openai import OpenAI

class Result(BaseModel):
    answer: str

# Initialize the agent with OpenAI GPT-4o-mini model
agent = Agent(
    "openai:gpt-4o-mini",
    system_prompt="You are a helpful assistant.",
    result_type=Result,
    api_key=os.environ["OPENAI_API_KEY"]
)

def run_with_retry(prompt: str, retries: int = 3, delay: float = 2.0) -> Result:
    for attempt in range(1, retries + 1):
        try:
            result = agent.run_sync(prompt)
            return result
        except Exception as e:
            print(f"Attempt {attempt} failed: {e}")
            if attempt == retries:
                raise
            time.sleep(delay)

if __name__ == "__main__":
    prompt = "Explain the retry mechanism in Pydantic AI models."
    result = run_with_retry(prompt)
    print("Answer:", result.data.answer)

output

Answer: In pydantic_ai, retry logic is implemented externally by wrapping calls to the agent in retry loops. The library itself does not provide built-in retry parameters, so you handle retries manually to ensure robustness against transient API failures.

Common variations

Async calls: Use await agent.run() inside an async retry loop.
Different models: Change the model string in Agent(), e.g., "openai:gpt-4o".
External retry libraries: Use tenacity or similar for more advanced retry policies.

python

import asyncio
from pydantic_ai import Agent
import os

agent = Agent(
    "openai:gpt-4o-mini",
    system_prompt="You are a helpful assistant.",
    api_key=os.environ["OPENAI_API_KEY"]
)

async def run_with_retry_async(prompt: str, retries: int = 3, delay: float = 2.0):
    for attempt in range(1, retries + 1):
        try:
            result = await agent.run(prompt)
            return result
        except Exception as e:
            print(f"Attempt {attempt} failed: {e}")
            if attempt == retries:
                raise
            await asyncio.sleep(delay)

async def main():
    prompt = "Explain retry logic in pydantic_ai asynchronously."
    result = await run_with_retry_async(prompt)
    print("Answer:", result.data.answer)

if __name__ == "__main__":
    asyncio.run(main())

output

Answer: To implement retry logic asynchronously with pydantic_ai, wrap the async agent.run() call in a retry loop with exception handling and delays.

Troubleshooting

If you see openai.error.RateLimitError, increase retry delay or reduce request frequency.
For TimeoutError, verify network connectivity and consider longer timeouts.
Unhandled exceptions should be logged and may require API key or environment variable checks.

✅

Key Takeaways

Pydantic AI does not have built-in retry; implement retries by wrapping Agent.run_sync() or Agent.run() calls.
Use manual loops or libraries like tenacity for robust retry policies with delays and max attempts.
Handle common API errors like rate limits and timeouts by catching exceptions and retrying accordingly.

Verified 2026-04 · openai:gpt-4o-mini, openai:gpt-4o

Verify ↗