PydanticAI — Agentes de IA Tipados em Python

Visão Geral

PydanticAI é um framework de agentes em Python da equipe Pydantic que traz a mesma segurança de tipo e garantias de validação do Pydantic para aplicações baseadas em LLM. Ele suporta saídas estruturadas (validadas com modelos Pydantic), injeção de dependência para testabilidade, respostas em streaming, conversas multi-turn e uso de ferramentas — em OpenAI, Anthropic, Google Gemini, Groq, Mistral e Ollama. Use esta habilidade ao construir agentes de IA de produção, chatbots ou pipelines de LLM onde a correção e a testabilidade importam.

Quando Usar Esta Habilidade

• Use ao construir agentes de IA em Python que chamam ferramentas e retornam dados estruturados
• Use quando precisar de saídas de LLM validadas e tipadas (não strings brutas)
• Use quando quiser escrever testes unitários para a lógica do agente sem chamar um LLM real
• Use ao alternar entre provedores de LLM sem reescrever o código do agente
• Use quando o usuário perguntar sobre Agent, @agent.tool, RunContext, ModelRetry, ou result_type

Como Funciona

Passo 1: Instalação

pip install pydantic-ai

# Install extras for specific providers
pip install 'pydantic-ai[openai]'       # OpenAI / Azure OpenAI
pip install 'pydantic-ai[anthropic]'    # Anthropic Claude
pip install 'pydantic-ai[gemini]'       # Google Gemini
pip install 'pydantic-ai[groq]'         # Groq
pip install 'pydantic-ai[vertexai]'     # Google Vertex AI

Passo 2: Um Agente Mínimo

from pydantic_ai import Agent

# Simple agent — returns a plain string
agent = Agent(
    'anthropic:claude-sonnet-4-6',
    system_prompt='You are a helpful assistant. Be concise.',
)

result = agent.run_sync('What is the capital of Japan?')
print(result.data)  # "Tokyo"
print(result.usage())  # Usage(requests=1, request_tokens=..., response_tokens=...)

Passo 3: Saída Estruturada com Modelos Pydantic

from pydantic import BaseModel
from pydantic_ai import Agent

class MovieReview(BaseModel):
    title: str
    year: int
    rating: float  # 0.0 to 10.0
    summary: str
    recommended: bool

agent = Agent(
    'openai:gpt-4o',
    result_type=MovieReview,
    system_prompt='You are a film critic. Return structured reviews.',
)

result = agent.run_sync('Review Inception (2010)')
review = result.data  # Fully typed MovieReview instance
print(f"{review.title} ({review.year}): {review.rating}/10")
print(f"Recommended: {review.recommended}")

Passo 4: Uso de Ferramentas

Registre ferramentas com @agent.tool — o LLM pode chamá-las durante uma execução:

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

class WeatherReport(BaseModel):
    city: str
    temperature_c: float
    condition: str

weather_agent = Agent(
    'anthropic:claude-sonnet-4-6',
    result_type=WeatherReport,
    system_prompt='Get current weather for the requested city.',
)

@weather_agent.tool
async def get_temperature(ctx: RunContext, city: str) -> dict:
    """Fetch the current temperature for a city from the weather API."""
    async with httpx.AsyncClient() as client:
        r = await client.get(f'https://wttr.in/{city}?format=j1')
        data = r.json()
        return {
            'temp_c': float(data['current_condition'][0]['temp_C']),
            'description': data['current_condition'][0]['weatherDesc'][0]['value'],
        }

import asyncio
result = asyncio.run(weather_agent.run('What is the weather in Tokyo?'))
print(result.data)

Passo 5: Injeção de Dependência

Injete serviços (banco de dados, clientes HTTP, configuração) em agentes para testabilidade:

from dataclasses import dataclass
from pydantic_ai import Agent, RunContext
from pydantic import BaseModel

@dataclass
class Deps:
    db: Database
    user_id: str

class SupportResponse(BaseModel):
    message: str
    escalate: bool

support_agent = Agent(
    'openai:gpt-4o-mini',
    deps_type=Deps,
    result_type=SupportResponse,
    system_prompt='Você é um agente de suporte. Use as ferramentas para ajudar os clientes.',
)

@support_agent.tool
async def get_order_history(ctx: RunContext[Deps]) -> list[dict]:
    """Busca pedidos recentes para o usuário atual."""
    return await ctx.deps.db.get_orders(ctx.deps.user_id, limit=5)

@support_agent.tool
async def create_refund(ctx: RunContext[Deps], order_id: str, reason: str) -> dict:
    """Inicia um reembolso para um pedido específico."""
    return await ctx.deps.db.create_refund(order_id, reason, ctx.deps.user_id)

# Uso
async def handle_support(user_id: str, message: str):

…