🤖 Agente vs LLM call
Distinção categórica que muda tudo. LLM call é stateless: input → output, ponto. Nenhuma ação no mundo real, nenhuma memória entre chamadas. Agente é stateful e ativo: decide iterativamente que ações tomar, executa via ferramentas, observa resultado, ajusta plano.
📖 A definição da Anthropic
"Agents are systems where LLMs dynamically direct their own processes and tool usage, maintaining control over how they accomplish tasks."
— anthropic.com/research/building-effective-agents
✓ Agente (Claude Code)
- ✓Stateful — mantém plano e contexto
- ✓Chama ferramentas (Read, Write, Bash)
- ✓Modifica estado externo (disco, terminal, web)
- ✓Itera baseado em observações
✗ LLM call (API direta)
- ✗Stateless — sem memória entre chamadas
- ✗Só texto/imagem in, texto out
- ✗Nenhuma ação fora da resposta
- ✗Sem iteração baseada em resultado
🪜 A escada: workflow → agente
- LLM call: "traduz isso aqui"
- Workflow: código orquestra LLMs e ferramentas em caminhos pré-definidos
- Agente: o próprio LLM controla o fluxo dinamicamente, escolhe ferramentas, decide quando parar
💡 Dica prática
Pra sala mista, use a analogia: LLM call é Google search, workflow é Zapier, agente é estagiário com chave do escritório. O estagiário decide a ordem, abre as gavetas, e te traz o resultado pronto.
🔄 Loop perceive → think → act → observe
O loop agêntico canônico, formalizado no paper ReAct (Yao et al., Princeton/Google, 2022): Thought → Action → Observation → repeat. Mostrou ganho de 34% em ALFWorld e 10% em WebShop vs. modelos sem o loop.
⚙️ Pseudocódigo do loop
loop:
Thought → modelo raciocina sobre o estado
atual e decide próximo passo
Action → chama ferramenta com argumentos
Observation → recebe resultado da ferramenta
→ continua até condição de parada
(tarefa concluída ou erro irrecuperável)Perceive
Recebe estado atual
Lê o prompt do usuário, o histórico da conversa, o output da última ferramenta. Não age, só absorve.
Think (Thought)
Raciocina sobre o que fazer
O modelo escreve um chain-of-thought visível: "preciso ler o README primeiro, depois entender a estrutura, depois identificar onde fica a feature X". É o passo que justifica a ação seguinte.
Act (Action)
Chama uma ferramenta
Tool call estruturada: Read({"path": "README.md"}). Cada ação modifica ou consulta o mundo externo.
Observe (Observation)
Lê o retorno da ferramenta
Recebe o resultado (conteúdo de arquivo, exit code do bash, dados da API). É o feedback que alimenta a próxima rodada de Thought.
🧠 Reflexion — a camada extra
Reflexion (Shinn et al., 2023): após falha, o agente gera uma reflexão verbal sobre o que deu errado antes de tentar de novo — sem fine-tuning, só feedback em texto. É o que diferencia agente robusto de agente que entra em loop infinito.
🛠️ Tool use no Claude Code
Claude Code é a implementação de referência. Tem 18+ ferramentas e roda tipicamente 5-50 iterações do loop por tarefa. Cada tool é uma porta pra agir no mundo: disco, terminal, web.
📦 Categorias de ferramentas
File ops → Read, Write, Edit
Search → Glob, Grep
Execution → Bash
Planning → TodoWrite
Orchestration → Agent (ex-Task), Skill
Web → WebFetch, WebSearch
+ MCP tools customizadas via plugins✓ Boas práticas de tool use
- ✓Grep antes de Read (não leia repo inteiro)
- ✓Edit prefere Write (diff < sobrescrita)
- ✓Bash em background pra processos longos
- ✓Agent pra tarefa que precisa de muitos Reads
✗ Anti-padrões clássicos
- ✗Read em loop até estourar contexto
- ✗Bash com cat/sed em vez de Read/Edit
- ✗Write em arquivo grande pra mudar 1 linha
- ✗Subagente pra tarefa de 30 segundos
💡 Dica prática
Em prompts pro Code, você pode orientar a estratégia de ferramentas: "Use Glob pra achar todos os testes, depois Grep pra filtrar os que mencionam X, só então Read os relevantes." Isso economiza contexto e tempo.
📋 TodoWrite e tracking
TodoWrite é a ferramenta que externaliza o plano em JSON estruturado. Quando enfrenta tarefa multi-step, Claude Code chama TodoWrite primeiro — cria lista com IDs, status e prioridade. O sistema re-injeta o estado do TODO após cada tool use, impedindo que o modelo esqueça onde está.
🧬 Anatomia de um TODO
[
{ id: 1, content: "Ler README e identificar stack",
status: "completed", activeForm: "Lendo README..." },
{ id: 2, content: "Rodar testes existentes",
status: "in_progress", activeForm: "Rodando testes..." },
{ id: 3, content: "Localizar arquivo de auth",
status: "pending", activeForm: "Localizando auth..." }
]⚙️ Por que o re-injection muda o jogo
- Sem TodoWrite: em tarefa de 20 passos, depois do passo 12 o agente começa a esquecer o início
- Com TodoWrite: a cada tool call, o estado completo do plano volta ao contexto
- Memória de trabalho visível: você (humano) vê o plano e pode intervir
- Auto-correção: o agente atualiza o TODO quando descobre que estava errado
💡 Dica prática
Use o TODO como ferramenta de governança. Em demo, mostre o plano antes de deixar rodar. Em workflow real, peça "atualize o TODO antes de cada ação". Vira janela de auditoria.
🌳 Subagents e paralelização
Subagentes rodam em contexto próprio com ferramentas restritas. O agente pai recebe apenas o resultado final — não o transcript completo — mantendo o contexto principal limpo. É o salto entre "uso o agente" e "delego a um time".
🧬 Anatomia de um subagente
---
name: pesquisador-auth
description: "Pesquisa código de autenticação
em codebases multi-arquivo"
model: sonnet
tools: Read, Grep, Glob
disallowedTools: Write, Edit, Bash
---
Você é um agente de pesquisa de código focado em
autenticação. Retorne só o sumário final.⚡ Paralelização real
Instrução em linguagem natural: "pesquise autenticação, banco de dados e API em paralelo usando subagentes separados". Claude Code spawna múltiplos subagentes simultâneos, cada um com seu contexto, e sintetiza os resultados.
- Built-in: Explore, Plan, general-purpose (pulam CLAUDE.md pra ficar leves)
- Custom: definidos em
.claude/agents/(projeto) ou~/.claude/agents/(usuário) - Inline:
claude --agents '{...}'sem salvar em disco - Background: subagentes podem rodar em background com
background: true
✓ Quando dispachar
- ✓Tarefa precisa ler 20+ arquivos
- ✓3+ subtarefas independentes (paralelo)
- ✓Quer manter contexto principal enxuto
- ✓Subtarefa exige tools/modelo diferente
✗ Quando NÃO dispachar
- ✗Tarefa de 1-2 tool calls
- ✗Você precisa ver o transcript inteiro
- ✗Subtarefas dependem uma da outra (seq)
- ✗Custo de spawn > ganho de paralelização
🪞 Reflection (ReAct, Reflexion)
Reflection é a camada que diferencia agente robusto de agente em loop infinito. Após falha (ou após N tentativas), o agente gera uma reflexão verbal sobre o que deu errado antes de tentar de novo. Sem fine-tuning — só feedback em texto.
📚 Os dois papers canônicos
- ReAct (Yao 2022): formaliza Thought-Action-Observation. Ganho de 34% em ALFWorld e 10% em WebShop.
- Reflexion (Shinn 2023): adiciona auto-crítica verbal após falha. Em HumanEval (codding), Reflexion alcança 91% pass@1 — superando GPT-4 sem reflection.
🔁 Reflexion em pseudocódigo
tentativa = 1
while not sucesso and tentativa <= max_tentativas:
resultado = executa_loop_react(tarefa)
if not avalia_resultado(resultado):
reflexao = "Eu falhei porque... próxima vez vou..."
contexto += reflexao
tentativa += 1✓ Como pedir reflection em prompts
- ✓"Após cada falha, escreva 2 linhas sobre o que deu errado"
- ✓"Antes de tentar de novo, revise o que mudou"
- ✓"Se a mesma estratégia falhar 2x, mude de abordagem"
✗ Sinais de "falta reflection"
- ✗Agente tenta a mesma coisa 5 vezes seguidas
- ✗Loop "Edit → testa → falha → Edit igual"
- ✗Resposta final sem reconhecer dificuldades
💡 Dica prática
Em prompts de produção, peça reflection explícita entre tentativas. É a diferença entre "agente travou" e "agente mudou de estratégia". Custa 1-2 frases no system prompt.
📋 Resumo do Módulo
Próximo Módulo:
2.4 — 📊 Hierarquia Haiku → Sonnet → Opus (três marchas, três preços, breaking change 4.7)