Por que você deveria parar de chamar tudo de "agente de IA"

Se você trabalha com IA há mais de seis meses, já deve ter notado: todo mundo virou "agente". Chatbot com duas funções? Agente. Script que chama GPT em loop? Agente autônomo. Marketing de produto SaaS? "Nossa plataforma usa agentes inteligentes."

Esse fenômeno tem até nome: agent washing. Mas por baixo do hype, existe uma mudança real acontecendo — e se você vai construir sistemas desse tipo (ou apenas entender o que seu colega de trabalho está propondo na sprint), vale a pena separar o que é buzzword do que é arquitetura.

O que separa um agente de um chatbot

A diferença não está no modelo. Está no loop.

Um chatbot tradicional funciona assim:

const response = await llm.chat("Me ajude com isso");
console.log(response);

Um agente faz isso:

let goal = "Encontre todos os bugs críticos no repositório";
let done = false;

while (!done) {
  const action = await agent.decide(goal, context);
  const result = await execute(action); // pode ser grep, API call, etc
  context.push(result);
  done = await agent.checkIfGoalReached(context);
}

A diferença está no agent loop: o sistema age, observa o resultado, decide o próximo passo. Repete até atingir o objetivo ou bater em um limite (tokens, tempo, tentativas).

Não é "IA que responde". É "IA que faz".

Tool calling: a primitiva que muda tudo

Se você usou Claude, GPT ou Gemini recentemente, já viu tool calling em ação — mesmo sem perceber.

Antes, quando você perguntava "Quanto é 127 * 843?", o modelo adivinhava. Agora ele faz isso:

{
  "role": "assistant",
  "tool_calls": [
    {
      "name": "calculator",
      "arguments": { "expression": "127 * 843" }
    }
  ]
}

Você executa a função, devolve o resultado, o modelo continua. Simples, mas é isso que permite que agentes usem ferramentas reais em vez de alucinar respostas.

A sacada: tool calling não é "o agente". É a interface que permite construir um.

Agent harness: a infraestrutura invisível

Se o LLM é o cérebro, o agent harness é o corpo. É tudo que fica em volta:

• Gerenciamento de ferramentas (quais o agente pode usar, quando, com quais permissões)
• Controle de estado (memória entre iterações)
• Tratamento de erro (quando a API falha, quando o modelo trava, quando ele tenta algo proibido)
• Limites (budget de tokens, timeout, retry policy)

Você raramente vê isso documentado porque é código de infraestrutura — mas é onde 80% do trabalho está. O modelo decide o que fazer. O harness decide se deixa.

Exemplo real: um agente tenta rodar rm -rf / porque interpretou mal uma instrução. O harness bloqueia, loga, e devolve "permission denied" pro modelo tentar outra coisa.

Guardrails são a parte do harness que impõe regras: não pode acessar certos arquivos, não pode gastar mais de X tokens, não pode tomar ação Y sem aprovação humana.

Context engineering: o timing importa mais que o volume

Você tem 10 mil linhas de documentação relevante. Joga tudo no prompt?

Má ideia. O modelo vai gastar atenção (literal — attention mechanism) em partes irrelevantes, e você vai estourar o contexto antes de terminar.

Context engineering é a arte de dar a informação certa na hora certa:

// Ruim: joga tudo logo no início
const prompt = `${todaADocumentacao}\n\n${perguntaDoUsuario}`;

// Melhor: busca o que é relevante sob demanda
const question = "Como funciona autenticação?";
const relevantDocs = await searchDocs(question, topK=3);
const prompt = `${relevantDocs}\n\n${question}`;

Em sistemas multi-agente, isso fica ainda mais crítico. Você não quer que o agente de frontend veja os logs do backend a cada iteração. Quer que ele peça quando precisar.

MCP: porque cada ferramenta não deveria ser um caso especial

Se você já integrou um LLM com ferramentas externas, sabe o problema: cada API é um floco de neve. OAuth aqui, API key ali, webhook acolá. Você acaba com um Frankenstein de integrações.

Model Context Protocol (MCP) é uma tentativa da Anthropic de padronizar isso. A ideia:

[Agente] <--MCP--> [Servidor de Ferramentas] <--> [GitHub, Jira, DB, etc]

O agente fala MCP. O servidor expõe ferramentas via MCP. Você troca de ferramenta sem reescrever o agente.

Ainda está em adoção (e tem concorrência), mas a direção é essa: ferramentas como protocolo, não como código custom.

Agentic RAG: quando o agente escolhe o que buscar

RAG tradicional:

