Pydantic AI

Pydantic AI: O Framework de Agentes GenAI

Pydantic AI é um framework de agentes Python criado para facilitar a construção rápida, confiável e integrada de aplicações e fluxos de trabalho de nível de produção, aproveitando a IA Generativa. Ele visa trazer o design ergonômico do FastAPI para o desenvolvimento de aplicações e agentes GenAI.

O que é Pydantic AI?

Pydantic AI é uma ferramenta projetada para ajudar desenvolvedores a construir aplicações com IA Generativa de forma rápida e eficiente. Ele aproveita a Validação Pydantic e recursos modernos do Python para fornecer uma experiência de desenvolvimento tranquila.

Principais Características:

• Construído pela Equipe Pydantic: Acesso direto ao código-fonte da Validação Pydantic, que é usada em muitos SDKs de IA populares.
• Agnóstico ao Modelo: Suporta uma ampla gama de modelos e provedores, incluindo OpenAI, Anthropic, Gemini e muito mais. Modelos personalizados também podem ser implementados facilmente.
• Observabilidade Integrada: Integra-se com o Pydantic Logfire para depuração em tempo real, monitoramento de desempenho e rastreamento de custos. Também suporta outras plataformas compatíveis com OpenTelemetry.
• Totalmente Type-safe: Projetado para fornecer contexto abrangente para autocompletar e verificação de tipo, reduzindo erros de tempo de execução.
• Avaliações Poderosas: Permite testes e avaliação sistemáticos do desempenho e precisão do agente.
• MCP, A2A e AG-UI: Integra padrões para acesso do agente a ferramentas e dados externos, interoperabilidade com outros agentes e construção de aplicações interativas.
• Aprovação de Ferramentas com Interação Humana: Permite sinalizar chamadas de ferramentas que exigem aprovação antes da execução.
• Execução Durável: Permite construir agentes que podem manter o progresso em caso de falhas de API e reinicializações da aplicação.
• Saídas Transmitidas: Fornece transmissão contínua de saída estruturada com validação imediata.
• Suporte a Grafos: Oferece uma maneira poderosa de definir grafos usando dicas de tipo para aplicações complexas.

Como o Pydantic AI funciona?

Pydantic AI funciona fornecendo um framework que simplifica o desenvolvimento de agentes de IA. Ele usa modelos Pydantic para definir a estrutura das entradas e saídas do agente e fornece ferramentas para conectar o agente a vários LLMs e outros serviços.

Como usar o Pydantic AI?

1. Instalação: Instale o pacote pydantic_ai.

2. Uso Básico: Crie uma instância Agent com o modelo e as instruções especificadas.

   from pydantic_ai import Agent
   
   agent = Agent(
       'anthropic:claude-sonnet-4-0',
       instructions='Seja conciso, responda com uma frase.',
   )
   
   result = agent.run_sync('De onde vem "hello world"?')
   print(result.output)
   """
   

O primeiro uso conhecido de "hello, world" foi em um livro didático de 1974 sobre a linguagem de programação C. """ ```

3. Uso Avançado: Adicione ferramentas, instruções dinâmicas e saídas estruturadas para construir agentes mais poderosos.

Para quem é o Pydantic AI?

Pydantic AI é ideal para:

• Desenvolvedores que desejam construir aplicações e fluxos de trabalho GenAI de forma eficiente.
• Equipes que exigem agentes de IA robustos, type-safe e observáveis.
• Projetos que precisam se integrar com vários LLMs e serviços.

Exemplo de Ferramentas e Injeção de Dependência

Pydantic AI facilita a injeção de dependência, o que é útil quando você precisa injetar dados ou serviços em suas ferramentas. Você pode definir sua classe de dependência e passá-la para o agente. Abaixo está o código de exemplo construindo um agente de suporte para um banco com Pydantic AI:

from dataclasses import dataclass

from pydantic import BaseModel, Field
from pydantic_ai import Agent, RunContext

from bank_database import DatabaseConn


@dataclass
class SupportDependencies:
    customer_id: int
    db: DatabaseConn


class SupportOutput(BaseModel):
    support_advice: str = Field(description='Conselho retornado ao cliente')
    block_card: bool = Field(description='Se deve bloquear o cartão do cliente')
    risk: int = Field(description='Nível de risco da consulta', ge=0, le=10)


support_agent = Agent(
    'openai:gpt-5',
    deps_type=SupportDependencies,
    output_type=SupportOutput,
    instructions=(
        'Você é um agente de suporte em nosso banco, dê o '
        'suporte ao cliente e julgue o nível de risco de sua consulta.'
    ),
)


@support_agent.instructions
async def add_customer_name(ctx: RunContext[SupportDependencies]) -> str:
    customer_name = await ctx.deps.db.customer_name(id=ctx.deps.customer_id)
    return f"O nome do cliente é {customer_name!r}"


@support_agent.tool
async def customer_balance(
    ctx: RunContext[SupportDependencies], include_pending: bool
) -> float:
    """Retorna o saldo atual da conta do cliente."""
    return await ctx.deps.db.customer_balance(
        id=ctx.deps.customer_id,
        include_pending=include_pending,
    )

Instrumentação com Pydantic Logfire

Para monitorar agentes em ação, o Pydantic AI se integra perfeitamente com o Pydantic Logfire, a plataforma de observabilidade OpenTelemetry, que permite depuração em tempo real, monitoramento de desempenho baseado em avaliações e rastreamento de comportamento, rastreamento e custos. O código de exemplo:

...from pydantic_ai import Agent, RunContext
from bank_database import DatabaseConn
import logfire

logfire.configure()
logfire.instrument_pydantic_ai()
logfire.instrument_asyncpg()
...support_agent = Agent(
    'openai:gpt-4o',
    deps_type=SupportDependencies,
    output_type=SupportOutput,
    system_prompt=(
        'Você é um agente de suporte em nosso banco, dê o '
        'suporte ao cliente e julgue o nível de risco de sua consulta.'
    ),
)

Por que escolher o Pydantic AI?

Pydantic AI oferece uma abordagem simplificada para construir aplicações GenAI. Sua base na Validação Pydantic, design agnóstico ao modelo, observabilidade integrada e ambiente type-safe o tornam uma escolha atraente para desenvolvedores que buscam eficiência e confiabilidade.

Próximos Passos

Para explorar o Pydantic AI mais a fundo:

• Instale o Pydantic AI e siga os exemplos.
• Consulte a documentação para um entendimento mais profundo.
• Verifique a Referência da API para entender a interface do Pydantic AI.
• Junte-se ao canal do Slack ou registre um problema no GitHub para quaisquer perguntas.