Machine Learning Mastery mostra como criar agentes de IA em Python com Pydantic AI

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

Por que isso importa

A ideia central do artigo é simples: a maior parte da infraestrutura de agentes ainda lembra glue code. O modelo devolve uma string, o desenvolvedor espera que ela traga um JSON correto, depois analisa a resposta manualmente, captura erros e adiciona exceções a cada etapa.

O Pydantic AI propõe outro caminho. Em vez de respostas sem estrutura, ele se organiza em torno de modelos Pydantic, esquemas, verificação de tipos e novas tentativas automáticas quando a saída do modelo não corresponde à estrutura esperada. Para quem desenvolve em Python, isso significa menos mágica e mais código que pode ser testado, lido e mantido.

O artigo demonstra isso desde o exemplo mais básico: o agente é criado em poucas linhas, e o modelo é indicado por uma string no formato provider:model-name. O autor usa openai:gpt-4o-mini, mas destaca que o mesmo padrão funciona com outros provedores, incluindo Anthropic e Gemini. As instruções do agente são definidas uma única vez, e depois é possível executar uma chamada síncrona com run_sync ou uma versão assíncrona com a mesma API. Com isso, a barreira de entrada continua baixa, e a arquitetura não desmorona na primeira vez que a lógica se complica.

Do que o método é feito

A parte mais útil do material é a análise dos quatro mecanismos que sustentam o fluxo prático de agentes no Pydantic AI. O autor não se perde em abstrações nem descreve o framework com base em promessas: cada bloco vem com um exemplo curto de código e uma explicação de qual problema concreto de produção ele resolve, sem teoria desnecessária. O resultado é um artigo que funciona como um mapa do conjunto mínimo de soluções para o primeiro agente funcional em Python.

• output_type obriga o modelo a devolver dados na forma de um objeto Python validado, e não de texto livre.
• @agent.tool_plain transforma uma função comum de Python em uma ferramenta que o agente pode chamar durante o raciocínio.
• deps_type e RunContext oferecem injeção de dependências sem estado global nem dependências ocultas.
• capabilities adicionam recursos extras, como WebSearch e Thinking, sem sobrecarregar o construtor.

O autor também mostra como isso funciona na extração de dados de uma vaga de emprego. O desenvolvedor descreve um modelo JobPosting com campos como cargo, empresa, lista de habilidades, nível de seniority e indicação de trabalho remoto, e o agente devolve um objeto pronto em vez de texto bruto. Se um campo estiver ausente ou um tipo não bater, o framework valida a resposta e tenta de novo antes que o erro chegue ao restante do aplicativo. Isso elimina a dor típica de qualquer sistema em que um LLM precisa entregar dados prontos para uso imediato no código.

Como isso leva à produção

O segundo grande exemplo do artigo trata de tool calling. O autor usa uma base nutricional simples e registra uma função que, a partir do nome de um ingrediente, devolve calorias, proteínas, carboidratos e gorduras por 100 gramas. Em seguida, o agente recebe um pedido, como analisar um prato, chama a ferramenta por conta própria para cada ingrediente, soma os valores e entrega o resultado como um modelo MealSummary.

A saída não é uma resposta de chat em formato livre, mas um resumo estruturado com os totais, um veredito sobre a composição e uma recomendação. Um detalhe importante: o docstring da função não é cosmético, e sim parte do contrato pelo qual o modelo entende quando e por que chamar a ferramenta.

Ainda mais importante é o bloco sobre injeção de dependências. Em vez de um dicionário fixo no código, o autor encapsula a fonte de dados em uma classe de serviço, NutritionService, e a passa ao agente por meio de deps e de um RunContext tipado. Isso aproxima muito o código da operação real: no lugar do dicionário pode haver um banco de dados, um cliente de API, uma sessão de usuário ou qualquer outra dependência de runtime. Além disso, a testabilidade melhora. No exemplo, o serviço é facilmente trocado por um mock, e o agente continua funcionando sem mudanças em sua lógica principal.

A camada final são as capabilities integradas. O artigo analisa pelo menos duas: WebSearch, para acessar dados atuais da internet, e Thinking, para um raciocínio passo a passo mais profundo em tarefas complexas. Elas podem ser combinadas em um mesmo agente, por exemplo em um assistente de pesquisa que decide o que buscar, obtém resultados recentes e só então elabora a resposta. No final, o autor aponta a integração com o Logfire para observabilidade: é possível ver as chamadas ao modelo, o acionamento de ferramentas e as novas tentativas de validação.

O que isso significa

O material da Machine Learning Mastery é útil porque tira a conversa sobre agentes de IA do modo demo e a leva para a prática de engenharia. O Pydantic AI aparece não como mais um wrapper de LLM, mas como uma forma de impor disciplina a tipos, dependências e ferramentas. Para equipes Python, é um bom sinal: dá para construir agentes sem um orquestrador pesado, desde que se apoie, desde o início, em esquemas validáveis, contratos explícitos e componentes de runtime testáveis.