🔩 O agente mínimo viável
Antes de qualquer código, defina o mínimo necessário para chamar algo de agente. Se faltar qualquer um desses 5 componentes, você tem uma função, um chatbot ou um script — mas não um agente.
🔩 Os 5 elementos obrigatórios
LLM
O modelo que raciocina e decide as ações
Tools
Pelo menos uma ação real no mundo externo
Loop
Execução repetida até condição de parada
Observação
Resultado da tool injetado de volta no contexto
Stop Condition
Critério claro para saber quando parou
📋 O que NÃO é obrigatório no MVP
Pode adicionar depois:
- ○Memória longa (RAG) — ótimo, mas não obrigatório
- ○Planejamento sofisticado — comece linear
- ○Framework (LangChain etc.) — desnecessário no início
- ○Interface gráfica — terminal é suficiente para validar
Já inclua no MVP:
- ✓max_iterations — evita loop infinito
- ✓Print de cada ação — visibilidade do loop
- ✓Try/except nos tool calls — falha graciosa
- ✓Contagem de tokens — consciência de custo
🛠️ Definindo tools em Python
Uma tool é uma função Python com um JSON schema bem descrito. O schema é o contrato entre o LLM e o código — ele diz ao modelo o que a função faz, quais parâmetros aceita e como chamá-la.
📋 Exemplo: 3 tools para um agente de pesquisa
# As tools como JSON schema (o que o modelo vê)
tools = [
{
"name": "search_web",
"description": "Busca informações na web. Use quando precisar de dados atuais ou específicos que não estão no seu conhecimento base. Retorna título, URL e snippet dos resultados.",
"input_schema": {
"type": "object",
"properties": {
"query": {"type": "string", "description": "Termo de busca"},
"num_results": {"type": "integer", "default": 5}
},
"required": ["query"]
}
},
{
"name": "save_result",
"description": "Salva um resultado de pesquisa em arquivo markdown. Use APENAS quando tiver informação suficiente para gerar o relatório final.",
"input_schema": {
"type": "object",
"properties": {
"filename": {"type": "string"},
"content": {"type": "string"}
},
"required": ["filename", "content"]
}
}
]
💡 As 3 regras de ouro para descriptions
Descreva o quando usar — "Use quando precisar de dados atuais" orienta melhor que "Busca na web"
Descreva o quando NÃO usar — evita que o modelo abuse de tools de alto custo
Descreva o que retorna — "Retorna título, URL e snippet" ajuda o modelo a saber o que esperar
🔁 O loop de execução em código
O loop é o coração do agente. Em Python com o SDK da Anthropic, o padrão é direto: enquanto o modelo retornar tool_use, execute a tool e adicione o resultado ao contexto. Quando retornar end_turn, você terminou.
🔁 O loop completo comentado
import anthropic
client = anthropic.Anthropic()
# Estado inicial
messages = [{"role": "user", "content": objetivo}]
iteration = 0
while iteration < MAX_ITERATIONS:
iteration += 1
print(f"--- Iteração {iteration} ---")
# 1. PENSAR: chamar o modelo com o contexto atual
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=4096,
tools=tools,
messages=messages
)
# 2. AVALIAR: verificar condição de parada
if response.stop_reason == "end_turn":
print("Agente concluiu a tarefa!")
break
# 3. AGIR: executar tools retornadas
tool_results = []
for block in response.content:
if block.type == "tool_use":
print(f"Chamando tool: {block.name}")
result = dispatch_tool(block.name, block.input)
tool_results.append({
"type": "tool_result",
"tool_use_id": block.id,
"content": str(result)
})
# 4. OBSERVAR: adicionar resultados ao contexto
messages.append({"role": "assistant", "content": response.content})
messages.append({"role": "user", "content": tool_results})
else:
print(f"Limite de {MAX_ITERATIONS} iterações atingido")
📊 A função dispatch_tool: roteador de actions
def dispatch_tool(name: str, inputs: dict) -> str:
"""Executa a tool correta baseado no nome"""
try:
if name == "search_web":
return search_web(**inputs)
elif name == "save_result":
return save_result(**inputs)
else:
return f"Erro: tool '{name}' não encontrada"
except Exception as e:
return f"Erro ao executar {name}: {str(e)}"
O dispatch sempre retorna string — nunca propaga exceção. O agente recebe o erro e pode decidir o que fazer com ele.
🧪 Exercício: agente de pesquisa em ~50 linhas
Chegou a hora. Você vai construir um agente de pesquisa completo. Ele recebe um tema, busca na web, sintetiza os resultados e salva um relatório markdown. Custo total estimado: menos de $0.05.
📋 agent_pesquisa.py — versão completa
~52 linhasimport anthropic, json, requests
from pathlib import Path
### CONFIGURAÇÃO ###
client = anthropic.Anthropic()
MAX_ITERATIONS = 10
### IMPLEMENTAÇÃO DAS TOOLS ###
def search_web(query: str, num_results: int = 5) -> str:
"""Simula busca web — troque por API real (Serper, Brave, etc)"""
return json.dumps([{
"title": f"Resultado {i+1} para: {query}",
"snippet": f"Conteúdo relevante sobre {query} — resultado {i+1}",
"url": f"https://example.com/{i+1}"
} for i in range(num_results)])
def save_result(filename: str, content: str) -> str:
Path(filename).write_text(content, encoding="utf-8")
return f"Arquivo '{filename}' salvo com sucesso ({len(content)} chars)"
### SCHEMA DAS TOOLS ###
tools = [
{"name": "search_web", "description": "Busca info na web. Use para coletar dados sobre o tema.", "input_schema": {"type": "object", "properties": {"query": {"type": "string"}, "num_results": {"type": "integer", "default": 5}}, "required": ["query"]}},
{"name": "save_result", "description": "Salva relatório em arquivo .md. Use APENAS quando tiver informação suficiente para o relatório final.", "input_schema": {"type": "object", "properties": {"filename": {"type": "string"}, "content": {"type": "string"}}, "required": ["filename", "content"]}}
]
### LOOP AGENTIC ###
def run_agent(objetivo: str):
messages = [{"role": "user", "content": objetivo}]
total_tokens = 0
for iteration in range(1, MAX_ITERATIONS + 1):
print(f"\n--- Iteração {iteration} ---")
response = client.messages.create(model="claude-haiku-20240307", max_tokens=2048, tools=tools, messages=messages)
total_tokens += response.usage.input_tokens + response.usage.output_tokens
if response.stop_reason == "end_turn": print(f"Concluído! Total: {total_tokens} tokens"); break
tool_results = []
for block in response.content:
if block.type == "tool_use":
print(f"Tool: {block.name}({block.input})")
result = search_web(**block.input) if block.name == "search_web" else save_result(**block.input)
tool_results.append({"type": "tool_result", "tool_use_id": block.id, "content": result})
messages += [{"role": "assistant", "content": response.content}, {"role": "user", "content": tool_results}]
return total_tokens
if __name__ == "__main__":
run_agent("Pesquise os principais frameworks de agentes de IA em 2026 e salve um relatório em relatorio_frameworks.md")
💡 Para executar
Troque a função search_web por uma chamada real à Serper API, Brave Search ou DuckDuckGo para resultados reais.
💥 Quebre o agente de propósito
A forma mais rápida de entender profundamente um sistema é quebrá-lo com intenção. Cada experimento abaixo vai revelar um comportamento específico que você precisa conhecer antes de ir para produção.
Experimento 1: Sem max_iterations
Remova o limite de iterações. Dê um objetivo impossível de atingir ("Pesquise TODOS os artigos sobre IA de 2024"). Observe o que acontece.
O que você vai aprender:
O agente entra em loop, gasta tokens indefinidamente, custo sobe sem parar. Isso torna max_iterations inegociável, não opcional.
Experimento 2: Schema errado na tool
Mude o type de "query" de "string" para "integer" no schema. Observe o que o modelo faz ao tentar chamar a tool.
O que você vai aprender:
O modelo pode tentar chamar com o tipo errado. A tool falha. Com um bom error handler, o agente tenta novamente ou adapta. Com handler ruim, o agente entra em estado inconsistente.
Experimento 3: Tool que sempre falha
Faça a search_web lançar uma exceção sempre. Veja quantas vezes o agente tenta antes de desistir.
O que você vai aprender:
Sem circuit breaker, o agente tenta repetidamente. Com erro estruturado no retorno, o agente consegue replanejar. A diferença entre "throw exception" e "return error string" é crítica.
Experimento 4: Objetivo ambíguo
Mude o objetivo para "Faça o melhor possível". Observe: o agente para, pede clarificação ou inventa um objetivo?
O que você vai aprender:
Objetivos ambíguos fazem o agente inventar critérios de sucesso. Às vezes isso é OK (agente proativo), às vezes é perigoso (agente decide o que "melhor" significa sem seu input).
🎓 Por que quebrar de propósito é o melhor treinamento
Cada quebra te dá uma intuição visceral do risco — não teórica, mas vivida. Depois desses 4 experimentos, você nunca mais vai implantar um agente sem max_iterations, error handling e objetivo claro. O medo informado é o melhor guia de arquitetura.
🚀 O que vem na Trilha 2
Você completou a Trilha 1 — Mentalidade Agentic. Agora você tem o modelo mental correto, entende o loop, conhece os componentes e construiu seu primeiro agente. A Trilha 2 — Construção é onde a coisa fica séria.
Módulo 2.1 — Memória Avançada
FAISS, Chroma, embeddings, RAG pipeline completo. Seu agente vai lembrar de tudo entre sessões e buscar conhecimento de bases enormes.
Módulo 2.2 — LangChain na Prática
Chains, agents, prompts e memory no LangChain. Quando usar o framework vs. SDK puro. Padrões de produção que funcionam.
Módulo 2.3 — Multi-Agent Systems
Orquestrador + sub-agentes, comunicação entre agentes, delegação de tasks, sistemas com 5+ agentes em paralelo.
Módulo 2.4 — Deploy em Produção
Observabilidade, monitoramento de custo, Circuit breaker avançado, escalabilidade e arquitetura cloud-native para agentes.
🎯 O que você pode fazer AGORA
Execute o agente de pesquisa do Tópico 4 com uma API de busca real (Serper ou Brave Search)
Adapte o código para um caso do seu trabalho atual — o agente de pesquisa é um template universal
Faça os 4 experimentos de "quebrar de propósito" — cada um ensina algo que você não vai esquecer
Continue para a Trilha 2 quando sentir que dominou o loop básico
✅ Resumo do Módulo 1.6 e da Trilha 1
Neste módulo você aprendeu:
🎓 Você completou a Trilha 1 — Mentalidade Agentic!
Em 6 módulos, você saiu de "o que é um agente?" para "construir e quebrar um agente real". Esse é o modelo mental que vai guiar tudo que você aprende na Trilha 2. Parabéns.
Próxima Trilha:
Trilha 2 — Construção: memória avançada com RAG, LangChain na prática, sistemas multi-agente, e deploy em produção. O nível técnico sobe significativamente — você está pronto.