PydanticAI

1. Concept Overview & Systemic Problem

The first wave of libraries for working with language models was created during the rapid prototyping era: they relied on nested dynamic classes, untyped dictionaries, invisible prompts, and complex inheritance. In production backends, this created catastrophic difficulties:

1. Lack of Autocompletion and Refactoring: IDEs do not understand which fields an agent returns, and renaming a single property breaks the code at runtime without warnings.
2. Testing Challenges: It is impossible to isolate agent logic from external services or substitute a database with a test mock due to the absence of proper Dependency Injection.
3. Unreliable Structure Error Handling: Models often skip required fields or confuse types (e.g., a string instead of a number), leading to API crashes.

PydanticAI by Samuel Colvin (the author of Pydantic) redirects agent development towards classical, clean software engineering: it is a type-safe, minimalist, and fast framework built on the Pydantic v2 standard.

2. Architectural Taxonomy & Mental Model

The architecture of PydanticAI is based on four conceptual pillars:

• 1. Parameterized Agent (Agent[Deps, ResultType]): The agent is explicitly typed with two parameters: the type of contextual dependencies (Deps) it needs to operate, and the type of the final result (ResultType). If the result is a Pydantic model, the agent guarantees a validated instance of the class is returned.
• 2. Execution Context and DI (RunContext[Deps]): The Dependency Injection mechanism. Each tool and dynamic prompt accesses ctx.deps, where active database connections, configuration, or user rights information are stored.
• 3. Typed Tools (@agent.tool): Python functions whose arguments are automatically translated into JSON Schema for LLM. Argument descriptions are derived from Type Hints and docstrings.
• 4. Dynamic System Prompts (@agent.system_prompt): Asynchronous functions that generate the system instruction 'on the fly' based on the provided dependencies (e.g., substituting the current user balance or time zone).

3. Technical Pipeline & Internal Mechanics

The lifecycle of a request execution in PydanticAI:

1. Instantiation & Context Binding: When calling agent.run(prompt, deps=my_deps), the framework initializes RunContext and resolves all functions marked with the @agent.system_prompt decorator.
2. Schema Generation & Model Inference: The types of tool arguments and the final ResultType are converted into strict JSON schemas via the Pydantic Core engine (written in Rust, ensuring microsecond speed).
3. Tool Invocation with Self-Correction: When the model returns a tool call, the input arguments are validated through Pydantic's validator. If validation fails (e.g., a negative number is passed where PositiveInt is expected), PydanticAI does not throw an exception but automatically sends a message to the model: "Validation error in field X: expected value > 0. Please try again."
4. Structured Output Serialization & Streaming: The final response is deserialized into the target Python object. The run_stream() method is supported, allowing partially constructed fields of the object to be streamed to the client in real-time.

4. Production Engineering Scenarios

01. Native Agents within FastAPI

Shared model usage: the same schema InvoiceExtractionResponse is used as the output schema for PydanticAI, as the response_model in the FastAPI endpoint, and for automatic TypeScript client type generation via OpenAPI.

02. Safe Handling of Database Transactions

A transactional session AsyncSession from SQLAlchemy is injected into the tools via RunContext. The agent can perform checks and write data. If an error occurs at the final stage, the external context manager rolls back the transaction, preventing the saving of half-formed data.

03. Streaming Structured Interfaces (Generative UI)

The agent generates a dynamic dashboard. With PydanticAI's streaming validation support, the frontend can render graphs and cards even before the model has finished constructing the complete JSON document.

5. Pitfalls, Common Mistakes & Security

• Lack of Field Descriptions (Field(description=...)): The model forms calls based solely on field names and descriptions. If a field is ambiguously named (e.g., status: int), and the description is missing, the model will frequently hallucinate incorrect values.
• Exhaustion of Error Correction Attempts (Max Retries Exceeded): If the schema is too convoluted, the model may exhaust the limit of retries=3 while trying to fit the response to the validator, leading to request failure. Simplify schemas or decompose them into subtasks.
• Resource Lifecycle Leakage in Deps: Ensure that the objects you pass in deps (connection pools, HTTP clients) are properly closed after the agent's work is completed (via async with).