Pydantic AI: quando usar agentes inteligentes em Python

Conteúdo verificado na documentação do fabricante e na licença do repositório em 17 de outubro de 2026. Os critérios de escolha aqui são validação de saídas, acesso aos serviços da aplicação, controle do fluxo de trabalho e recuperação de falhas, sem um ranking de desempenho.

O que é Pydantic AI?

Pydantic AI é o SDK de agentes em Python criado pela equipe do Pydantic. Ele reúne um modelo, instruções, funções Python que podem ser chamadas e um tipo de saída opcional em um Agent, o objeto que sua aplicação executa. O modelo é o sistema que gera respostas; o SDK gerencia as interações ao redor dele. A visão geral atual apresenta um SDK mais abrangente, mas esse é o núcleo necessário para criar uma funcionalidade de produto.

Pense nisso como definir um contrato de função para um colaborador imprevisível. A aplicação fornece o contexto e as operações permitidas, depois exige um resultado com campos nomeados. Isso é útil quando uma funcionalidade de suporte precisa produzir uma categoria e um próximo passo que o código Python convencional consiga consumir.

Agentes no Pydantic AI: a unidade que você reutiliza

Um Agent guarda a configuração de uma tarefa. Cada execução é uma tentativa específica de realizá-la, com um prompt e dependências fornecidas em tempo de execução. Você pode chamar run_sync() em um script síncrono ou await agent.run() no código assíncrono da aplicação; ao terminar, o resultado disponibiliza seu valor final em .output. Essas interfaces estão documentadas nas APIs de Agent.

A tipagem cumpre dois papéis distintos. A tipagem estática ajuda o editor ou o verificador de tipos a identificar incompatibilidades no código Python. Já a validação da saída em tempo de execução confere se os dados devolvidos pelo modelo correspondem ao esquema declarado. Nenhuma das duas elimina a ambiguidade de uma solicitação de suporte.

Ferramentas no Pydantic AI: funções com o contexto da aplicação

As ferramentas baseadas em funções permitem que o modelo solicite algo que seu código sabe fazer, como consultar uma assinatura. Registre uma função que precisa do contexto com @agent.tool, ou use @agent.tool_plain quando ela não precisar do contexto da execução. As anotações de tipo descrevem os argumentos, e as docstrings ajudam a explicar a ferramenta ao modelo. A documentação de ferramentas baseadas em funções mostra como essas informações se tornam esquemas de ferramentas.

Injeção de dependências significa passar a cada execução os serviços de que ela precisa. Com deps_type=CustomerContext, você declara o tipo Python esperado; com deps=customer_context, fornece a instância concreta. A ferramenta recebe RunContext[CustomerContext] e acessa esse objeto por ctx.deps. O contexto pode carregar um cliente autenticado, uma conexão com o banco de dados ou um cliente de API. O guia de dependências deixa explícito que deps_type auxilia a verificação de tipos, sem validar o objeto de dependência em tempo de execução.

Para quem desenvolve um SaaS, o ganho é concreto: o servidor pode selecionar a conta do cliente antes que o modelo solicite uma consulta. Mantenha a autorização no código que faz a consulta. Passar um cliente de banco de dados por um contexto tipado não limita quais registros ele pode ler.

Saída estruturada no Pydantic AI: o que é validado?

output_type define o resultado que a aplicação espera receber. Forneça um BaseModel do Pydantic, uma classe Python com campos tipados, e o Pydantic AI deriva um esquema e valida os dados gerados. A documentação de saídas também contempla outros tipos, como dataclasses, listas e uniões.

Os três modos de saída mudam a forma de pedir esses dados ao modelo:

Esses são os três modos de saída documentados do SDK, não três níveis de precisão. Escolha o mecanismo suportado pelo modelo e avalie o resultado na sua tarefa.

Uma falha de validação pode ser devolvida ao modelo para uma nova tentativa. Há um limite de tentativas, e esgotar as repetições de saída pode gerar UnexpectedModelBehavior. A aplicação precisa prever o que fazer nesse caso, como pedir as informações que faltam ou encaminhar a solicitação para uma pessoa. Consulte o comportamento das novas tentativas.

Tutorial de Pydantic AI: uma decisão de suporte com saída validada

