Instructor vs PydanticAI

Overview

Instructor and PydanticAI both solve the same core problem: getting reliable, structured outputs from LLMs. However, they take different approaches:

• Instructor is a library that wraps any LLM client to enforce Pydantic schema validation with automatic retry
• PydanticAI is a full agent framework built on Pydantic with type-safe outputs as a core feature

This comparison helps you choose the right tool based on whether you need just structured outputs (Instructor) or a full agent framework (PydanticAI).

Comparison Table

Aspect	Instructor	PydanticAI
Type	Library for structured outputs	Full agent framework
Primary Focus	Enforce Pydantic schemas	Build type-safe agents
Retry Logic	✅ Automatic on validation failure	✅ Built-in
Streaming	✅ Partial updates	✅ Type-safe streaming
Multi-Provider	✅ 10+ providers	✅ Multiple providers
Agent Abstractions	❌ None	✅ Full agent framework
Tool Calling	⚠️ Limited	✅ First-class support
Memory/State	❌ None	✅ Built-in
Learning Curve	Low (Pydantic knowledge)	Moderate (framework concepts)
Best For	Data extraction, classification	Full agent applications

Deep Dive

Instructor: Structured Output Library

Philosophy: Make any LLM client return valid Pydantic models with automatic retry.

Strengths:

• Guaranteed valid structured outputs
• Simple Pydantic-based API
• Automatic retry and correction
• Works with any Pydantic model
• Excellent for data extraction tasks
• Streaming support for partial results

Weaknesses:

• Python only
• Not a full agent framework
• Requires Pydantic knowledge
• Some providers have limited support
• No built-in agent abstractions

Best Use Cases:

• Extracting structured data from unstructured text
• Building classification pipelines
• When you need guaranteed output schemas
• Creating APIs that return structured data
• Data validation and transformation workflows

PydanticAI: Type-Safe Agent Framework

Philosophy: Build reliable AI agents with Pydantic's type system at the core.

Strengths:

• Full agent framework with type safety
• Deep Pydantic integration for validation
• Multi-provider model support
• Built-in testing utilities
• Dependency injection for clean architecture
• Streaming with type safety
• Tool calling with type validation

Weaknesses:

• Python only (no TypeScript yet)
• Newer ecosystem with smaller community
• Requires understanding of Pydantic for full power
• Limited pre-built tools compared to LangChain

Best Use Cases:

• Building production AI agents
• When type safety is critical
• Multi-step agent workflows
• Applications needing tool calling
• Teams already using Pydantic

Feature Comparison

Structured Outputs

Feature	Instructor	PydanticAI
Pydantic models	✅	✅
Nested models	✅	✅
Optional fields	✅	✅
Validation errors	✅ Auto-retry	✅ Auto-retry
Custom validators	✅	✅

Retry & Correction

Feature	Instructor	PydanticAI
Automatic retry	✅	✅
Error feedback to LLM	✅	✅
Configurable retries	✅	✅
Backoff strategy	✅	⚠️ Basic

Streaming

Feature	Instructor	PydanticAI
Partial updates	✅	✅
Type-safe streaming	⚠️ Limited	✅ Full
Real-time validation	⚠️ Limited	✅

Agent Features

Feature	Instructor	PydanticAI
Agent class	❌	✅
Tool calling	⚠️ Limited	✅ First-class
Memory/state	❌	✅ Built-in
Multi-agent	❌	✅ Supported
Dependency injection	❌	✅

Integration Example

Instructor

import instructor
from pydantic import BaseModel
from openai import OpenAI

# Patch the OpenAI client
client = instructor.from_openai(OpenAI())

# Define your schema
class UserExtract(BaseModel):
    name: str
    age: int
    email: str | None
    interests: list[str]

# Extract structured data
user = client.chat.completions.create(
    model="gpt-4o",
    response_model=UserExtract,
    messages=[
        {"role": "user", "content": "John Doe is 30 years old..."}
    ]
)

print(user.name)  # "John Doe"
print(user.age)   # 30

PydanticAI

from pydantic_ai import Agent
from pydantic import BaseModel

class UserExtract(BaseModel):
    name: str
    age: int
    email: str | None
    interests: list[str]

# Create an agent
agent = Agent(
    'openai:gpt-4o',
    result_type=UserExtract,
    retries=3
)

# Run the agent
result = agent.run_sync('John Doe is 30 years old...')
user = result.data

print(user.name)  # "John Doe"
print(user.age)   # 30

When to Choose Instructor

✅ You only need structured outputs from LLMs ✅ You already have an agent framework you like ✅ You want the simplest possible API ✅ You're building data extraction pipelines ✅ You need quick integration with existing code

When to Choose PydanticAI

✅ You're building a full AI agent application ✅ You need tool calling with type safety ✅ You want memory and state management ✅ Type safety is a core requirement ✅ You're starting a new Python project

Can They Work Together?

Yes! You can use Instructor for structured outputs within a PydanticAI agent:

from pydantic_ai import Agent
import instructor

# Use Instructor's patched client within PydanticAI
client = instructor.from_openai(OpenAI())

class MyAgent:
    def extract_data(self, text: str) -> UserExtract:
        return client.chat.completions.create(
            model="gpt-4o",
            response_model=UserExtract,
            messages=[{"role": "user", "content": text}]
        )

Verdict

Scenario	Recommendation
Need just structured outputs	Instructor
Building full agent application	PydanticAI
Already using another framework	Instructor (add-on)
Starting fresh Python project	PydanticAI
Data extraction focus	Instructor
Multi-step agent workflows	PydanticAI
Need tool calling	PydanticAI
Simplest integration	Instructor

Resources

• Instructor Documentation
• PydanticAI Documentation
• Instructor GitHub
• PydanticAI GitHub