Building Intelligent Agents with PydanticAI

A deep dive into how PydanticAI helps create powerful, data-aware AI agents by leveraging Pydantic for data validation and modeling.

Posted on: 2025-07-26 by AI Assistant

Hello everyone! Today, we’re diving into a fascinating topic in the world of AI: building agents with PydanticAI.

PydanticAI is a powerful tool that enables us to create agents capable of efficiently managing data and interacting with users. By leveraging Pydantic, a library renowned for its data validation and modeling capabilities, our agents become smarter and more organized.

Let’s explore the steps to build an agent with PydanticAI with some easy-to-understand examples!

How to Build an Agent with PydanticAI

The core principle of building an agent with PydanticAI is to define a set of “Tools” that the agent can use and then define an “Agent” that selects the appropriate tool based on the conversation context.

1. Setting Up Tools

A tool is a function or a set of instructions that an agent can execute to perform a specific task, such as searching for information, performing calculations, or calling an external API.

The key is to use Pydantic to define the Input Schema and Output Schema for each tool.

• Input Schema: Defines what data the tool needs and its required format (e.g., must be a number, a string, or have a specific range).
• Output Schema: Defines what data the tool will return and its format.

Example: Let’s create an agent that can add two numbers.

from pydantic import BaseModel

# Input Schema for the addition function
class AddToolInput(BaseModel):
    """Defines the input schema for the add_numbers tool."""
    num1: int  # The first integer
    num2: int  # The second integer

# The addition function (our tool)
def add_numbers(num1: int, num2: int) -> int:
    """Takes two numbers and returns their sum."""
    return num1 + num2

# In a real PydanticAI application, you would wrap this function
# using a decorator or a class to make it a usable tool.
# This example is more conceptual to illustrate the idea.

from pydanticai.tool import tool

@tool(input_schema=AddToolInput)
def add_numbers_tool(num1: int, num2: int) -> int:
     return add_numbers(num1, num2)

Explanation:

• AddToolInput is a Pydantic model that specifies that the add_numbers function requires two inputs, num1 and num2, both of which must be integers.
• add_numbers is the actual function that performs the addition.

2. Creating the Agent

The agent is responsible for understanding the user’s prompt and selecting the most appropriate tool to respond.

How it works:

1. The agent analyzes the user’s query.
2. It determines which of its available tools can answer the query.
3. It checks the Input Schema of the selected tool.
4. It tries to extract the necessary information from the user’s query and formats it to match the Input Schema.
5. It executes the tool.
6. It receives the result from the tool and presents it to the user.

Conceptual Example:

# Assuming we have a PydanticAI framework to help create an Agent
from pydanticai import Agent # Fictional import for clarity
from pydanticai.tool import Tool # Fictional import for clarity

# Define all the tools the Agent can use
# (Assuming add_numbers_tool is the wrapped function from before)
tools = [
    Tool(name="AddTool", func=add_numbers_tool, input_schema=AddToolInput)
]

# Create the Agent
my_agent = Agent(tools=tools)

# Run the agent with a prompt
response = my_agent.run("Please add 5 and 10")
print(response) # Expected output: 15

Explanation:

When my_agent.run("Please add 5 and 10") is called, the agent:

1. Analyzes the prompt and understands it requires addition.
2. Selects the add_numbers_tool.
3. Extracts 5 and 10 from the prompt.
4. Validates that 5 and 10 match the AddToolInput schema (they are integers).
5. Calls add_numbers_tool(num1=5, num2=10).
6. Receives the result 15 and returns it.

Advantages of Using PydanticAI

• Clear Input/Output: Pydantic allows you to explicitly define the data your tools need and what they return, reducing errors and making the agent more accurate.
• Data Validation: Pydantic automatically validates that the data passed to a tool is correct. If not, the agent can report the error, making debugging easier.
• Extensibility: It’s easy to add new tools to expand the agent’s capabilities for various tasks.
• LLM Integration: PydanticAI is designed to work seamlessly with Large Language Models (LLMs), allowing them to understand and use the tools you create effectively.

Real-World Applications

• Calendar Assistant Agent: Can process commands like, “Schedule a meeting about PydanticAI tomorrow at 10 AM.” The agent uses a calendar tool, and Pydantic ensures the title, date, and time are correctly formatted before calling the calendar function.
• Information Retrieval Agent: Can handle queries like, “What’s the weather in Bangkok?” The agent uses a weather API tool, and Pydantic validates that the city name is a valid string before making the API call.

Conclusion

PydanticAI offers a robust framework for building capable and reliable agents. By using Pydantic to define the structure of your tools, you can create agents that handle data in a structured, clear, and safe manner.

We hope this post helps you get started on your agent-building journey! If you have any questions, feel free to ask.