Início/Tutoriais/Seu primeiro agente IA com PydanticAI

Guía Paso a PasoNivel: Iniciante25 minsPydanticAI22 de março de 2026

Seu primeiro agente IA com PydanticAI

Crie seu primeiro agente IA com PydanticAI em Python. Tutorial passo a passo com saídas estruturadas, chamada de ferramentas e código funcional.

Se você já quis criar um agente de inteligência artificial em Python, mas achou que as ferramentas eram complicadas demais ou cheias de abstrações desnecessárias, PydanticAI será seu novo framework favorito. É simples, tipado e construído pela mesma equipe por trás do Pydantic — a biblioteca de validação que já é utilizada por 90% do ecossistema Python moderno.

Neste tutorial, você vai construir um agente IA com PydanticAI que analisa textos e retorna respostas estruturadas (saídas estruturadas) usando ferramentas personalizadas (chamada de ferramentas). Tudo em menos de 150 linhas de Python, sem mágica, com tipos estritos de ponta a ponta.

Este tutorial é para você se você sabe o básico de Python e quer dar seu primeiro passo no mundo dos agentes de IA. Você não precisa de experiência prévia com LLMs ou frameworks de agentes.

Requisitos prévios:

Python 3.12 ou superior
API key da OpenAI (obtenha a sua aqui) — PydanticAI também suporta Anthropic e Gemini
Conhecimentos básicos de Python (funções, classes, async/await)
uv instalado como gerenciador de pacotes (instalação)

Instalação e configuração do projeto

Primeiro, clone o repositório de tutoriais do khoal.ai e navegue até este tutorial:

bash

git clone https://github.com/khoalai/khoal-ai-tutorials.git
cd khoal-ai-tutorials/tutorials/01-pydanticai-first-agent

Instale as dependências com uv:

bash

uv sync

Isso instala pydantic-ai e python-dotenv automaticamente. Agora configure sua API key:

bash

cp ../../.env.example .env

Abra o arquivo .env e substitua o placeholder pela sua chave real da OpenAI:

bash

OPENAI_API_KEY=sk-sua-chave-real-aqui

Nunca comite seu arquivo .env. Ele já está incluído em .gitignore, mas sempre verifique antes de fazer push. As API keys expostas podem gerar custos inesperados na sua conta.

PydanticAI é agnóstico em relação ao modelo: se você preferir usar Anthropic ou Gemini, basta trocar o modelo no código e usar a chave da API correspondente. Vamos usar gpt-4o-mini porque é econômico e rápido — ideal para experimentar sem gastar demais.

Definir a estrutura de resposta (Saída Estruturada)

A grande vantagem do PydanticAI é que você pode dizer ao agente exatamente qual forma sua resposta deve ter. Em vez de receber texto livre e torcer para que o formato esteja correto, você define um modelo Pydantic e o framework cuida do resto.

python

from pydantic import BaseModel, Field

class AnaliseTexto(BaseModel):
    """Estrutura para a análise de um texto."""

    resumo: str = Field(description="Resumo conciso do texto em 1-2 frases")
    idioma: str = Field(description="Idioma detectado do texto")
    sentimento: str = Field(description="Sentimento geral: positivo, negativo ou neutro")
    temas: list[str] = Field(description="Lista de temas principais identificados")
    quantidade_palavras: int = Field(description="Quantidade aproximada de palavras no texto")

Cada campo usa Field(description=...) para que o LLM entenda o que se espera. Isso funciona como documentação para a IA — quanto mais claro você for nas descrições, melhores resultados você obterá.

As saídas estruturadas eliminam a necessidade de analisar texto livre com regex ou hacks similares. O PydanticAI valida automaticamente se a resposta do LLM atende ao seu esquema e reitera se não atender.

Criar o agente com dependências

Agora vamos criar o agente. No PydanticAI, um agente combina três coisas: um modelo de IA, um prompt do sistema e, opcionalmente, um tipo de resultado estruturado.

Primeiro, definimos as dependências — dados de contexto que o agente e suas ferramentas podem compartilhar:

python

from dataclasses import dataclass

@dataclass
class DependenciasAgente:
    """Contexto compartilhado entre o agente e suas ferramentas."""
    nome_usuario: str
    modo_detalhado: bool = False

Em seguida, criamos o agente propriamente dito:

python

from pydantic_ai import Agent

agente_analista = Agent(
    model="openai:gpt-4o-mini",
    result_type=AnaliseTexto,
    system_prompt=(
        "Você é um analista de textos experiente. Seu trabalho é analisar textos 
        e devolver uma análise estruturada com resumo, idioma, sentimento, 
        temas principais e quantidade de palavras. 
        Responda sempre em espanhol."
    ),
    deps_type=DependenciasAgente,
)

Note que com result_type=AnaliseTexto estamos dizendo ao agente que sua resposta sempre deve ser um objeto AnaliseTexto válido. Se o LLM retornar algo que não corresponde ao esquema, o PydanticAI tentará novamente automaticamente.

Adicionar ferramentas (Chamada de Ferramentas)

As ferramentas (tools) são funções Python que o agente pode decidir usar durante seu raciocínio. Você as define e o LLM escolhe quando chamá-las.

