💬 Chatbot vs Agente
Um chatbot responde perguntas. Um agente EXECUTA ações. Essa diferença parece sutil, mas muda tudo. O chatbot termina quando entrega o texto; o agente continua até completar a tarefa — lendo arquivos, escrevendo código, rodando comandos. O Claude Code não é um chatbot sofisticado. É um agente completo: loop contínuo, ferramentas reais e memória persistente.
Chatbot vs Agente — A Diferença Fundamental
Chatbot: recebe input → gera texto → fim. Não tem acesso ao mundo real
Agente: recebe input → planeja → usa ferramentas → observa resultado → repete até completar
Claude Code é agente: loop de execução + 40+ ferramentas + 4 tipos de memória
A chave: capacidade de AGIR no mundo, não apenas descrever o que faria
💡 Como Identificar um Agente
Faça o teste simples: o sistema pode modificar algo no mundo real sem intervenção humana? Se sim, é um agente. Se ele só gera texto que você precisa copiar e colar manualmente, é um chatbot. O Claude Code edita seus arquivos diretamente, roda seus testes e faz commits — isso é agência.
🔄 O Loop Fundamental
Todo agente roda um loop: Input → LLM → Tools → Results → Response, repetido quantas vezes forem necessárias. É o while(true) do Claude Code. O agente não sabe de antemão quantas iterações vai precisar — ele continua até que o LLM decida que terminou (ou atinja um limite de segurança).
O Ciclo do Agente
Input: o usuário faz um pedido ou o sistema injeta uma tarefa
LLM decide: o modelo analisa o contexto e escolhe quais ferramentas usar (ou nenhuma)
Tools executam: as ferramentas escolhidas rodam e produzem resultados concretos
Loop repete: resultados voltam pro LLM, que decide se precisa de mais ações ou se pode responder
📊 Como o Claude Code Implementa o Loop
queryHaiku/queryLoop: função principal que mantém o loop rodando até não haver mais tool_calls
Streaming assíncrono: resultados chegam em tempo real via async generators
Execução paralela: múltiplas tool calls na mesma iteração rodam simultaneamente
Fallback de modelo: se o modelo principal falha, o loop tenta automaticamente um modelo alternativo
🧰 Ferramentas como Superpoderes
Sem ferramentas, um LLM é apenas um gerador de texto. Com ferramentas, ele pode ler arquivos, executar código, buscar na web, criar commits e muito mais. As ferramentas são o que transformam previsão de próximo token em ação real. O Claude Code tem mais de 40 ferramentas, cada uma dando ao agente uma capacidade específica.
O Papel das Ferramentas
Interface com o mundo: ferramentas são a ponte entre o raciocínio do LLM e ações concretas
Definidas como JSON Schema: cada ferramenta tem nome, descrição e parâmetros tipados
LLM escolhe quais usar: o modelo decide sozinho quais ferramentas chamar com quais argumentos
Resultado volta como contexto: a saída da ferramenta é adicionada à conversa para o LLM processar
💡 Ferramentas no Claude Code
O Claude Code organiza suas 40+ ferramentas em categorias: leitura (Read, Glob, Grep), escrita (Edit, Write), execução (Bash), navegação (WebFetch, WebSearch) e meta (Agent, TodoWrite). Cada ferramenta tem permissões configuráveis — algumas rodam livremente, outras pedem confirmação. Quando você construir seu próprio agente, comece com 3-5 ferramentas essenciais e vá adicionando conforme a necessidade.
🧠 Estado e Memória
Estado é o que o agente sabe agora — o contexto da conversa atual, os resultados das ferramentas, as decisões tomadas. Memória é o que persiste entre sessões — configurações, preferências, conhecimento acumulado. O Claude Code implementa 4 tipos de memória + o sistema AutoDream para resumo automático.
Estado vs Memória
Estado (efêmero): conversa atual, tool results pendentes, decisões em andamento — morre quando a sessão fecha
Memória (persistente): CLAUDE.md, configurações, preferências aprendidas — sobrevive entre sessões
Context window: o "cérebro de curto prazo" — tudo que cabe na janela de contexto do modelo
AutoDream: quando a context window enche, o Claude Code resume automaticamente para liberar espaço
📊 Os 4 Tipos de Memória do Claude Code
CLAUDE.md global: ~/.claude/CLAUDE.md — preferências do usuário, válido para todos os projetos
CLAUDE.md de projeto: ./CLAUDE.md — regras específicas do projeto, commitável no git
CLAUDE.local.md: memória local não commitável — segredos, paths, configs pessoais
TodoWrite: lista de tarefas persistente dentro da sessão — o agente marca progresso conforme avança
🎯 Autonomia e Limites
Quanto de liberdade você dá ao agente? Autonomia demais é perigoso — ele pode deletar arquivos, fazer push forçado ou gastar tokens desnecessariamente. Autonomia de menos é frustrante — fica pedindo confirmação para tudo. O Claude Code resolve isso com um sistema de permissões em 5 camadas.
O Espectro da Autonomia
Allow: ferramentas permitidas sem perguntar — leitura de arquivos, buscas, operações seguras
Ask: pede confirmação antes de executar — escrita, execução de comandos, operações potencialmente destrutivas
Deny: bloqueado completamente — operações proibidas por política de segurança
5 camadas: sistema operacional, processo, rede, API e permissões do usuário — defesa em profundidade
Fazer
- ✓ Configurar permissões explícitas para cada ferramenta
- ✓ Usar modo interativo para tarefas sensíveis (ask before execute)
- ✓ Rodar em sandbox/container quando testar agentes novos
- ✓ Definir limites de iteração e custo máximo
Evitar
- ✗ Dar autonomia total sem entender o que o agente pode fazer
- ✗ Desabilitar confirmações em operações destrutivas
- ✗ Rodar agentes sem limite de iteração em produção
- ✗ Confiar cegamente na saída sem revisar ações críticas
📐 Anatomia de um Agente
Todo agente é composto pelos mesmos blocos fundamentais: loop de execução, ferramentas, contexto, memória e segurança. No Claude Code, esses blocos se organizam em 8 subsistemas interconectados. Entender essa anatomia é o primeiro passo para construir o seu próprio agente.
Componentes de um Agente
| Componente | Claude Code | Seu Agente |
|---|---|---|
| Loop | queryHaiku / queryLoop | while True + API call |
| Ferramentas | 40+ tools (Read, Edit, Bash...) | 3-5 tools iniciais |
| Contexto | System prompt + CLAUDE.md | System prompt customizado |
| Memória | 4 tipos + AutoDream | Arquivo de estado |
| Segurança | 5 camadas + allow/deny/ask | Validação de input/output |
| Streaming | Async generators | SSE ou WebSocket |
| Erros | Retry + fallback de modelo | Try/catch + retry |
| Agentes | Standard/Fork/Teammate | Subprocessos |
📋 Resumo do Módulo
Próximo Módulo:
4.2 - 🔄 O Loop do Agente