Machine Learning Mastery mostrou como construir agentes de IA em Python com Pydantic AI

O Machine Learning Mastery publicou em 29 de abril de 2026 uma análise detalhada do Pydantic AI — um framework Python para construir agentes de IA com type-hinting, validação e ferramentas integradas. O material mostra como transformar o trabalho com LLMs de um conjunto de strings frágeis e parsers em um processo de produção mais previsível.

Por

Que Isso Importa A ideia principal do artigo é simples: a maioria dos scaffolds de agentes ainda se parece com glue code. Um modelo retorna uma string, um desenvolvedor espera que haja JSON válido, depois faz parsing manual da resposta, captura erros e adiciona tratamento de exceções em cada etapa. Pydantic AI oferece um caminho diferente.

Em vez de respostas não estruturadas, ele constrói fluxos de trabalho em torno de modelos Pydantic, schemas, verificação de tipos e retentativas automáticas se a saída do modelo não corresponder à estrutura esperada. Para desenvolvedores Python, isso significa menos magia e mais código que pode ser testado, lido e mantido. O artigo demonstra isso com o exemplo mais básico: um agente é criado em apenas algumas linhas, e o modelo é especificado via formato de string provider:model-name.

O autor usa openai:gpt-4o-mini, mas enfatiza separadamente que o mesmo template funciona com outros provedores, incluindo Anthropic e Gemini. As instruções do agente são definidas uma vez, após o que você pode executar um cenário síncrono via run_sync ou uma variante assíncrona com a mesma API. Isso mantém a barreira de entrada baixa e impede que a arquitetura desabe na primeira complexidade lógica.

Do

Que Consiste a Abordagem A parte mais útil do material é a análise de quatro mecanismos que sustentam o fluxo de trabalho prático do agente em Pydantic AI. O autor não recua para a abstração nem descreve o framework no nível de promessas: cada bloco é acompanhado por um exemplo de código curto e uma explicação de como resolve um ponto específico de dor no desenvolvimento de produção, sem teoria desnecessária. O resultado é um artigo que se lê como um mapa do conjunto mínimo de soluções para um primeiro agente funcional em Python.

output_type força o modelo a retornar dados na forma de um objeto Python validado em vez de texto arbitrário. @agent.tool_plain transforma uma função Python ordinária em uma ferramenta que o agente pode chamar durante o raciocínio.

deps_type e RunContext fornecem injeção de dependência sem estado global e dependências ocultas. capabilities conectam recursos adicionais como WebSearch e Thinking sem sobrecarregar o construtor. O autor mostra separadamente como fica no exemplo de extração de dados de uma oferta de emprego.

O desenvolvedor descreve um modelo JobPosting com campos como cargo, empresa, lista de habilidades, nível de senioridade e indicador de trabalho remoto, e o agente retorna um objeto pronto em vez de texto bruto. Se um campo estiver faltando ou o tipo não corresponder, o framework valida a resposta e tenta novamente antes do erro se propagar mais para o aplicativo. Isso elimina a dor típica de todos os sistemas em que um LLM deve fornecer dados adequados para uso imediato no código.

Como Isso Leva à Produção O segundo exemplo principal no artigo é dedicado ao tool calling.

O autor pega um banco de dados de nutrição simples e registra uma função que retorna calorias, proteínas, carboidratos e gorduras por 100 gramas para um nome de ingrediente. Então o agente recebe uma solicitação como analisar um prato, chama a ferramenta para cada ingrediente, soma os valores e entrega o resultado na forma de um modelo MealSummary. A saída não é uma resposta de chat em forma livre, mas um resumo estruturado com cifras totais, um veredicto sobre composição e uma recomendação.

Um detalhe importante: a docstring da função aqui não é cosmética, mas parte do contrato pelo qual o modelo entende quando e por que chamar a ferramenta. Ainda mais importante é a seção sobre injeção de dependência. Em vez de uma base de dados codificada, o autor envolve a fonte de dados em uma classe NutritionService e a passa ao agente via deps e um RunContext tipado.

Isso aproxima muito o código da operação real: o dicionário pode ser substituído por um banco de dados, cliente de API, sessão de usuário ou qualquer outra dependência de tempo de execução. Além disso, surge uma testabilidade adequada. No exemplo, o serviço é facilmente substituído por um mock e o agente continua funcionando sem mudanças em sua lógica principal.

A camada final são as capacidades integradas. O artigo abrange pelo menos duas: WebSearch para acesso a dados atuais da internet e Thinking para raciocínio passo a passo mais profundo em tarefas complexas. Elas podem ser combinadas em um agente, por exemplo para um assistente de pesquisa que decide por si só o que pesquisar, depois obtém resultados frescos e só então formula uma resposta.

No final, o autor menciona separadamente a integração com Logfire para observabilidade: você pode ver chamadas de modelo, disparadores de ferramentas e tentativas de revalidação.

O

Que Isso Significa O material do Machine Learning Mastery é útil porque desloca a conversa sobre agentes de IA do modo demo para o modo de prática de engenharia. Pydantic AI é mostrado aqui não como outro wrapper sobre um LLM, mas como uma forma de impor disciplina em tipos, dependências e ferramentas. Para equipes Python, este é um bom sinal: agentes podem ser construídos sem um orquestrador pesado se dependerem desde o início de schemas validados, contratos explícitos e componentes de tempo de execução testáveis.