🎛️
Gerenciando Agents: orquestração, contexto e custo
⏱ 17 min de leitura·+80 XP
Pré-requisitos (0/1)0%
- ⬜📜 Spec-Driven Development (SDD): a nova espinha dorsal(Engenharia de Software Moderna)
Recomendamos completar os pré-requisitos antes de seguir, mas nada te impede de continuar.
Agent não é botão mágico. É processo com contexto, memória, ferramentas, orçamento e política. Gerenciar agents em organização séria é mais parecido com orquestrar serviços distribuídos do que com pedir ajuda num chat: você define limites, observa comportamento, mede outcome, corta custo, auditoria em cima. Quem trata agent como chatbot paga em bug de produção.
As 5 dimensões de gestão de agent
1. ContextoO que entra na janela. Quanto mais denso e relevante, melhor o output. RAG, sumarização, subagents e CLAUDE.md são ferramentas pra curar contexto.
2. MemóriaO que persiste entre sessões. Memória de projeto (CLAUDE.md), memória de usuário (prefs), memória global (docs). Muita memória vira ruído.
3. ToolsO que o agent pode fazer: ler, escrever, executar comando, chamar API, MCP server. Menor privilégio por padrão.
4. OrçamentoTokens por run, custo por tarefa, timeout. Sem orçamento, um loop de agent pode custar $100 num loop acidental.
5. PolíticaRegras: "nunca faça X", "sempre peça confirmação pra Y", "em caso de Z, pare". Vive em CLAUDE.md, policy files, ou hooks.
Orquestração: quando usar múltiplos agents
🗺️ Padrão Orchestrator + Subagents
Orchestrator
🧠→
Decide tarefas
plano
📋→
Delega a subs
prompt + tools
📊→
Revisa resultado
sumário
✅→
Entrega ao humano
PR final
spawn
Subagents
🔬←
Research agent
lê repo, gera sumário
🧪←
Testing agent
escreve e roda testes
🛡️←
Security agent
revisa vuln
🏗️←
Architect agent
planeja trade-off
💡
Por que subagents vencem “um agent faz tudo”. (1) Contexto isolado — research agent não polui janela do orquestrador com 20 arquivos lidos; só retorna o sumário. (2) Paralelização — rodar research+security ao mesmo tempo acelera lead time. (3) Especialização — subagent com system prompt específico performa melhor. (4) Custo — cada subagent paga só pelo próprio contexto.
Contexto: o recurso mais escasso
📥Entrada brutarepo + web + docs
Tudo que poderia ser relevante. Mas não cabe na janela e confunde o modelo.
filtra▼
🧠RAG / searchrecall
Busca semântica por chunks relevantes. BM25 + embeddings + reranker.
sumariza▼
📝Sumarização por subagentcompress
Research agent lê 20 arquivos, retorna 500 tokens de essência.
injeta▼
🎯Prompt final enxutofocused
Spec + contexto filtrado + regras. Modelo trabalha com clareza.
⚠️
Armadilha do “coloca tudo na janela”. Jogar o repo inteiro num modelo de 1M tokens não é estratégia — é preguiça. Qualidade cai. Latência sobe. Custo explode. Contexto é curado como query em banco de dados, não como despejo.
Memória: o que persiste, o que expira
| Tipo | Onde vive | Escopo | Exemplo |
|---|---|---|---|
| Projeto | CLAUDE.md na raiz do repo | Um repositório | Stack, padrões, gotchas, comandos de build |
| Usuário | Arquivo de memória do agent | Uma pessoa | Prefs de estilo, feedback recorrente ("não use emoji") |
| Global | Docs externos citados em prompts | Toda org | Guias de segurança, políticas, SLAs |
| Session | Contexto da conversa atual | Uma execução | Raciocínio intermediário, desaparece ao terminar |
💡
CLAUDE.md é o gerente de memória. É o arquivo que o agent lê sempre ao abrir o projeto. Boa regra: 200 linhas max, seções claras (Stack, Comandos, Gotchas, Padrões). Mais que isso vira ruído e o agent começa a ignorar.
Controle de custo (token budget)
Custo de agent é linear com tokens. Uma tarefa “pequena” pode virar $5 em um loop de ferramenta. Gerenciar custo é operacional:
Token budget por runEx.: 100k tokens por tarefa. Agent para antes de estourar e pede decisão ao humano.
Modelo certo pra tarefaHaiku pra task trivial (sumário, lint), Sonnet pra maioria, Opus só quando precisa raciocínio pesado (trade-off, código crítico).
Cache promptUsa prompt caching do provider. Prefixo estável (system + CLAUDE.md) vira ~90% mais barato.
Evite loopsTool call que loopa é custo exponencial. Ponha timeout e max_iterations.
Observe uso realDashboard com tokens por dev, por projeto, por tipo de tarefa. Conversa com time quando sobe injustificado.
bash
# Exemplo: política de custo por agent em .agent/policy.yaml models: default: claude-sonnet-4-6 heavy: claude-opus-4-6 light: claude-haiku-4-5 budget: per_task_max_tokens: 100000 per_day_max_usd: 50 alert_threshold_usd: 40 policy: require_approval_above_usd: 5 kill_switch_above_usd: 20
Segurança: menor privilégio
👁️Read-only defaultsempre
Agent começa podendo ler. Qualquer write requer permissão explícita.
autoriza▼
📝Write em sandboxárea isolada
Worktree, container, VM. Agent nunca toca em main branch direto.
revisa▼
✅Humano aprovaPR ou prompt
Merge, deploy, chamada paga, drop de tabela: humano confirma.
audita▼
📋Audit logtudo
Cada comando executado vira log imutável. SIEM consome.
🚨
Nunca. (1) Dar credencial de produção pra agent sem HSM/vault intermediando. (2) Rodar
rm -rf, DROP TABLE, git push --force sem confirmação humana. (3) Permitir chamada a endpoint caro (OpenAI, SMS, Twilio) sem budget cap. (4) Deixar agent com acesso a webhook público executar código arbitrário.Política escrita (prompt engineering operacional)
Boa política mora em CLAUDE.md e é clara, curta, com exemplo:
markdown
# Policies (em CLAUDE.md) ## O que agent NUNCA faz sem confirmação humana - git push --force, git reset --hard - DROP TABLE / ALTER TABLE destrutivo - Apagar arquivo fora de /tmp ou worktree - Chamar API externa paga (LLM, SMS, pagamento) - Alterar .env, credentials.json, secrets ## Estilo de código - TypeScript strict. Nunca "any". - Componentes React: named export, function component. - Testes: vitest + msw; não mockar banco. ## Fluxo de PR - Sempre abrir PR, nunca commit direto em main. - PR deve linkar a spec (docs/specs/<slug>.md). - Descrição: 1 parágrafo do "o que e por quê". ## Onde achar contexto - Ticket em Linear/INGEST = bugs de pipeline. - SLOs em grafana.internal/d/api-latency. - Runbook em ops/RUNBOOK.md.
Observabilidade do agent
Taxa de sucesso% de tarefas em que agent entregou PR aceito sem pedir mudança grande.
Lead timeDo início da tarefa até merge. Agent deve reduzir vs baseline humano.
Custo por featureSoma de tokens * preço modelo. Compare com horas-humano equivalentes.
Bug escape rate% de PRs de agent que geraram incidente em <30 dias pós-deploy. Baseline humano é ~5-10%.
Cobertura de testeAgent tende a escrever mais testes; verifique se são úteis (mutation score, não só cobertura).
Tempo de review humanoSe reviewer gasta mais tempo lendo PR de agent do que escreveria sozinho, algo está errado.
Cenários reais de decisão
📋 Migrar 200 endpoints de Express pra Fastify num monorepo
✓ Orchestrator + subagents paralelos
Orchestrator quebra em batches de 20 endpoints por subagent; cada sub carrega contexto mínimo (seu batch + utils compartilhados), retorna PR. Humano revisa cada PR com checklist — agent faz o que agent faz bem.
Alt: Um agent pra tudo — contexto estoura, qualidade cai do endpoint 50 em diante.
📋 Debug de latência P99 intermitente em API crítica
✓ Humano lidera, agent assistente
Exige intuição operacional, traces, correlação com deploys. Agent lê flamegraph, sugere hipótese, escreve benchmark. Decisão é humana — você responde pelo incidente.
Alt: Agent sozinho — sem acesso a traces reais e SRE judgment, chuta.
📋 Feature nova com impacto em 30 arquivos e integração com stripe
✓ SDD + subagent de security obrigatório
Spec na mão. Security subagent roda antes do merge (scan de vulns, review de chamadas ao stripe, verificação de idempotência). Sem esse gate, dívida cresce em silêncio.
Perguntas típicas
❓ Meu time tem 10 devs. Posso usar o mesmo CLAUDE.md pra todos?
Sim. CLAUDE.md é do projeto. Prefs individuais vão em arquivo de memória do usuário (por exemplo
~/.claude/memory/). Regra do time vai no CLAUDE.md do repo.❓ Como evito que agent mexa em arquivo que não é da tarefa?
Especifique arquivos-alvo no prompt + policy no CLAUDE.md + review crítico. Se agent mexe em 20 arquivos quando a tarefa era 2, rejeita o PR e ajusta o prompt/policy.
❓ Agent é confiável pra merge automático?
Não em produção ainda. Em 2026 o padrão é: agent abre PR, humano (ou LGTM automático com CI verde + score de review assistido por IA) merge.
❓ Quando não usar agent?
Quando você não entende o problema (vai só mascarar sua confusão); quando a stack é desconhecida do modelo (contexto ruim); quando o risco é alto e custo de erro é grande (migrations críticas, produção sem canary).
❓ Como prevenir um agent quebrar um agent (loop)?
Timeouts por tool call, limite de iterações, circuit breaker no orchestrator, e validação do output de cada subagent antes de continuar. Sem isso, um bug trivial vira bill de $500.
✅
Take-aways.(1) Agent é processo: contexto + memória + tools + orçamento + política. (2) Orchestrator + subagents ganham de “um agent pra tudo”. (3) Contexto é curado, não despejado. (4) Menor privilégio é inegociável. (5) Mede outcome (lead time, bug escape, custo), não volume. (6) Próximo: você vai criar um agent customizado.
🧩
Quiz rápido
4 perguntas · Acerte tudo e ganhe o badge 🎯 Gabarito
Próximos passos sugeridos
Continue lendo