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

spawn

💡

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 bruta

▼

RAG / search

▼

Sumarização por subagent

▼

Prompt final enxuto

⚠️

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

TipoProjeto

Onde viveCLAUDE.md na raiz do repo

EscopoUm repositório

ExemploStack, padrões, gotchas, comandos de build

TipoUsuário

Onde viveArquivo de memória do agent

EscopoUma pessoa

ExemploPrefs de estilo, feedback recorrente ("não use emoji")

TipoGlobal

Onde viveDocs externos citados em prompts

EscopoToda org

ExemploGuias de segurança, políticas, SLAs

TipoSession

Onde viveContexto da conversa atual

EscopoUma execução

ExemploRaciocí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.

# 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 default

▼

Write em sandbox

▼

Humano aprova

▼

Audit log

🚨

Nunca. (1) Dar credencial de produção pra agent sem HSM/vault intermediando. (2) Rodar , , 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:

# 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 —

📋 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 —

📋 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 ). 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.

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

spawn

💡

Contexto: o recurso mais escasso

Entrada bruta

▼

RAG / search

▼

Sumarização por subagent

▼

Prompt final enxuto

⚠️

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

TipoProjeto

Onde viveCLAUDE.md na raiz do repo

EscopoUm repositório

ExemploStack, padrões, gotchas, comandos de build

TipoUsuário

Onde viveArquivo de memória do agent

EscopoUma pessoa

ExemploPrefs de estilo, feedback recorrente ("não use emoji")

TipoGlobal

Onde viveDocs externos citados em prompts

EscopoToda org

ExemploGuias de segurança, políticas, SLAs

TipoSession

Onde viveContexto da conversa atual

EscopoUma execução

ExemploRaciocínio intermediário, desaparece ao terminar

💡

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.

# 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 default

▼

Write em sandbox

▼

Humano aprova

▼

Audit log

🚨

Política escrita (prompt engineering operacional)

Boa política mora em CLAUDE.md e é clara, curta, com exemplo:

# 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

Alt: Um agent pra tudo —

📋 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 —

📋 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 ). 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?

❓ 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.

✅

Gerenciando Agents: orquestração, contexto e custo

As 5 dimensões de gestão de agent

Orquestração: quando usar múltiplos agents

Contexto: o recurso mais escasso

Memória: o que persiste, o que expira

Controle de custo (token budget)

Segurança: menor privilégio

Política escrita (prompt engineering operacional)

Observabilidade do agent

Cenários reais de decisão

Perguntas típicas

Próximos passos sugeridos

Discussão

Gerenciando Agents: orquestração, contexto e custo

As 5 dimensões de gestão de agent

Orquestração: quando usar múltiplos agents

Contexto: o recurso mais escasso

Memória: o que persiste, o que expira

Controle de custo (token budget)

Segurança: menor privilégio

Política escrita (prompt engineering operacional)

Observabilidade do agent

Cenários reais de decisão

Perguntas típicas

Próximos passos sugeridos

Discussão