A Practioner’s Guide to PydanticAI Agents

PydanticAI Agents have emerged as a powerful framework for creating robust, type-safe autonomous systems. These agents build upon the strong foundation of Pydantic’s data validation capabilities and represent a significant advancement in the development, deployment, and management of AI systems capable of complex decision-making. The combination of structured data validation with planning and execution capabilities ensures predictable and reliable behavior when working with LLMs. This article practically explains PydanticAI Agents. 

Table of Contents

1. Understanding PydanticAI
2. Overview of PydanticAI Agent Framework
3. Building Multi-Agent Applications with PydanticAI
4. Implementing a Multi-Agent System using PydanticAI

Understanding PydanticAI

PydanticAI is a Python library that combines Pydantic’s data validation capabilities with AI-powered functionality. It’s designed to structure the working of LLMs, thereby increasing their reliability. It’s an agent framework intended solely for building GenAI applications with ease and production-grade performance. It essentially bridges the gap between the unstructured text outputs of language models and the structured data that applications often require, making it easier to build reliable AI-powered applications. 

With PydanticAI, users can use the Pydantic model to determine the expected LLM output schema and verify that the response generated via LLM is in the required format. It makes sure the generated response is consistent with the expected structure of the schema, types, and constraints. PydanticAI also provides tools that users can use to format prompts for guiding LLMs to generate outputs matching the required schema. 

Frameworks such as LangChain, OpenAI’s API, and other LLM providers integrate seamlessly with PydanticAI providing the ability to implement different LLMs and handle their inherent unpredictability in generated responses. If the model generates responses that don’t match the required schema, PydanticAI can automatically retry with refined prompts or apply correction strategies enabling the LLM to generate valid output according to the user specifications.  

It was created as an extension of the Pydantic validation library, for addressing the need for structured, validated data when interfacing with LLMs. It uses Pydantic’s type annotation system and validation capabilities but extends them with specialized features for AI interactions. The library uses clear schemas definitions that user can use for guiding LLMs. This approach significantly reduces the error handling and post-processing typically required when working with raw LLM outputs. 

Pydantic models are defined with field types, constraints, and descriptions that serve both as validation schemas and as implicit instructions for the LLM for implementing PydanticAI. When integrated into prompt templates, these model definitions help the LLM understand the expected structure. When the generated response from an LLM doesn’t match the expected schema, PydanticAI’s validation system identifies specific violations and can implement different recovery strategies such as prompt reformulation, feedback provision, etc. 

PydanticAI uses retry logic with exponential backoff, content filtering, and model-specific optimization techniques to maximize successful validation rates, thereby making error-handling easy and efficient. 

Overview of PydanticAI Agent Framework

Agents are the primary interface in PydanticAI, used for interfacing with LLMs. They are designed to create autonomous AI applications that can perform difficult and multi-step tasks while maintaining structured data validation. These agents combine the schema validation strength of PydanticAI through planning and execution capabilities. 

At the foundation level, PydanticAI Agents use Pydantic models to define the expected outputs, available actions, tools, and decision-making processes that agents can use. This creates an environment where each step of the agent’s reasoning and action is validated against predefined schemas, thereby, reducing LLM unpredictability. 

The agent architecture follows a loop of observation, thought, and actions. Each observation from the environment is parsed into a validated Pydantic model. The agent then uses an LLM to reason about the observations, with its thoughts captured and validated. Finally, the agent selects and executes actions from a predefined set of tools, with both inputs and outputs validated against corresponding schemas. 

The tool system in PydanticAI agents allows for integrating external capabilities like API calls, database queries, functions, etc. The tools are wrapped in a Pydantic model which defines the input parameters and expected return values, ensuring that even when the agent interacts with external systems, the data flows remain validated and structured. 

Building Multi-Agent Applications with PydanticAI

PydanticAI allows building multi-agent applications using the concepts of agent delegation, programmatic agent hand-off, and graph-based control flow. Agent delegation concept is when an agent delegates work to another agent, then takes back control when the delegate agent finishes the work. Since the agents are stateless and designed to be global, the users don’t need to include the agent itself in agent dependencies. A simple example of agent delegation can be shown using the image below – 

Programmatic agent hand-off is the scenario where an agent executes, then application code calls another agent. The agents in this case don’t need to use same dependencies. A simple example of programmatic agent hand-off is shown in the image below – 

Graph-based control flow is another multi-agent application building scenario which is appropriate for complex cases. It employs a graph-based state machine which controls the execution of multiple agents. 

Implementing a Multi-Agent System using PydanticAI Agents

Let’s use PydanticAI Agents and generate a structured output using pre-defined response schema. 

Step 1: Library Installation – 

!pip install pydantic-ai logfire

Step 2: Library Imports – 

from pydantic import BaseModel, Field

from pydantic_ai import Agent, ModelRetry, RunContext, Tool

from pydantic_ai.models.openai import OpenAIModel

from google.colab import userdata

import os

Step 3: GPT Model Configuration – 

os.environ["OPENAI_API_KEY"] = userdata.get("OPENAI_API_KEY")

model = OpenAIModel(

   'gpt-4o-mini'

)

Step 4: Response Schema Definition – 

class ResponseModel(BaseModel):

   """Automatic Structured response with metadata."""

   leader_name: str

   continent_name: str

   country_name: str

   capital_name: str

   leader_description: str = Field(description="leader description")

Step 5: Agent Definition – 

agent = Agent(

   model=model,

   result_type=ResponseModel,

   system_prompt=(

       "You are an intelligent research agent. "

       "Analyze user request carefully and provide structured responses."

   ),

   result_retries = 3

)

agent2 = Agent(

   model=model,

   system_prompt=(

       "You are an intelligent research agent. "

       "Analyze input json list carefully and provide markdown table"

       "Be concise and don't write anything else except the markdown table"

       "use bold tags for headers"

   ),

)

Step 6: Task Completion and Output Generation – 

import nest_asyncio

nest_asyncio.apply()

data_list = []

response = agent.run_sync("tell me about Narendra Modi")

data_list.append(response.data.model_dump_json(indent=2))

response = agent.run_sync("tell me about Donald Trump")

data_list.append(response.data.model_dump_json(indent=2))

response = agent.run_sync("tell me about Xi Jinping")

data_list.append(response.data.model_dump_json(indent=2))

response_table = agent2.run_sync(str(data_list))

print(response_table.data)

Output: 

We can see the response is structured as per our response schema definition. 

Final Words

PydanticAI Agents provide huge flexibility towards development of reliable, maintainable agent-based solutions. Using strict validation throughout the observation-thought-action loop, these agents bring much needed predictability to systems powered by inherently probabilistic language models. This framework represents a significant step towards the creation, deployment, reduced development overhead, and improved long-term maintainability of autonomous systems. 

References

1. Link to Colab Notebook
2. PydanticAI Documentation
3. PydanticAI GitHub Repo