Se você já implementou um recurso LLM e o viu retornar JSON malformado em produção, o PydanticAI foi feito para você. É o framework de agente Python da equipe por trás do Pydantic, e ele coloca saídas validadas e com segurança de tipo no centro do desenvolvimento de agentes. Este guia explica o que é o PydanticAI, por que a segurança de tipo é importante para agentes, os conceitos centrais que você realmente usará e como ele se compara a outros frameworks Python como o LangGraph.
O que é o PydanticAI
PydanticAI é um framework de agente de código aberto e agnóstico a provedores para Python. Ele é mantido pela mesma equipe que desenvolve o Pydantic Validation e o Pydantic Logfire, então herda uma forte base de validação e um objetivo de design claro: trazer “aquela sensação de FastAPI” para a construção de agentes.
Em termos simples, você descreve o que seu agente deve fazer, quais ferramentas ele pode chamar e qual formato sua saída deve ter. O PydanticAI lida com as chamadas de modelo, valida tudo contra seus modelos Pydantic e tenta novamente quando o modelo retorna algo que não se encaixa.
O projeto alcançou uma versão estável v2.0.0 em 23 de junho de 2026, após uma série de versões beta. A V2 se inclina para um design harness-first, onde as ferramentas, hooks, instruções e configurações de modelo de um agente se compõem como unidades reutilizáveis. Você pode instalá-lo com pip install pydantic-ai ou uv add pydantic-ai.
Por que a segurança de tipo é importante para agentes
LLMs são não determinísticos. Faça a mesma pergunta duas vezes e você pode obter dois formatos de resposta diferentes. Isso é bom para uma caixa de chat, mas falha no momento em que você conecta a saída do modelo a um código real: uma gravação em banco de dados, uma chamada de API, um cálculo de faturamento.
A maioria dos bugs de agente vem dessa lacuna. O modelo “na maioria das vezes” retorna JSON válido, seu parser funciona em testes, mas então uma resposta de produção remove um campo ou envolve a resposta em prosa e seu pipeline falha. Você acaba escrevendo parsing defensivo, limpeza com regex e loops de repetição manualmente.
O PydanticAI fecha essa lacuna tornando o contrato de saída parte do framework. Você define um modelo Pydantic, o passa como tipo de saída, e o framework garante que o valor que você recebe de volta corresponde a esse modelo. Se o modelo retornar algo inválido, o PydanticAI envia o erro de validação de volta ao LLM e pede para ele tentar novamente. Seu código downstream recebe objetos tipados, não strings esperançosas.
Essa mesma ideia se estende aos argumentos das ferramentas. Quando o modelo chama uma de suas ferramentas, o PydanticAI valida os argumentos contra as dicas de tipo de sua função antes que a função seja executada. Argumentos inválidos nunca chegam à sua lógica de negócios.
Conceitos centrais
O PydanticAI mantém sua área de superfície pequena. Cinco ideias cobrem a maior parte do que você construirá.
Agentes
A classe Agent é o ponto de entrada principal. Você cria um com um identificador de modelo e instruções opcionais. A classe é genérica em relação a dois parâmetros de tipo: o tipo de dependências e o tipo de saída, que é o que dá ao seu editor e verificador de tipo visibilidade real sobre seu agente.
from pydantic_ai import Agent
agent = Agent(
'anthropic:claude-sonnet-4-6',
instructions='Be concise, reply with one sentence.',
)
result = agent.run_sync('Where does "hello world" come from?')
print(result.output)
Essa string de modelo é tudo o que você altera para trocar de provedor, o que mantém seu código portátil.
Saídas tipadas
Passe um modelo Pydantic como output_type e o resultado do agente será validado contra ele. Você obtém um objeto tipado de volta, e sua IDE conhece todos os campos. Aqui está um esboço de saída estruturada:
from pydantic import BaseModel
from pydantic_ai import Agent
class SupportTicket(BaseModel):
category: str
priority: int
summary: str
agent = Agent('openai:gpt-4o', output_type=SupportTicket)
result = agent.run_sync('My payment failed three times today.')
print(result.output.priority) # um int, validado, não uma suposição
Se o modelo retornar uma prioridade como texto ou omitir o resumo, a validação falha e o framework solicita novamente. Você nunca faz o parsing da resposta bruta por conta própria.
Ferramentas
As ferramentas permitem que o modelo se estenda para fora: consultar um banco de dados, acessar uma API REST, executar um cálculo. Você registra uma ferramenta com o decorador @agent.tool. O PydanticAI lê as dicas de tipo e a docstring da função para construir o esquema que o modelo vê, então valida cada chamada contra ele.
from pydantic_ai import Agent, RunContext
agent = Agent('openai:gpt-4o', deps_type=str)
@agent.tool
async def get_user_balance(ctx: RunContext[str], account_id: str) -> float:
"""Return the current balance for an account."""
# ctx.deps holds your injected dependency
return await lookup_balance(ctx.deps, account_id)
O modelo decide quando chamar a ferramenta. Sua função só é executada com argumentos que já passaram pela validação.
Dependências
Agentes reais precisam de contexto: uma conexão de banco de dados, um cliente HTTP, o usuário atual, uma chave de API. O PydanticAI lida com isso por meio de injeção de dependência. Você declara um deps_type no agente, então o lê através de RunContext dentro de ferramentas e instruções dinâmicas. Toda a cadeia permanece com segurança de tipo, e o teste se torna mais fácil porque você pode trocar dependências reais por fakes.
Provedores agnósticos de modelo e streaming
O PydanticAI suporta uma longa lista de provedores: OpenAI, Anthropic, Gemini, DeepSeek, Grok, Cohere, Mistral, Perplexity, além de opções de nuvem como Azure AI Foundry e Amazon Bedrock e modelos auto-hospedados. A troca é geralmente uma alteração de uma linha na string do modelo.
Ele também faz streaming de saída estruturada com validação aplicada conforme os dados chegam, para que você possa renderizar resultados parciais sem abrir mão das garantias de tipo. E como a equipe também constrói o Pydantic Logfire, a observabilidade é integrada: rastreamento, depuração e acompanhamento de custos para cada execução.
Como o PydanticAI se compara a outros frameworks de agente Python
Não existe um único framework "melhor". Eles otimizam coisas diferentes. Aqui está uma análise honesta de onde o PydanticAI se encaixa.
| Framework | Ponto forte principal | Melhor quando você quer |
|---|---|---|
| PydanticAI | Saídas e argumentos de ferramenta validados e com segurança de tipo | Confiabilidade em produção e fluxo de dados limpo e tipado |
| LangGraph | Grafos com estado explícitos e fluxo de controle | Fluxos de trabalho de longa duração, ramificados e multi-etapas |
| Google ADK | Orquestração multi-agente no ecossistema do Google | Integração profunda com Gemini e Vertex AI |
| OpenAI Agents SDK | Integração estreita com OpenAI e transferências | Uma pilha prioritária de OpenAI e configuração rápida |
A vantagem do PydanticAI é a camada de validação. Se seu agente alimenta dados tipados em outros sistemas, a garantia de que a saída corresponde a um modelo Pydantic remove uma classe inteira de erros de tempo de execução. O LangGraph oferece um controle mais refinado sobre máquinas de estado e fluxos complexos. O OpenAI Agents SDK é um ajuste natural se você já está comprometido com o OpenAI e deseja recursos como transferências de agente e suporte a servidores MCP.
Você também pode misturá-los. O PydanticAI funciona bem como a camada de saída tipada dentro de uma orquestração maior.
Quando usar o PydanticAI
Recorra ao PydanticAI quando:
- A saída do seu agente vai para o código, não apenas para uma janela de chat, e o formato precisa estar correto.
- Você quer que seu verificador de tipo e IDE entendam seu agente de ponta a ponta.
- Você já usa Pydantic em sua base de código, então as definições de modelo parecem nativas.
- Você precisa de flexibilidade de provedor e não quer reescrever seu agente para trocar de modelo.
- A observabilidade importa e o rastreamento integrado do Logfire é atraente.
Procure outras opções quando você precisar de uma orquestração pesada baseada em grafo com ramificações complexas, onde um framework de máquina de estados oferece um controle mais direto.
Testando e simulando as APIs por trás do seu agente
Um agente PydanticAI é tão confiável quanto as APIs das quais ele depende. Cada execução chama um provedor LLM, e a maioria dos agentes úteis também chamam seus próprios endpoints REST ou ferramentas de terceiros. Essas chamadas são onde comportamentos instáveis, custos inesperados e incompatibilidades de formato se manifestam. O PydanticAI valida a saída do modelo, mas não pode validar se a API da ferramenta upstream que você está chamando retorna o que você espera.
É aqui que o Apidog se encaixa, e é uma função diferente do framework. O Apidog é uma plataforma de API onde você testa e simula as APIs subjacentes com as quais seu agente se comunica.
Alguns usos concretos:
- Simule o LLM ou um endpoint de ferramenta. Durante o desenvolvimento, aponte uma ferramenta para uma API simulada que retorna respostas determinísticas. Você para de queimar tokens em cada execução de teste e evita os limites de taxa do provedor enquanto itera.
- Afirme os formatos de resposta. Antes de conectar um endpoint REST a uma função
@agent.tool, use asserções de API para confirmar que a resposta real corresponde à estrutura que sua ferramenta espera. Pegue um campo ausente na camada da API, não profundamente em uma execução de agente. - Gerencie chaves por ambiente. Mantenha as chaves do provedor e as URLs base em ambientes Apidog separados para que as execuções locais, de staging e de CI atinjam os alvos corretos sem alterações de código.
- Verifique o endpoint do LLM diretamente. Se você chamar um provedor via HTTP, você pode testar a API do ChatGPT com Apidog para confirmar a autenticação, streaming e formatos de chamada de ferramenta antes que seu agente dependa deles.
O Apidog não constrói nem orquestra agentes, e não é uma alternativa ao PydanticAI. É a bancada onde você testa e simula a superfície da API na qual seu agente opera. Se você quiser experimentar, baixe o Apidog e simule um de seus endpoints de ferramenta primeiro.
Perguntas frequentes
O PydanticAI é gratuito e de código aberto?
Sim. O PydanticAI é de código aberto e você o instala do PyPI com pip install pydantic-ai ou uv add pydantic-ai. Você ainda pagará por qualquer provedor LLM que usar, já que o framework chama essas APIs em seu nome. Para manter esses custos do provedor baixos enquanto você desenvolve, você pode simular as respostas da API durante os testes em vez de acessar o modelo ao vivo em cada execução.
Com quais modelos o PydanticAI funciona?
É agnóstico a provedores. A documentação lista OpenAI, Anthropic, Gemini, DeepSeek, Grok, Cohere, Mistral, Perplexity, além de opções de nuvem como Azure AI Foundry e Amazon Bedrock e modelos auto-hospedados. Você seleciona um modelo passando uma string como 'anthropic:claude-sonnet-4-6' ou 'openai:gpt-4o' para o construtor Agent, e a troca é geralmente uma alteração de uma linha.
Em que o PydanticAI difere do LangChain ou LangGraph?
O PydanticAI se concentra na segurança de tipo: saídas estruturadas validadas e argumentos de ferramentas validados, suportados por modelos Pydantic. O LangGraph se concentra em grafos de estado explícitos para fluxos de trabalho de várias etapas e ramificações. Se sua prioridade são formatos de saída garantidos e um fluxo de dados limpo e tipado, o PydanticAI se encaixa bem. Se você precisa de controle refinado sobre uma máquina de estado complexa, um framework de grafo oferece alavancas mais diretas.
Preciso conhecer Pydantic para usá-lo?
Ajuda, mas os fundamentos são rápidos de aprender. Você define formatos de dados como classes que herdam de BaseModel, e o PydanticAI usa isso para saídas e esquemas de ferramentas. Se você usou Python para testes de API ou trabalhou com FastAPI, o modelo mental parecerá familiar.
Conclusão
O PydanticAI traz algo prático para o desenvolvimento de agentes: a garantia de que a saída do seu modelo e as chamadas de ferramentas correspondem aos tipos que você declarou. Isso remove uma fonte real de bugs de produção e mantém seu fluxo de dados limpo. Escolha-o quando a confiabilidade e as saídas tipadas importarem mais do que uma orquestração pesada de grafo.
Qualquer que seja o framework que você escolher, as APIs subjacentes ao seu agente ainda precisam de testes. Simule seu LLM e os endpoints das ferramentas, afirme seus formatos de resposta e gerencie as chaves por ambiente no Apidog para que seu agente funcione em uma base que você realmente verificou.