Instructor vs Pydantic AI: What’s the Difference

Instructor and Pydantic AI both promise structured, typed LLM output using Pydantic — here’s what actually separates a narrow tool from a full agent framework

Both Instructor and Pydantic AI use Pydantic to get typed, validated data out of an LLM instead of parsing free-text responses — which is exactly why they get confused with each other. What they actually are is quite different.

Instructor: one job, done narrowly

Instructor wraps a single LLM call. You define a Pydantic model describing the shape of data you want, and Instructor handles prompting the model to produce it, validating the response, and retrying on failure. That’s the entire scope — it doesn’t manage multi-step agent logic, tool use, or application state. It’s a building block, meant to be dropped into a pipeline built with something else.

import instructor
from pydantic import BaseModel

class User(BaseModel):
    name: str
    age: int

client = instructor.from_openai(OpenAI())
user = client.chat.completions.create(
    model="gpt-4",
    response_model=User,
    messages=[{"role": "user", "content": "Extract: John is 30 years old"}],
)

Pydantic AI: a full agent framework

Pydantic AI is built by the same team, but solves a broader problem — building an actual AI agent, with tool use, dependency injection for testing without hitting a real model, and multi-step logic, not just one validated call. Structured output is part of what it does, not the whole point of it; it’s positioned as a type-safe alternative to broader agent frameworks like LangChain.

The actual decision

If the problem is “I need this one LLM call to return data matching a schema,” reach for Instructor — it’s smaller, narrower, and adds less to a codebase that doesn’t need a full agent framework. If the problem is “I’m building an agent that needs to reason, call tools, and manage state,” Pydantic AI is a real framework for that job, with structured output as one of its features rather than needing a separate library bolted on.

They’re rarely used together, since Pydantic AI already covers what Instructor does — a project using Instructor is more commonly pairing it with a framework that doesn’t have built-in structured-output handling, like LangChain or a lower-level SDK.