Comece com um objeto de decisão somente de leitura, antes de dar ao agente permissão para alterar qualquer coisa. O exemplo adapta os padrões documentados de Agent, RunContext e output_type a uma pequena tarefa de triagem de suporte.

O guia de instalação atual exige Python 3.11 ou superior. Em um ambiente virtual, instale a biblioteca:

python -m pip install pydantic-ai

Defina OPENAI_API_KEY no ambiente para uma conta com acesso ao modelo. Salve o código abaixo como triage.py e execute python triage.py. O identificador do modelo segue a documentação atual de Agent; você pode substituí-lo por um modelo suportado e disponível na sua conta.

from dataclasses import dataclass
from typing import Literal

from pydantic import BaseModel
from pydantic_ai import Agent, RunContext

@dataclass
class Customer:
    plan: str

class Triage(BaseModel):
    category: Literal['billing', 'technical']
    priority: Literal['normal', 'urgent']
    summary: str

agent = Agent(
    'openai:gpt-6.1-sol',
    deps_type=Customer,
    output_type=Triage,
    instructions=(
        'Triage the support message. Use customer_plan for context. '
        'Summarize the issue without inventing account facts.'
    ),
)

@agent.tool
def customer_plan(ctx: RunContext[Customer]) -> str:
    """Return the authenticated customer's plan."""
    return ctx.deps.plan

if __name__ == '__main__':
    result = agent.run_sync(
        'I was charged twice for my subscription.',
        deps=Customer(plan='business'),
    )
    print(result.output.model_dump())

Quando a execução termina com sucesso, result.output é um objeto Triage. A categoria e a prioridade precisam corresponder às opções declaradas, e model_dump() converte o objeto em um dicionário. A ferramenta de contexto, o resultado tipado e a rejeição de uma categoria inválida desse exemplo foram verificados offline com TestModel. A redação gerada pelo modelo e a precisão da triagem ainda precisam ser avaliadas com seus próprios casos.

O contexto do cliente é ilustrativo. Em um produto, construa esse contexto a partir da requisição autenticada e dos registros da conta. Defina também o que torna um caso urgente: o esquema lista os rótulos válidos, mas não contém uma política de urgência. Essa regra de negócio que falta importa mais do que adicionar outro agente.

Modelos no Pydantic AI: trocar de provedor exige avaliar o comportamento

O Pydantic AI reduz o código de integração específico de cada provedor, mas trocar de modelo continua mudando o comportamento. Muitas integrações usam um identificador no formato <provider>:<model>. Algumas exigem um modelo ou cliente explícito, credenciais adequadas e extras de instalação. Os recursos disponíveis dependem do modelo e da API escolhidos, como mostra o diretório de provedores.

O diretório inclui OpenAI, Anthropic, Google/Gemini, AWS Bedrock, Groq, Mistral, xAI e Ollama. As demais integrações documentadas abrangem:

• Serviços de modelos e inferência: Alibaba Cloud/Qwen, Cerebras, Cohere, Crusoe, DeepSeek, Fireworks AI, Heroku AI, Hugging Face, Meta, Moonshot AI/Kimi, Nebius AI Studio, OVHcloud AI Endpoints, SambaNova, Snowflake Cortex, Together AI e Z.AI.
• Opções de nuvem, gateway e hospedagem própria: Google Cloud/Vertex AI, Microsoft Azure/Foundry, Pydantic AI Gateway, LiteLLM, OpenRouter, Vercel AI Gateway e vLLM.
• Outras formas de acesso e integrações com modelos de decisão: GitHub Copilot, OpenAI Codex, OpenAI Decisions API, System One API e TypeSafe (Jev).

Esses nomes representam diferentes formas de acessar modelos, cada uma com seus próprios recursos. Um modelo local pode se comportar de outra forma ao usar ferramentas em comparação com um modelo de ponta hospedado; uma API compatível ainda pode impor restrições diferentes ao esquema.

Para quem fundou a empresa, a portabilidade oferece uma alternativa de saída e espaço para experimentar. Para quem implementa a troca, o teste de aceitação continua o mesmo: o substituto escolhe as ferramentas certas, respeita o esquema de saída e toma decisões aceitáveis nos mesmos casos? Reúna essas evidências antes de mudar o modelo padrão em produção.

MCP e execução durável: conectar ferramentas e preservar o progresso

