PydanticAI

1. Visão geral do conceito e problema sistêmico

A primeira onda de bibliotecas para trabalhar com modelos de linguagem foi criada na era da prototipagem rápida: elas dependiam de classes dinâmicas aninhadas, dicionários não tipados, prompts invisíveis e herança complexa. Em backends de produção, isso gerava dificuldades catastróficas:

1. Ausência de autocompletar e refatoração: A IDE não entende quais campos o agente retorna, e a renomeação de uma propriedade quebra o código em runtime sem avisos prévios.
2. Complexidade na testabilidade: É impossível isolar a lógica do agente de serviços externos ou substituir o banco de dados por um mock de teste devido à falta de Injeção de Dependência (DI) adequada.
3. Tratamento não confiável de erros de estrutura: Os modelos frequentemente omitem campos obrigatórios ou confundem tipos (por exemplo, string em vez de número), levando a falhas na API.

PydanticAI, desenvolvido por Samuel Colvin (autor do Pydantic), traz o desenvolvimento de agentes de volta ao caminho da engenharia de software clássica e limpa: é um framework tipado, minimalista e rápido, construído sobre o padrão Pydantic v2.

2. Taxonomia arquitetural e modelo mental

A arquitetura do PydanticAI baseia-se em quatro pilares conceituais:

• 1. Agente parametrizado (Agent[Deps, ResultType]): O agente é explicitamente tipado por dois parâmetros: o tipo das dependências de contexto (Deps) de que ele precisa para operar, e o tipo do resultado final (ResultType). Se o resultado for um modelo Pydantic, o agente garante retornar uma instância validada da classe.
• 2. Contexto de execução e DI (RunContext[Deps]): Mecanismo de injeção de dependências. Cada ferramenta e prompt dinâmico acessa ctx.deps, onde são armazenadas conexões ativas com o banco de dados, configurações ou informações sobre as permissões do usuário.
• 3. Ferramentas tipadas (@agent.tool): Funções Python cujos argumentos são automaticamente convertidos em JSON Schema para a LLM. As descrições dos argumentos são extraídas dos Type Hints e docstrings.
• 4. Prompts de sistema dinâmicos (@agent.system_prompt): Funções assíncronas que constroem a instrução de sistema "on the fly" com base nas dependências passadas (por exemplo, inserindo o saldo atual do usuário ou o fuso horário).

3. Pipeline técnico e mecânica interna

O ciclo de vida da execução de uma requisição no PydanticAI:

1. Instantiation & Context Binding (Montagem do contexto): Ao chamar agent.run(prompt, deps=my_deps), o framework inicializa o RunContext e resolve todas as funções marcadas com o decorator @agent.system_prompt.
2. Schema Generation & Model Inference (Chamada ao modelo): Os tipos dos argumentos das ferramentas e o ResultType final são convertidos em schemas JSON rigorosos através do motor Pydantic Core (escrito em Rust, garantindo velocidade na ordem de microssegundos).
3. Tool Invocation with Self-Correction (Validação e correção): Quando o modelo retorna uma chamada de ferramenta, os argumentos de entrada passam pelo validador Pydantic. Se a validação falhar (por exemplo, se um número negativo for passado onde se espera PositiveInt), o PydanticAI não lança uma exceção; em vez disso, envia automaticamente uma mensagem ao modelo: «Erro de validação no campo X: esperava-se valor > 0. Tente novamente».
4. Structured Output Serialization & Streaming (Retorno do resultado): A resposta final é desserializada para o objeto Python alvo. O método run_stream() é suportado, permitindo transmitir campos parcialmente formados do objeto ao cliente em tempo real.

4. Cenários de engenharia prática em produção

01. Agentes nativos dentro do FastAPI

Reuso de modelos: o mesmo schema InvoiceExtractionResponse é usado como schema de saída do PydanticAI, como response_model no endpoint do FastAPI e para a geração automática de tipos TypeScript do cliente via OpenAPI.

02. Operação segura com transações de banco de dados

Através do RunContext, a sessão transacional AsyncSession do SQLAlchemy é injetada nas ferramentas. O agente pode realizar verificações e gravar dados. Se ocorrer um erro na etapa final, o gerenciador de contexto externo faz o rollback da transação, evitando a persistência de dados incompletos.

03. Streaming de interfaces estruturadas (Generative UI)

O agente gera um dashboard dinâmico. Graças ao suporte à validação de stream do PydanticAI, o frontend pode renderizar gráficos e cartões antes mesmo de o modelo terminar de formar o documento JSON completo.

5. Armadilhas, erros comuns e segurança

• Ausência de descrições de campos (Field(description=...)): O modelo constrói a chamada baseando-se exclusivamente nos nomes e descrições dos campos. Se um campo tiver um nome ambíguo (por exemplo, status: int) e não houver descrição, o modelo tenderá a alucinar valores incorretos.
• Esgotamento das tentativas de correção de erros (Max Retries Exceeded): Se o schema for excessivamente complexo, o modelo pode esgotar o limite de retries=3 tentando ajustar a resposta ao validador, resultando na falha da requisição. Simplifique os schemas ou decomponha-os em subtarefas.
• Vazamento do ciclo de vida de recursos em Deps: Certifique-se de que os objetos passados em deps (pools de conexão, clientes HTTP) sejam corretamente fechados após a conclusão da operação do agente (utilizando async with).