python

from pydantic_ai import RunContext

@agente_analista.tool
async def contar_caracteres(ctx: RunContext[DependenciasAgente], texto: str) -> str:
    """Conta os caracteres de um texto (sem espaços e com espaços)."""
    sem_espacos = len(texto.replace(" ", ""))
    com_espacos = len(texto)

    resultado = (
        f"📊 Caracteres com espaços: {com_espacos}\n"
        f"📊 Caracteres sem espaços: {sem_espacos}"
    )

    # Acessamos as dependências através do contexto
    if ctx.deps.modo_detalhado:
        resultado += f"\n📊 Espaços: {com_espacos - sem_espacos}"

    return resultado

Pontos-chave da chamada de ferramentas no PydanticAI:

O decorador @agente_analista.tool registra a função como uma ferramenta disponível.
O docstring da função é o que o LLM lê para decidir se deve usá-la — escreva de forma clara e descritiva.
O primeiro argumento ctx: RunContext[DependenciasAgente] fornece acesso às dependências que você configurou.
O agente decide autonomamente se a ferramenta é útil para a tarefa atual.

A chamada de ferramentas é o que diferencia um agente de um simples chatbot. Um chatbot apenas gera texto; um agente pode executar ações reais — consultar bancos de dados, chamar APIs, fazer cálculos, o que você precisar.

Executar o agente e ver os resultados

Finalmente, executamos o agente com asyncio:

python


async def main() -> None:
    texto = (
        "A inteligência artificial generativa continua revolucionando "
        "a indústria de software. Empresas de todo o mundo estão "
        "adotando modelos de linguagem para automatizar tarefas."
    )

    deps = DependenciasAgente(nome_usuario="Developer", modo_detalhado=True)

    resultado = await agente_analista.run(
        f"Analise o seguinte texto:\n\n{texto}",
        deps=deps,
    )

    # resultado.data é uma AnaliseTexto tipada ✨
    analise = resultado.data
    print(f"📋 Resumo:     {analise.resumo}")
    print(f"🌐 Idioma:      {analise.idioma}")
    print(f"💭 Sentimento: {analise.sentimento}")
    print(f"🏷️  Temas:       {', '.join(analise.temas)}")
    print(f"📏 Palavras:    ~{analise.quantidade_palavras}")

asyncio.run(main())

Execute o programa:

bash

uv run python main.py

Você deverá ver algo como isso:

text

══════════════════════════════════════════════════════════
🐨 khoal.ai — Seu primeiro agente IA com PydanticAI
══════════════════════════════════════════════════════════

──────────────────────────────────────────────────────────
📝 Exemplo 1: Notícia tecnológica
──────────────────────────────────────────────────────────

📋 Resumo:     A IA generativa está transformando a indústria de software...
🌐 Idioma:      Espanhol
💭 Sentimento: Positivo
🏷️  Temas:       IA generativa, software, América Latina, código aberto
📏 Palavras:    ~52

✅ Análise concluída!

[IMAGEM: Captura de terminal mostrando a saída completa do programa com as duas análises de texto, emoji e cores do terminal]

Os resultados exatos podem variar entre execuções porque os LLMs são probabilísticos. O resumo e os temas podem mudar ligeiramente, mas a estrutura sempre será a mesma graças à saída estruturada.

💡 Por que importa

PydanticAI resolve um problema real que temos os desenvolvedores Python: construir agentes de IA com segurança de tipos e sem as camadas de abstração desnecessárias que outros frameworks arrastam. Se você já usa Pydantic (e se trabalha com FastAPI, certamente sim), o PydanticAI se sente como uma extensão natural do seu stack.

As saídas estruturadas mudam as regras do jogo. Em vez de receber texto livre e torcer para que o modelo responda no formato correto, você define exatamente o que quer e o PydanticAI cuida para que o LLM cumpra. Isso é fundamental quando você está construindo aplicações reais onde precisa de dados consistentes para alimentar sua lógica de negócios.

E a chamada de ferramentas é a peça que transforma um LLM de um "gerador de texto sofisticado" em um agente capaz de interagir com o mundo real — consultar APIs, buscar em bancos de dados, executar código. O padrão que você aprendeu neste tutorial é o mesmo que você usará para construir agentes mais complexos.

Próximos passos

Agora que você tem seu primeiro agente funcionando, você pode:

Trocar de modelo: Experimente com anthropic:claude-sonnet-4-20250514 ou google-gla:gemini-2.0-flash — basta mudar uma linha.
Adicionar mais ferramentas: Conecte seu agente a APIs externas, bancos de dados ou serviços de busca.
Encadear agentes: Use a saída de um agente como entrada de outro para criar fluxos mais complexos.

Encontre o código completo deste e todos os tutoriais no repositório do GitHub.

O que amamos

●Type-safe de ponta a ponta com Pydantic
●Model-agnostic: OpenAI, Anthropic, Gemini com uma única mudança
●Chamada de ferramentas integrada com decoradores simples
●Validação e reiterações automáticas de saídas estruturadas

O que precisa melhorar

●Framework relativamente novo — comunidade ainda em crescimento
●Documentação apenas em inglês por enquanto