O MCP conecta um agente a servidores de ferramentas; a execução durável ajuda uma execução a sobreviver a interrupções. Cada um resolve um problema diferente.

O Model Context Protocol, ou MCP, padroniza como aplicações disponibilizam ferramentas e contexto para clientes de IA. O suporte a MCP do Pydantic AI aceita URLs de servidores, clientes ou conjuntos de ferramentas, com opções de MCP nativo do provedor quando há suporte. Isso permite reutilizar um servidor de ferramentas em vez de criar uma integração para cada agente. O protocolo não decide qual cliente tem permissão para usar as operações desse servidor.

Execução durável significa preservar o progresso para que o trabalho possa continuar após uma falha, reinicialização ou espera prolongada. A documentação atual de durabilidade lista 9 soluções:

• Mantidas em conjunto com as equipes dos fornecedores: Temporal, DBOS, Prefect, Restate e AWS Lambda.
• Integrações externas com o SDK: Kitaru, Apache Airflow, Absurd e pgtask.

Também há um construtor de backends para outros mecanismos de execução. Escolha uma integração documentada quando o agente precisar continuar existindo além da requisição ou do processo que o iniciou. A existência dessas integrações não torna uma chamada isolada a Agent uma implantação com execução durável.

Imagine uma tarefa de suporte que prepara uma recomendação de reembolso, espera a aprovação e depois efetiva a operação. Uma execução salva pode preservar o trabalho que está aguardando, mas a operação de pagamento ainda precisa de idempotência: repetir a requisição não deve gerar outro reembolso. Defina como identificar uma operação já realizada e como reconciliar um resultado incerto. Essa responsabilidade cabe à aplicação, em conjunto com o mecanismo de execução.

Pydantic AI e avaliações: confira a decisão por trás do objeto

Pydantic Evals testa se o trabalho do agente foi aceitável, para além de verificar se a saída pode ser interpretada. É um pacote separado de avaliação definida em código, que não exige Pydantic AI. Você define casos e avaliadores, executa a tarefa com esses casos e examina um relatório; a documentação cobre tanto a avaliação das saídas finais quanto das trajetórias de chamadas de ferramentas, ou seja, a sequência de ações realizadas durante uma execução.

Para o exemplo de triagem, crie casos de cobrança duplicada, falha de login, ausência de contexto da conta e uma mensagem que peça ao assistente para ignorar suas instruções. Confira a categoria, a decisão de encaminhar o caso e se a consulta obrigatória à conta foi feita. Inclua casos em que a resposta aceitável seja fazer uma pergunta.

Para quem opera o sistema, um trace explica uma execução; uma avaliação mede o comportamento em vários casos. O Pydantic AI usa OpenTelemetry, um padrão de telemetria de aplicações, e suporta outros backends de observabilidade por meio de sua instrumentação. Quando um caso falhar, examine a requisição ao modelo e as chamadas de ferramentas, depois mantenha esse caso no conjunto de avaliação.

O serviço opcional Pydantic Logfire oferece rastreamento de agentes, modelos e ferramentas; o plano Personal é gratuito e o Team começa em US$49/mês, com uso adicional e licenças de usuário cobrados à parte, segundo a página de preços.

Quando escolher Pydantic AI em vez de outro framework?

Escolha a abstração que corresponde à parte difícil da sua funcionalidade. Quem desenvolve em Python e já tem modelos de domínio e serviços deve considerar Pydantic AI quando o principal desafio de integração está nas entradas, ferramentas e saídas tipadas. Quem fundou uma empresa e tem perfil técnico deve avaliar qual opção resulta na estrutura de operação mais enxuta que a empresa consegue explicar e manter.

Pydantic AI vs LangGraph

LangGraph é um ponto de partida mais adequado quando você quer desenhar explicitamente o fluxo de trabalho em torno do agente. Sua documentação se concentra em agentes de longa duração que mantêm estado, execução durável e intervenção humana. Pense em uma aplicação com etapas obrigatórias: reunir evidências, obter aprovação, executar uma ação autorizada e reconciliar o resultado.

