🔧 Construindo um Agente Completo

Definir claramente: agente de codigo? Assistente de pesquisa? O escopo define quais ferramentas e quanto de autonomia.

Escopo indefinido = agente que tenta tudo e nao faz nada bem.

Escopo, caso de uso, requisitos minimos.

Python como linguagem principal, Ollama como backend local, biblioteca ollama para comunicacao.

Python tem o melhor ecossistema para IA; Ollama roda modelos localmente sem custo.

Python, Ollama, pip install ollama, localhost:11434.

Os 5 componentes minimos: AgentLoop, ToolExecutor, ContextManager, MemoryStore, PermissionController.

Inspirado nos 8 subsistemas do Claude Code, simplificado para implementacao pratica.

Componentes, responsabilidade unica, modularidade.

Dicionario que mapeia nome → funcao + schema. Inspirado no padrao universal de ferramentas do Claude Code.

Registro centralizado permite descoberta, validacao e execucao padronizada.

Registry pattern, tool_map, tool_schemas.

Classe que monitora tokens usados, comprime quando necessario, gerencia sliding window.

Sem gerenciamento, contexto estoura em sessoes longas.

Token counting, sliding window, compression trigger.

Classe com regras allow/deny/ask por ferramenta. Configuravel via JSON. Inspirado nas 5 camadas do Claude Code.

Seguranca nao e opcional — e requisito.

Permission rules, JSON config, allow/deny/ask.

Interface Python com name, description, parameters, execute(). Inspirada no padrao universal do Claude Code.

Consistencia permite trocar/adicionar ferramentas sem reescrever o loop.

Interface, classe base, contrato.

read_file: Path(path).read_text(). write_file: mkdir + write_text. Com tratamento de erros e limites de tamanho.

Sao as ferramentas mais usadas em qualquer agente de codigo.

Path, encoding, error handling, size limits.

subprocess.run com capture_output, timeout, e validacao do comando. Inspirado nas 23+ verificacoes da BashTool.

Shell e o maior vetor de ataque — precisa de sandbox.

subprocess, timeout, command validation, stdout/stderr.

Percorre arquivos com glob, busca com regex, retorna path:line:content. Como o Grep do Claude Code.

Encontrar codigo e essencial antes de editar.

glob, regex, re.search, file traversal.

TOOL_MAP = {name: function}, TOOL_SCHEMAS = [{type, function: {name, description, parameters}}]. OpenAI-compatible.

O LLM precisa do schema para saber quais ferramentas existem e como chama-las.

Tool registry, JSON Schema, OpenAI format.

Read-only tools (read, search) podem rodar em paralelo. Write tools (edit, shell) devem ser sequenciais. Como isConcurrencySafe().

Paralelismo seguro = performance sem bugs.

Concurrency safety, parallel execution, exclusive access.

Lista de dicts [{role, content}] que cresce a cada turno. E o historico da conversa.

Sem historico, cada mensagem e isolada — o agente esquece o que fez.

messages list, role (system/user/assistant/tool), append.

Salvar messages em JSON por sessao. Ou SQLite para busca e organizacao. Classe AgentMemory com save/load.

Sem persistencia, fechar o terminal perde tudo.

JSON files, SQLite, session_id, save/load.

Memoria do Usuario (preferencias), Feedback (correcoes), Projeto (contexto ativo), Referencia (links externos). Inspirado no Claude Code.

Tipos diferentes servem propositos diferentes — nao e tudo igual.

4 tipos, MEMORY.md, indice + topicos.

Quando mensagens excedem limite, manter system + ultimas N. Descartar as mais antigas.

Simples, previsivel, funciona bem para janelas pequenas.

Sliding window, token budget, trim_messages().

Usar o proprio LLM (modelo rapido) para resumir o historico antigo em poucas frases.

Preserva contexto melhor que simplesmente descartar.

Summarization, fast model, context packing.

A cada N sessoes, consolidar memorias: ler sessoes recentes → extrair fatos → atualizar arquivos de topicos → podar indice.

Memorias de curto prazo viram longo prazo, como no sono.

AutoDream simplificado, consolidacao, poda.

Agentes executam comandos reais no seu sistema. Um rm -rf / ou exfiltracao de dados e possivel sem protecao.

Seguranca nao e feature — e requisito para qualquer agente que roda comandos.

Attack surface, risk assessment, defense in depth.

subprocess.run com shell=True controlado: timeout, working directory restrito, environment limpo.

Isolamento limita o dano de comandos maliciosos ou errados.

subprocess, sandbox, restricted environment.

JSON com regras por ferramenta: {"read_file": "allow", "run_shell": "ask", "delete_file": "deny"}.

Equilibrio entre automacao e controle.

Permission config, allow/deny/ask, user confirmation.

Antes de executar run_shell, analisar o comando: bloquear rm -rf, dd, wget para destinos suspeitos, etc.

A BashTool do Claude Code tem 23+ verificacoes por um motivo.

Command parsing, blocklist, pattern matching.

Timeout por ferramenta (30s default), limite de memoria, rate limit de chamadas de API.

Evitar que o agente trave, consuma recursos demais ou gere custos inesperados.

Timeout, memory limit, rate limiting.

Registrar toda chamada de ferramenta com timestamp, parametros, resultado e duracao.

Observabilidade e crucial para depurar, auditar e melhorar o agente.

Logging, audit trail, structured logs.