Pydantic AI
Pydantic AI is a Python framework for building AI agents whose tool inputs and final answers are checked against types you define.
Pydantic is the most popular Python library for checking data. You describe the shape you expect, such as “a whole number from 0 to 10”, using ordinary Python type hints. Pydantic then checks real data against that shape and complains when it does not fit. The Pydantic team built Pydantic AI to bring the same idea to AI agents.
An agent here is a program where a language model can call your functions and then give a final answer. The trouble is that a model writes text. Your code wants exact data. Pydantic AI turns your types into a JSON Schema, a machine-readable description of the fields, and hands it to the model. When the answer comes back, Pydantic checks it. If a field is wrong, the error goes back to the model, which gets another try.
Picture a bank’s support helper. A customer types that they lost their card. The agent can call a tool that reads their account. It reaches the database through a dependency, which is anything your code hands the agent to use. Its final answer must fill three fields: advice for the customer, whether to block the card, and a risk score. Your program gets those as a checked Python object. It does not have to pick apart a paragraph.
The same agent can talk to OpenAI, Anthropic, Gemini and many other providers, usually by changing one model name. For testing, a built-in test model runs offline without calling any real model. You can also swap in fake dependencies.
Plain model replies are hard for the rest of a program to trust.
Follow one bank support question through an agent run.
- 1 · defineYou create an agent with instructions, tools, a dependency type and an output type.
- 2 · runThe agent sends the user's message to the model along with the tool and output schemas.
- 3 · callThe model may call a tool, and Pydantic validates the arguments before your function runs.
- 4 · checkThe final answer is validated against the output type, and a failure asks the model to try again.
- 5 · returnYour code receives an object of the type you declared.
Pydantic AI turns a model reply into data your code can rely on.
| Who | What they ask | What it works with |
|---|---|---|
| Bank support team | “I just lost my card, what should I do?” | Customer account data passed in as dependencies |
| Product team | “How are people feeling about our app?” | Review snippets fetched by a tool, returned as a sentiment label and score |
| Data team | “Turn this question into a database query” | The SQL generation example in the docs |
| Platform team | “Can we move this agent to another model provider?” | The model name string set on the agent |
- Final answers arrive as typed Python objects, checked by Pydantic.
- Wrong tool arguments are caught and the error goes back to the model to retry.
- The same agent can switch model providers by changing the model it uses.
- Dependencies such as a database connection reach tools in a type-safe way.
- A valid shape does not mean the content is true or wise.
- If the model is not capable enough, retries may still fail.
- It does not remove the need to test and watch what agents do.
- Runs still cost tokens and requests, so limits need setting.
Sources used
This explainer is written in original language. The links below support its factual claims.
- docsPydantic AI, Pydantic · read 28 Sept 2026
- docsAgents, Pydantic · read 28 Sept 2026
- docsFunction Tools, Pydantic · read 28 Sept 2026
- docsOutput, Pydantic · read 28 Sept 2026
- docsDependencies, Pydantic · read 28 Sept 2026
- docsModel Providers, Pydantic · read 28 Sept 2026
- docsPydantic Validation, Pydantic · read 28 Sept 2026