Como Criar Agentes de IA com PydanticAI em Python: Guia Prático

Criar agentes autônomos de IA em Python costumava exigir frameworks pesados, cheios de abstrações obscuras e respostas em texto não estruturado difíceis de validar. Quando o agente precisa interagir com bancos de dados, APIs corporativas ou tomar decisões de alto impacto, a falta de tipagem estática e validação estrita torna a aplicação frágil em produção.

É exatamente essa dor que o PydanticAI resolve, trazendo a simplicidade e a robustez do Pydantic tradicional para o ecossistema de agentes. Neste guia prático, você aprenderá como estruturar agentes tipados, definir ferramentas de execução (tools) e garantir retornos estruturados com validação nativa.

O Que É o PydanticAI e Por Que Ele Simplifica a Criação de Agentes

Criado pela mesma equipe por trás do Pydantic — a biblioteca de validação de dados mais utilizada no ecossistema Python —, o PydanticAI é um framework focado na construção de sistemas de IA produtivos e seguros. Ele se conecta nativamente aos principais LLMs (como OpenAI, Anthropic e Gemini) garantindo que todas as entradas e saídas sigam esquemas estritamente tipados.

A grande vantagem do PydanticAI em relação a outros frameworks é a ausência de 'magia' oculta nas abstrações. Ele se apoia em modelos Pydantic padronizados, injeção de dependência explícita e suporte nativo ao Python assíncrono, permitindo capturar erros de schema antes mesmo de enviar a resposta para o usuário final.

Além disso, o framework integra-se perfeitamente com ferramentas de observabilidade como o Logfire, facilitando a auditoria de cada chamada de função e raciocínio realizada pelo agente em tempo real.

Os 4 Pilares para Estruturar um Agente Robusto com PydanticAI

Para construir um agente funcional e pronto para produção, você deve estruturar o código seguindo quatro componentes essenciais do framework:

1. Instanciação do Agente e Seleção do Modelo

Defina a classe Agent informando o modelo base (como gpt-4o ou claude-3-5-sonnet) e as instruções do sistema que guiarão o comportamento padrão da IA.

2. Definição do Modelo de Saída (Result Type)

Passe uma classe Pydantic como parâmetro result_type para forçar o agente a retornar dados estruturados e tipados, eliminando a necessidade de parsear texto bruto.

3. Registro de Ferramentas de Ação (@agent.tool)

Decore funções Python com @agent.tool para permitir que o modelo execute ações externas, como consultar APIs ou bancos de dados de forma autônoma.

4. Gerenciamento de Estado e Injeção de Dependência

Utilize a classe RunContext para passar dependências do seu sistema (como conexões de banco ou chaves de API) de maneira segura e isolada para os agentes.

Exemplo Prático: Agente de Suporte Técnico para E-commerce

Imagine um cenário onde você precisa criar um agente responsável por consultar o status de pedidos de clientes em uma loja virtual brasileira e responder de forma estruturada.

• Estruturação da Saída:: Criamos um modelo StatusPedidoResponse com Pydantic contendo campos como id_pedido, status e previsao_entrega.
• Criação da Ferramenta:: Definimos a função buscar_pedido decorada com @agent.tool, que simula a consulta a um banco de dados PostgreSQL.
• Execução e Validação:: Ao rodar agent.run_sync(), o PydanticAI identifica a intenção, chama a tool e retorna o objeto Python validado nativamente.

Caso o LLM tente gerar um valor fora do formato esperado, o PydanticAI força uma nova tentativa automática (retry) até obter um dado válido.

Erros Comuns ao Desenvolver Agentes com PydanticAI

• Ignorar docstrings nas ferramentas:. O LLM utiliza a docstring da função decorada para entender quando deve executá-la; ocultar essa explicação faz o agente ignorar a ferramenta.
• Não limitar o número de retries:. Permitir tentativas infinitas de validação de schema pode aumentar drasticamente seus custos de API com requisições redundantes.
• Acoplar estado global no agente:. Evite usar variáveis globais para guardar o histórico do usuário; prefira utilizar o mecanismo nativo de RunContext para manter o agente isolado.
• Usar tipos genéricos em excesso:. Fornecer tipos muito vagos (como Any ou dict) frustra o objetivo principal da biblioteca, reduzindo a precisão do Structured Output.

Como Praticar e Evoluir Seus Agentes Amanhã

Para começar a aplicar o PydanticAI hoje mesmo, instale a biblioteca via pip e construa um protótipo simples de agente que consulte dados de uma API pública. Foque em mover a lógica que antes ficava em prompts textuais para modelos de dados Pydantic bem definidos.

Conforme seus fluxos de IA se tornarem mais complexos — exigindo a coordenação de múltiplos agentes e integrações avançadas —, investir em arquiteturas organizadas será o diferencial entre um script de teste e um sistema autônomo escalável em produção.