Harness: a Infraestrutura do Agente
- ⬜🔧 Tool Calling e Agentes(IA Além do LLM)
Recomendamos completar os pré-requisitos antes de seguir, mas nada te impede de continuar.
Voce ja sabe que um agente e um LLM em loop com tools. Mas o que faz um agente funcionar bem? A resposta e o harness — a infraestrutura ao redor do modelo que orquestra o loop, gerencia contexto, controla permissoes e delega para subagentes. Neste artigo, voce vai entender os 6 componentes que transformam um LLM em um agente profissional.
Anatomia de um agente
1. LLM: o cerebro
O LLM e uma funcao pura: recebe texto (contexto), retorna texto (decisao/conteudo). Ele nao tem estado — tudo que sabe vem do contexto que o harness envia.
| Escolha de modelo | Quando usar | Trade-off |
|---|---|---|
| Opus / GPT-4 | Tarefas complexas, raciocinio longo, planejamento | Mais caro ($15-75/M tokens), mais lento |
| Sonnet / GPT-4o | Uso geral, coding, analise | Equilibrio custo/qualidade |
| Haiku / GPT-4o-mini | Triagem, classificacao, tasks simples | Rapido e barato, menos capaz em tarefas complexas |
2. Tools: as maos
Tools sao as interfaces do agente com o mundo. Em um coding agent tipico:
| Tool | O que faz | Risco |
|---|---|---|
| read_file | Le conteudo de um arquivo | Baixo — so leitura |
| write_file | Cria ou sobrescreve arquivo | Medio — pode destruir trabalho |
| edit_file | Edita trecho especifico (search/replace) | Medio — edicao precisa |
| run_command | Executa comando no shell | Alto — pode rodar qualquer coisa |
| search_codebase | Busca por pattern no codigo | Baixo — so leitura |
| web_search | Pesquisa na internet | Baixo — so leitura |
| create_subagent | Delega tarefa para agente filho | Medio — consume tokens |
3. Loop: o ciclo de decisao
O numero de iteracoes varia: uma refatoracao simples pode levar 5-10 passos. Um bug complexo pode levar 30-50. Agentes profissionais tem limites de iteracao para evitar loops infinitos e custo descontrolado.
4. Context Engineering: o que vai no prompt
O contexto e tudo que o modelo ve a cada passo. Gerenciar esse contexto e talvez a parte mais importante e menos obvia do harness.
5. Subagentes: dividir para conquistar
Tarefas complexas se beneficiam de delegacao. O agente principal cria subagentes especializados, cada um com:
| Aspecto | Agente principal | Subagente |
|---|---|---|
| Contexto | Completo (task + historico) | Limpo (so a subtarefa) |
| Tools | Todos disponiveis | Pode ser restrito (so leitura, por ex) |
| Custo | Alto (contexto longo) | Menor (contexto focado) |
| Risco | Pode tomar decisoes globais | Isolado — nao afeta estado principal |
6. Permissoes: seguranca em agentes
Um agente com acesso a shell pode rodar qualquer comando. Sem controle, isso e perigoso. Harnesses profissionais categorizam acoes por risco:
| Nivel | Acoes | Comportamento |
|---|---|---|
| Auto-approve | Ler arquivo, buscar codigo, listar diretorio | Executa sem perguntar |
| Ask once | Editar arquivo, criar arquivo, instalar pacote | Pede permissao na primeira vez, lembra depois |
| Always ask | Deletar arquivo, push git, executar shell generico | Pede permissao toda vez |
| Block | Push force, rm -rf, credenciais, emails | Nunca permite — alerta o usuario |
📋 Projetando permissoes para um coding agent
Comece bloqueando tudo exceto leitura. O usuario libera acoes conforme confianca cresce. O custo de parar para pedir permissao e baixo; o custo de uma acao destrutiva nao autorizada e alto.
Alt: Auto-approve tudo — Apenas em ambientes isolados (containers, VMs) onde destruicao nao importa.
Padrões de orquestração: qual arquitetura usar
A estrutura do agente determina como ele decompõe tarefas complexas. Não existe padrão universal — cada um tem trade-offs em qualidade, velocidade e custo:
| Padrão | Como funciona | Melhor para | Limitação |
|---|---|---|---|
| ReAct (Reasoning + Acting) | Pense → Aja → Observe → Repita. Loop simples sem planejamento explícito. | Tarefas abertas onde o próximo passo depende do resultado anterior | Pode ficar preso em loops se uma ferramenta falha repetidamente |
| Plan-and-Execute | Fase 1: planejar todos os passos. Fase 2: executar o plano. | Tarefas bem definidas onde o espaço de busca é conhecido antecipadamente | Plano pode ficar obsoleto se o ambiente muda durante execução |
| Orchestrator-Worker | Agente orquestrador delega subtarefas para subagentes especializados. | Tarefas compostas com domínios distintos (código + busca + análise) | Overhead de comunicação entre agentes; custo alto |
| Parallel Execution | Múltiplos subagentes trabalham simultaneamente em partes independentes. | Tarefas paralelizáveis: analisar 50 arquivos, pesquisar 10 fontes | Precisa de dependência clara entre subtarefas para evitar conflitos |
| Reflexion | Agente auto-critica sua própria saída e itera até atingir qualidade alvo. | Tarefas com critério de qualidade claro (código que passa nos testes) | Caro (múltiplas iterações); risco de loop infinito sem critério de parada |
Custo de um agente em producao
A conta fecha quando o agente economiza 2+ horas/dia de trabalho de dev. Para tarefas bem definidas (testes, docs, bug fixes), o ROI é imediato.
Perguntas e respostas
❓ Qual a diferenca entre ReAct e outros patterns de agente?
❓ Como evitar loops infinitos?
❓ O contexto nao estoura em tarefas longas?
Quiz rápido
4 perguntas · Acerte tudo e ganhe o badge 🎯 Gabarito