const docs = await vectorDB.search(query);
const answer = await llm.generate(docs, query);

Agentic RAG:

let findings = [];
while (!satisfied) {
  const nextQuery = await agent.decideWhatToSearchNext(findings);
  const docs = await vectorDB.search(nextQuery);
  findings.push(docs);
  satisfied = await agent.hasEnoughInfo(findings);
}
const answer = await agent.synthesize(findings);

O agente dirige a busca. Se a primeira query não trouxe o que ele precisa, ele refina, tenta outro ângulo, cruza fontes.

Útil quando a pergunta é complexa e você não sabe de antemão qual chunk vai ter a resposta.

Multi-agente: quando um não basta

Você tem um sistema que precisa:

1. Ler issues do GitHub
2. Analisar o código relacionado
3. Gerar um report técnico
4. Postar no Slack

Opção A: um agente faz tudo. Opção B: quatro agentes especializados, com um orchestrator coordenando.

const issues = await githubAgent.fetchCriticalIssues();
const analysis = await codeAgent.analyze(issues);
const report = await reportAgent.generate(analysis);
await slackAgent.post(report);

Cada agente tem ferramentas, contexto e prompt próprios. O orchestrator gerencia a pipeline.

Desvantagem: complexidade. Vantagem: cada agente fica pequeno, testável, e você pode trocar um sem quebrar os outros.

Human-in-the-loop: o freio de mão

HITL é simples: antes de fazer algo crítico, o agente pede aprovação.

if (action.isDestructive) {
  const approved = await askHuman(action);
  if (!approved) return;
}
await execute(action);

Parece óbvio, mas você ficaria surpreso com quantos "agentes autônomos" em produção não têm isso. Até o sistema estar maduro (e mesmo depois), HITL é sua rede de segurança.

Evals: porque "parece funcionar" não é teste

Como você testa um agente? Rodar uma vez e ver se deu certo?

Evals (evaluations) são datasets de casos de teste onde você sabe o resultado esperado:

const testCases = [
  {
    goal: "Encontre o arquivo de config",
    expectedTool: "grep",
    expectedResult: "config.json"
  },
  // ...
];

for (const test of testCases) {
  const result = await agent.run(test.goal);
  assert(result.tool === test.expectedTool);
  assert(result.output.includes(test.expectedResult));
}

Você roda evals antes de deploy, depois de mudar o prompt, depois de trocar de modelo. É a única forma de saber se você quebrou algo.

Computer use: quando não existe API

Última fronteira: agentes que controlam interfaces visuais. Tipo Selenium, mas dirigido por IA.

// Pseudo-código
await agent.openBrowser("https://example.com");
await agent.click("Login");
await agent.type("#username", "user");
await agent.type("#password", "pass");
await agent.click("Submit");
const data = await agent.extractTable(".results");

Útil quando você precisa integrar com sistemas legados que não têm API. Frágil (qualquer mudança de UI quebra), lento, mas às vezes é a única opção.

Anthropic lançou isso como computer use (literalmente "uso do computador"). Outros estão seguindo.

Quando não usar agentes

Agora a parte que ninguém fala: a maioria dos problemas não precisa de um agente.

Se você pode resolver com:

• Uma chamada de LLM (llm.generate(prompt))
• Um script determinístico
• Uma pipeline de dados tradicional

...use isso. Agentes são caros (tokens, latência, complexidade), imprevisíveis, e difíceis de debugar.

Use agentes quando:

• O problema é aberto (você não sabe os passos de antemão)
• Precisa de adaptação (o próximo passo depende do resultado anterior)
• Ferramentas variadas são necessárias

Caso contrário, você está usando uma britadeira pra pendurar um quadro.

TL;DR

• Agent loop: agir → observar → decidir → repetir. Isso que separa agentes de chatbots.
• Tool calling: primitiva que permite agentes usarem funções reais em vez de alucinarem.
• Agent harness: toda a infraestrutura invisível (permissões, retry, logging, limites).
• Context engineering: informação certa na hora certa, não tudo de uma vez.
• MCP: protocolo pra padronizar como agentes falam com ferramentas.
• Agentic RAG: agente dirige a busca de informação, não só recebe resultado pronto.
• Multi-agente: vários agentes especializados coordenados por um orchestrator.
• HITL: aprovação humana antes de ações críticas. Sempre.
• Evals: testes automatizados pra garantir que o agente ainda funciona.
• Computer use: agente controla UI visual quando não tem API.
• Regra de ouro: se dá pra resolver sem agente, resolva sem agente.