Pydantic AI: como construir agentes type-safe em Python

Se você já perdeu horas depurando um agente que recebia um campo a mais ou a menos, o Pydantic AI ataca esse problema na raiz. Ele define a estrutura esperada das entradas e saídas do agente e valida automaticamente. Se algo não bate, o erro aparece cedo, não no meio da execução.

O repositório pydantic/pydantic-ai tem mais de 21 mil estrelas, licença MIT e recebeu atualização em 9 de novembro de 2026. A comunidade e o ritmo de desenvolvimento indicam maturidade para uso em produção.

O que é o Pydantic AI e como funciona a tipagem

Um agente típico chama um modelo de linguagem, recebe texto e tenta interpretar. Sem tipagem, essa interpretação é frágil. O Pydantic AI inverte a lógica. Você declara um modelo Pydantic para o resultado esperado e o framework garante que a resposta do modelo seja convertida e validada nesse formato.

Isso vale também para as ferramentas que o agente usa. Cada ferramenta tem parâmetros tipados. Se o modelo tentar chamar uma ferramenta com argumento errado, a validação falha de forma clara.

A abordagem lembra o FastAPI, mas para agentes. Você escreve menos código defensivo e mais código de negócio. A tipagem também melhora o autocomplete do editor e a documentação automática.

Como instalar o Pydantic AI e criar o primeiro agente

A instalação é simples. O pacote principal é pydantic-ai.

$ pip install pydantic-ai

Depois, defina o resultado esperado com um modelo Pydantic e crie o agente.

from pydantic import BaseModel
from pydantic_ai import Agent

class Resposta(BaseModel):
    resumo: str
    pontos: list[str]

agent = Agent(
    "openai:gpt-4o",
    result_type=Resposta,
)

result = agent.run_sync("Resuma as vantagens do Pydantic AI em 3 pontos.")
print(result.data.resumo)
print(result.data.pontos)

O método run_sync executa de forma síncrona e retorna um objeto com o campo data já validado. Se a resposta do modelo não couber no modelo Resposta, o framework tenta corrigir ou lança um erro claro.

Você pode trocar o provedor alterando a string do modelo. O Pydantic AI suporta OpenAI, Anthropic, Groq, Google e modelos locais via Ollama. A documentação oficial lista os provedores e suas configurações.

Como validar ferramentas e resultados

Ferramentas são funções que o agente pode chamar. No Pydantic AI, você decora uma função com @agent.tool e declara os parâmetros tipados. O framework gera o esquema para o modelo e valida a chamada.

from pydantic_ai import Agent, RunContext

agent = Agent("openai:gpt-4o")

@agent.tool
def busca_preco(ctx: RunContext, produto: str) -> float:
    # consulta o banco ou a API
    return 42.0

result = agent.run_sync("Qual o preço do produto X?")
print(result.data)

O parâmetro ctx dá acesso ao contexto de execução, como dependências injetadas. Isso facilita testes, porque você pode injetar mocks em vez de chamar serviços reais.

A validação de resultados também ajuda em fluxos multi-etapa. Se um agente precisa passar dados para o próximo, a tipagem garante que o contrato seja respeitado. Em times de agentes, isso reduz erros de integração.

Quando usar Pydantic AI e quando um framework mais pesado faz sentido

O Pydantic AI é leve e focado. Ele não tenta ser um orquestrador completo com filas, memória e dashboards. Se você precisa de coordenação complexa de vários agentes, pode combinar o Pydantic AI com um orquestrador ou usar um framework mais completo.

Use o Pydantic AI quando o problema principal é confiabilidade dos dados e clareza do código. Ele brilha em agentes que chamam ferramentas, extraem informações estruturadas ou classificam conteúdo.

Se você precisa de memória persistente, veja também Mem0: como dar memória persistente a agentes de IA. Se a tarefa exige controle de navegador, veja browser-use: como conectar agentes de IA ao navegador.

Limites e boas práticas

Tipagem forte não resolve todos os problemas. O modelo pode gerar uma resposta válida no formato, mas semanticamente errada. A validação garante a forma, não a verdade. Para dados críticos, adicione verificações de negócio.

Outro ponto é a verbosidade. Declarar modelos para cada resultado adiciona código. Em protótipos rápidos, isso pode parecer excesso. O ganho aparece quando o projeto cresce e precisa de testes automatizados.

Boas práticas que valem para qualquer framework de agentes:

• Defina modelos de resultado pequenos e focados
• Injete dependências via RunContext em vez de globais
• Teste ferramentas isoladamente, sem chamar o modelo
• Monitore tokens e latência em produção

Se você coordena vários agentes, cada um no seu papel e no seu espaço isolado, a tipagem vira contrato entre eles. No bridgecode você monta esse squad e acompanha cada etapa, do planejamento à entrega.

Perguntas frequentes sobre o Pydantic AI

O Pydantic AI é gratuito?

Sim. É open source com licença MIT. O custo vem do provedor de modelo que você escolhe.

Preciso saber Pydantic para usar o Pydantic AI?

Conhecimento básico de Pydantic ajuda, mas não é obrigatório. Os exemplos da documentação cobrem o essencial. O framework incentiva o uso de modelos para resultados.

Pydantic AI substitui LangChain?

Não. Eles resolvem problemas diferentes. LangChain orquestra cadeias e ferramentas. O Pydantic AI foca em tipagem e validação. Você pode usar os dois juntos.

Funciona com modelos locais?

Sim, desde que o provedor seja compatível. Ollama e vLLM funcionam. Verifique a versão suportada na documentação.

Como testar um agente sem chamar o modelo?

Você pode injetar dependências via RunContext e testar ferramentas isoladamente. A documentação mostra padrões de teste com mocks.