O Pydantic AI é atraente quando o agente tipado é um componente de um processo que a aplicação já controla. Ele também pode participar de fluxos duráveis, portanto a persistência, por si só, não resolve a escolha. A pergunta decisiva é se você quer modelar o processo de negócio ao redor do agente ou, principalmente, configurar o comportamento do próprio agente. O desafio do LangGraph é assumir o desenho do fluxo e a gestão do estado; no Pydantic AI, é lembrar que a praticidade do contrato do agente não desenha o processo inteiro por você.

Pydantic AI vs LangChain

LangChain faz sentido quando suas integrações de modelos e ferramentas e sua arquitetura de agentes já se encaixam na aplicação. Os agentes do LangChain são construídos sobre LangGraph, segundo a visão geral do LangChain. Portanto, escolher sua API de agentes de mais alto nível mantém essa base de execução.

Escolha Pydantic AI para um serviço Python quando seus contratos de dependências e saídas combinarem com a forma como você já escreve código. Mantenha uma funcionalidade que funciona em LangChain, a menos que consiga apontar uma fonte concreta de complexidade que a migração elimine. Ainda é preciso entender a abstração do LangChain quando o comportamento atravessa as camadas do agente e do fluxo de trabalho; trocar de biblioteca apenas desloca esse trabalho. A relação entre os dois é explorada em LangChain vs LangGraph.

OpenAI Agents SDK ou chamadas diretas à API

OpenAI Agents SDK atende a ciclos de agentes executados na própria aplicação, com ferramentas, transferências entre agentes e rastreamento. O SDK roda na sua aplicação e suporta saídas estruturadas; suas interfaces de provedores também acomodam modelos de outros fornecedores além da OpenAI. Seria incorreto tratar a saída tipada ou a escolha de provedor como exclusividades do Pydantic AI.

Escolha esse SDK quando seu modelo de agentes e transferências combinar com a integração com OpenAI que você pretende manter. Escolha Pydantic AI quando o modelo de dependências em Python e a configuração de provedores se encaixarem melhor. Nos dois casos, a implantação, a autorização das ferramentas e o funcionamento correto da aplicação continuam sob sua responsabilidade.

Use chamadas diretas à API quando a tarefa for uma requisição ao modelo com um pouco de código determinístico ao redor. APIs diretas já podem devolver saídas restritas por esquema. Um extrator de recibos não precisa de um framework de agentes só porque o resultado é um objeto Pydantic. O limite aparece quando você passa a reconstruir, em várias funcionalidades, os ciclos de chamadas de ferramentas, as novas tentativas de validação e a instrumentação.

Para uma escolha mais ampla, consulte o guia de frameworks de agentes de IA. Se a dúvida ainda for entre controlar explicitamente o fluxo de trabalho ou usar agentes com papéis especializados, siga para LangGraph vs CrewAI.

Onde o discurso sobre agentes tipados exagera

O exagero está em afirmar que um agente tipado é, automaticamente, um sistema correto em produção. Há vários limites que a biblioteca não consegue eliminar:

• Segurança de tipos não é precisão factual. Uma resposta bem formada pode interpretar mal o pedido do usuário. Defina o que deve ser conferido em registros oficiais.
• Portabilidade de modelos não garante qualidade equivalente. Uma nova configuração de provedor precisa da mesma avaliação da tarefa que um novo prompt.
• Durabilidade não significa implantação automática. Escolha e opere o mecanismo de execução, o armazenamento e o caminho de recuperação de que a funcionalidade precisa.
• Uma nova tentativa significa trabalho adicional. Outra requisição ao modelo acrescenta latência e consumo. Defina explicitamente o que a aplicação faz quando as tentativas se esgotam.

Avance agora se a próxima funcionalidade em Python já precisar de ferramentas e decisões estruturadas. Adie a migração de framework se o sistema atual funciona e o benefício proposto se resume a um código de demonstração mais bonito. Pouco muda para você se a funcionalidade é uma chamada simples de extração com validação e tratamento de erros adequados.

Perguntas frequentes sobre Pydantic AI

O que colocar em produção na próxima semana

Defina critérios claros de aceitação para uma pequena funcionalidade somente de leitura antes de ampliar sua autonomia. Em um produto de suporte, comece com o objeto de triagem do exemplo e mantenha a ação final sobre a conta no código convencional da aplicação.

Para receber dicas práticas sobre como desenvolver funcionalidades de IA, assine a newsletter.