Redação YTI&W-News
Introdução ao Pydantic AI 🤖
Pydantic AI é um framework Python para construir agentes de LLM (Large Language Models) que retornam saídas validadas e estruturadas usando modelos Pydantic. Em vez de parsear strings brutos de LLMs, você obtém objetos de tipo seguro com validação automática.
Definindo Saídas Estruturadas com Pydantic Models
Pydantic AI usa classes BaseModel para definir saídas estruturadas que garantem segurança de tipo e validação automática. Você pode definir um modelo Pydantic para especificar a estrutura da saída do agente, e o framework garantirá que a saída seja validada contra esse modelo.
from pydantic import BaseModel
class CityInfo(BaseModel):
name: str
country: str
population: int
fun_fact: str
Registrando Ferramentas com o Decorador @agent.tool
O decorador @agent.tool registra funções Python que os LLMs podem invocar com base em consultas de usuário e docstrings. Você pode registrar funções como ferramentas que o agente pode usar para realizar ações específicas.
from pydantic_ai import Agent
import requests
agent = Agent(
"google-gla:gemini-2.5-flash",
instructions="Ajude os usuários com raças de gatos. Seja conciso.",
)
@agent.tool_plain
def find_breed_info(breed_name: str) -> dict:
"""Encontre informações sobre uma raça de gato."""
response = requests.get("https://api.thecatapi.com/v1/breeds")
response.raise_for_status()
json_response = response.json()
for breed in json_response:
if breed["name"] == breed_name:
return breed
return {"error": "Raça não encontrada"}
Injetando Dependências com Type Safety
Pydantic AI fornece um padrão de injeção de dependência com type safety, permitindo que você passe um contexto de execução (RunContext) para os agentes e ferramentas.
from pydantic import BaseModel
from pydantic_ai import Agent, RunContext
import requests
class UserDatabase:
"""Simule um banco de dados de usuários usando a API JSONPlaceholder."""
_base_url = "https://jsonplaceholder.typicode.com"
def get_user_info(self, user_id: int) -> dict:
response = requests.get(f"{self._base_url}/users/{user_id}")
response.raise_for_status()
return response.json()
class UserSummary(BaseModel):
name: str
email: str
company: str
agent = Agent(
"google-gla:gemini-2.5-flash",
output_type=UserSummary,
deps_type=UserDatabase,
instructions=(
"Você recupera informações de usuário de um banco de dado externo. "
"Use as ferramentas disponíveis para coletar informações de usuário, "
"em seguida, retorne um resumo estruturado."
),
)
@agent.tool
def fetch_user(ctx: RunContext[UserDatabase], user_id: int) -> str:
"""Recupere o perfil do usuário do serviço."""
try:
user = ctx.deps.get_user_info(user_id)
return str(user)
except requests.HTTPError as e:
return f"Usuário com ID {user_id} não encontrado: {e}"
Instalando e Configurando o Pydantic AI
Requisitos e Instalação
Para começar a usar o Pydantic AI, você precisará instalar a biblioteca e configurá-la com um provedor de IA e uma chave de API.
pip install pydanticConfigurando o Provedor de IA e a Chave de API
Após a instalação, você precisará configurar o Pydantic AI com um provedor de IA e uma chave de API.
import os
os.environ['GOOGLE_API_KEY'] = 'sua_chave_de_api_aqui'
Definindo Modelos Pydantic para Saídas Estruturadas 📊
Os modelos Pydantic são fundamentais para criar agentes de IA que produzem saídas estruturadas e validadas.
from pydantic import BaseModel
class CityInfo(BaseModel):
name: str
country: str
population: int
fun_fact: str
Registrando Ferramentas com @agent.tool e @agent.tool_plain 🛠️
Decoradores para Chamadas de Funções
Os decoradores @agent.tool e @agent.tool_plain são usados para registrar ferramentas que os agentes de IA podem invocar.
from pydantic_ai import Agent
import requests
agent = Agent(
"google-gla:gemini-2.5-flash",
instructions="Help users with cat breeds. Be concise.",
)
@agent.tool_plain
def find_breed_info(breed_name: str) -> dict:
"""Find information about a cat breed."""
response = requests.get("https://api.thecatapi.com/v1/breeds")
response.raise_for_status()
json_response = response.json()
for breed in json_response:
if breed["name"] == breed_name:
return breed
return {"error": "Breed not found"}
Injetando Dependências de Tempo de Execução com Segurança de Tipo 📈
Visão Geral da Injeção de Dependência
A injeção de dependência é uma técnica de design de software que permite que os componentes de um sistema sejam desacoplados.
from pydantic import BaseModel
from pydantic_ai import Agent, RunContext
class UserDatabase:
def get_user_info(self, user_id: int) -> dict:
# Simula uma consulta a um banco de dados
return {"name": "João", "email": "joao@example.com"}
class UserSummary(BaseModel):
name: str
email: str
agent = Agent(
"google-gla:gemini-2.5-flash",
output_type=UserSummary,
deps_type=UserDatabase,
instructions="Retorne as informações do usuário.",
)
@agent.tool
def fetch_user(ctx: RunContext[UserDatabase], user_id: int) -> str:
user = ctx.deps.get_user_info(user_id)
return str(user)
Considerações sobre Custo de Tokens, Latência e Recursos do Provedor 📊
Custo de Tokens e Limitações
O custo de tokens é um fator importante a ser considerado ao usar o Pydantic AI em produção.
import requests
from pydantic import BaseModel
from typing import Optional
class Agent:
def __init__(self, model: str, instructions: str):
self.model = model
self.instructions = instructions
def run_sync(self, prompt: str):
class Result:
def __init__(self, token_cost: int):
self.token_cost = token_cost
# Simulação da execução do modelo
token_cost = len(prompt) * 2 # Custo de tokens fictício
return Result(token_cost)
Conclusão e Próximos Passos 🚀
Neste artigo, exploramos como o Pydantic AI pode ser utilizado para criar agentes de linguagem natural que retornam saídas estruturadas e validadas.
Próximos Passos
Agora que você tem uma base sólida em Pydantic AI, é hora de explorar mais a fundo as funcionalidades e recursos disponíveis.
import pydantic
from pydantic import BaseModel
class Agent(BaseModel):
pass
class RunContext(BaseModel):
pass
Para continuar aprendendo e aprimorando suas habilidades com Pydantic AI, é recomendado explorar os seguintes recursos:
from pydantic import BaseModel
Alguns próximos passos incluem:
- Aprender mais sobre os modelos Pydantic e como utilizá-los para criar saídas estruturadas complexas.
- Explorar as funcionalidades de registro de ferramentas e como utilizá-las para criar agentes mais avançados.
- Aprender a injetar dependências de tempo de execução com segurança de tipo e como utilizá-las para criar agentes mais escaláveis.
- Considerar os custos de tokens, latência e recursos do provedor e como otimizar o desempenho do agente.
Fonte: realpython.com.
Curadoria e Insights: Redação YTI&W (Developers).
Redação YTI&W-News
Notícias do universo do Desenvolvimento Web, dicas e tutoriais para Webmasters.
- Implemente um Token Bucket Eficiente em FastAPI 29 de março de 2026
- Oxc: A Revolução nos Ferramentas de Desenvolvimento 28 de março de 2026
- Exporte AI com Fluxo de Trabalho Personalizado 27 de março de 2026
- Dominando Dapper: A Micro-ORM para Desempenho 26 de março de 2026
- OpenClaw: Automação de Navegador com IA e Controle Total 25 de março de 2026
