O Agente que você não conhece: Princípios, Arquitetura e Práticas de Engenharia

0. TL;DR

Depois de escrever "O Claude Code Que Você Não Conhece: Arquitetura, Governança e Práticas de Engenharia", percebi que meu entendimento das camadas subjacentes dos Agentes não era profundo o suficiente. Combinado com a experiência significativa da nossa equipe na implementação de soluções de negócio baseadas em Agentes, senti a necessidade de uma revisão sistemática. Então, revisei materiais, implementações de código aberto e meu próprio código para organizar este artigo.

Este artigo foca nas partes da arquitetura de Agentes que mais impactam os resultados de engenharia, incluindo fluxo de controle, engenharia de contexto, design de ferramentas, memória, organização multi-agente, avaliação, rastreamento e segurança. Por fim, usaremos a implementação do OpenClaw para unir esses princípios de design.

Ao organizar isso, várias conclusões diferiram das minhas suposições iniciais: as melhorias trazidas por modelos mais caros são frequentemente menores do que o esperado; em vez disso, a qualidade do Harness e dos testes de verificação tem um impacto maior nas taxas de sucesso. Ao depurar o comportamento de um Agente, priorize a verificação das definições das ferramentas, pois a maioria dos erros de seleção de ferramentas decorre de descrições imprecisas. Além disso, problemas dentro do próprio sistema de avaliação são frequentemente mais difíceis de detectar do que bugs no Agente. Se você continua ajustando o código do Agente sem sucesso, a resposta pode estar nessas áreas.

1. Operação Básica do Loop do Agente

A lógica de implementação central de um Loop de Agente, quando abstraída, tem menos de 20 linhas de código:

1const messages: MessageParam[] = [{ role: "user", content: userInput }];
2
3while (true) {
4  const response = await client.messages.create({
5    model: "claude-opus-4-6",
6    max_tokens: 8096,
7    tools: toolDefinitions,
8    messages,
9  });
10
11  if (response.stop_reason === "tool_use") {
12    const toolResults = await Promise.all(
13      response.content
14        .filter((b) => b.type === "tool_use")
15        .map(async (b) => ({
16          type: "tool_result" as const,
17          tool_use_id: b.id,
18          content: await executeTool(b.name, b.input),
19        }))
20    );
21    messages.push({ role: "assistant", content: response.content });
22    messages.push({ role: "user", content: toolResults });
23  } else {
24    return response.content.find((b) => b.type === "text")?.text ?? "";
25  }
26}

O fluxo de controle correspondente é o seguinte: um ciclo contínuo de Percepção -> Decisão -> Ação -> Feedback até que o modelo retorne texto simples:

Tendo visto muitas implementações de Agentes e SDKs oficiais, as estruturas são semelhantes. O loop em si é bastante estável. Desde uma implementação mínima até o suporte a sub-agentes, compressão de contexto e carregamento de habilidades, o loop principal raramente muda. Novas capacidades são geralmente adicionadas fora do loop, em vez de modificar seu interior.

Novas capacidades são integradas principalmente de três maneiras: estendendo conjuntos de ferramentas e manipuladores, ajustando estruturas de prompt do sistema e externalizando o estado para arquivos ou bancos de dados. O corpo do loop não deve se tornar uma máquina de estado massiva. O modelo lida com o raciocínio, enquanto os sistemas externos lidam com o estado e os limites. Uma vez estabelecida essa divisão de trabalho, a lógica central do loop raramente precisa de ajustes frequentes.

Qual é a diferença entre Workflow e Agente?

A Anthropic faz uma distinção direta: um sistema onde o caminho de execução é pré-escrito em código é um Workflow; um sistema onde o LLM decide dinamicamente o próximo passo é um Agente. A diferença central é quem detém o controle. Na realidade, muitos produtos rotulados como Agentes estão mais próximos de Workflows, mas nenhum é inerentemente superior. O importante é encontrar a solução certa para a tarefa.

Observando em um diagrama, fica mais intuitivo:

Cinco Padrões de Controle Comuns

A maioria dos sistemas de IA, quando desmontados, são combinações desses cinco padrões. Muitos cenários não precisam de autonomia total do Agente; combinar alguns desses padrões é suficiente. O segredo é qual design se adequa à tarefa.

1. Encadeamento de Prompts (Prompt Chaining): As tarefas são divididas em etapas sequenciais, onde cada etapa do LLM processa a saída anterior. Pontos de verificação de código podem ser adicionados. Adequado para processos lineares, como tradução após geração ou escrita do corpo do texto após um esboço.
2. Roteamento (Routing): Classifica a entrada e a direciona para um processo especializado. Perguntas simples vão para modelos leves, complexas para modelos fortes; consultas de suporte técnico e faturamento seguem lógicas diferentes.
3. Paralelização (Parallelization): Duas variantes: Seccionamento (dividir tarefas em subtarefas independentes) e Votação (executar a mesma tarefa várias vezes para consenso). Adequado para decisões de alto risco ou necessidades de múltiplas perspectivas.
4. Orquestrador-Trabalhadores (Orchestrator-Workers): Um LLM central decompõe tarefas dinamicamente e as delega a LLMs trabalhadores, depois sintetiza os resultados. Este é o protótipo para a ferramenta spawn do nanobot e o modo sub-agente do learn-claude-code.
5. Avaliador-Otimizador (Evaluator-Optimizer): Um gerador produz saída, e um avaliador fornece feedback em um loop até que os padrões sejam atendidos. Adequado para tarefas como tradução ou escrita criativa, onde os padrões de qualidade são difíceis de definir precisamente em código.

Esses padrões resolvem como construir o fluxo de controle. Agora, vamos olhar para uma questão mais focada em engenharia: por que um sistema funciona de forma estável?

2. Por que o Harness é Mais Crítico que o Modelo

Um Harness refere-se à infraestrutura de teste, verificação e restrição construída em torno de um Agente. Um Harness inclui pelo menos quatro partes: linhas de base de aceitação, limites de execução, sinais de feedback e métodos de fallback.

Embora o modelo seja importante, essas condições periféricas de engenharia geralmente determinam se um sistema funciona de forma estável. Esse julgamento é mais verdadeiro para tarefas altamente verificáveis, como codificação, mas em tarefas de verificação fraca, como pesquisa aberta ou negociação em várias rodadas, o limite superior do modelo continua sendo mais crítico.

Prática de Desenvolvimento Focada em Agente da OpenAI

Três engenheiros escreveram um milhão de linhas de código em cinco meses com quase 1.500 PRs — 10x a velocidade do desenvolvimento tradicional. Essa velocidade não se deveu apenas à força do modelo; deveu-se a decisões corretas de engenharia:

1. O conteúdo que o Agente não pode ver não existe: O conhecimento deve existir na própria base de código. Documentos externos são invisíveis para um Agente em execução. O AGENTS.md é mantido com ~100 linhas como um índice, com detalhes divididos em diretórios docs para referência sob demanda.
2. Imponha restrições no código, não as documente: Normas em documentos são facilmente ignoradas. Restrições codificadas em Linters, sistemas de tipo ou regras de CI são executáveis. O particionamento arquitetural é imposto mecanicamente por Linters personalizados, não por revisão manual.
3. Conclusão autônoma de tarefas de ponta a ponta: Desde verificar o estado e reproduzir bugs até implementar correções e acionar a verificação do aplicativo, abrir PRs, lidar com revisões e fazer merge — toda a cadeia não requer intervenção humana. Os Agentes verificam ativamente logs, métricas e traces.
4. Minimize o atrito de merge: Lide com falhas intermitentes de teste com novas tentativas, em vez de bloquear o progresso. Em ambientes de alto rendimento, o custo de esperar pela revisão manual é frequentemente maior do que corrigir pequenos erros. A disciplina de codificação não desapareceu; ela mudou da revisão manual para restrições executadas por máquina.

O aplicativo distribui logs, métricas e traces via Vector para a camada de armazenamento Victoria, correspondendo às interfaces LogQL, PromQL e TraceQL. O Codex consulta, correlaciona e raciocina através dessas interfaces. Após as alterações, ele reinicia o aplicativo, reexecuta as cargas de trabalho e alimenta os resultados de volta para o Codex. UI Journeys também são entradas. Essa pilha de observabilidade é criada por tarefa e destruída após a conclusão. O Agente não espera ser informado sobre erros; ele consulta o estado do sistema para verificar as correções.

Qual é a Conclusão Chave para o Harness?

O diagrama usa clareza da tarefa e automação de verificação para dividir as tarefas em quatro estados. O canto superior direito (objetivos claros, verificação automatizada) é a zona ideal para Agentes. O canto superior esquerdo (tarefa clara, mas revisão manual) é limitado pela velocidade da revisão humana. O canto inferior direito (feedback automatizado, mas objetivos vagos) leva a um movimento eficiente na direção errada. O canto inferior esquerdo (falta de ambos) torna os Agentes inúteis.

O trabalho do Harness é empurrar as tarefas para o canto superior direito, garantindo que o certo e o errado sejam julgados por padrões executáveis por máquina, e não por olhos humanos.

3. Por que a Engenharia de Contexto Determina a Estabilidade

A complexidade da atenção do Transformer é O(n²). Quanto mais longo o contexto, mais fácil é para os sinais chave serem diluídos pelo ruído. Um modo de falha comum é a "Podridão de Contexto", onde o conteúdo irrelevante domina o contexto, fazendo com que a qualidade da decisão do Agente se deteriore. Muitos problemas que parecem ser incapacidade do modelo são, na verdade, devido à má organização do contexto.

Por que Camadas de Contexto?

O problema geralmente não é que a janela não seja longa o suficiente, mas que a densidade da informação está errada. Carregar itens raramente usados toda vez ou misturar regras estáveis com estados dinâmicos torna mais difícil para o modelo perceber o que é útil.

A solução é organizar a informação em camadas por frequência e estabilidade:

• Camada Permanente: Identidade, convenções do projeto, proibições absolutas. Conteúdo que deve valer para cada sessão. Mantenha-o curto, firme e executável.
• Carregamento Sob Demanda: Habilidades e conhecimento de domínio. Mantenha os descritores permanentes, mas injete o conteúdo completo apenas quando acionado.
• Injeção em Tempo de Execução: Informações dinâmicas como hora atual, ID do canal, preferências do usuário. Injetado por rodada conforme necessário.
• Camada de Memória: Experiência entre sessões escrita no MEMORY.md. Não está diretamente no prompt do sistema; lido apenas quando necessário.
• Camada de Sistema: Hooks ou regras de código para lógica determinística. Permanece completamente fora do contexto.

Não coloque lógica determinística no contexto. Qualquer coisa que possa ser expressa via Hooks, regras de código ou restrições de ferramentas deve ser tratada por sistemas externos.

Três Estratégias Comuns de Compressão

1. Janela Deslizante (Sliding Window): Descarta mensagens antigas. Baixo custo, mas perde o contexto inicial. Bom para conversas curtas.
2. Resumo do LLM (LLM Summary): O modelo gera um resumo. Custo médio, perde detalhes, mas mantém decisões. Bom para tarefas longas.
3. Substituição de Resultado de Ferramenta (Tool Result Replacement): Substitui a saída bruta por placeholders. Baixo custo, bom para tarefas com muitas ferramentas.

Janelas deslizantes são as mais fáceis, mas perdem o contexto inicial. Resumos avançados de LLM usam "sumarização de ramificação", preservando explicitamente decisões arquiteturais, tarefas inacabadas e restrições chave. Na substituição de ferramentas, o micro_compact substitui saídas antigas de ferramentas a cada rodada, enquanto o auto_compact é acionado quando o contexto excede um limite.

Cache de Prompt para Reduzir Sobrecarga Redundante

A inferência do LLM calcula pares Chave-Valor para cada token. Se um prefixo corresponder exatamente a uma solicitação anterior, ele é lido do cache. O cache requer correspondência exata de prefixo. O design favorável ao cache centra-se na estabilidade: prompts do sistema, definições de ferramentas e documentos longos são estáveis e adequados para cache. Informações dinâmicas (hora, entrada, resultados de ferramentas) devem ser colocadas no final.

Isso se relaciona com a organização em camadas do contexto. Quanto mais estável a camada permanente, maior a taxa de acerto do cache e menor o custo marginal. "Curto e estável" não é apenas para economizar tokens; protege o cache. O carregamento atrasado de habilidades também ajuda, anexando conteúdo após o prefixo estável. Um ponto contraintuitivo: um prompt de sistema grande e estável pode ser mais barato do que um pequeno que muda frequentemente, porque o desconto de 90% nas leituras subsequentes supera o custo inicial de escrita.

Por que Carregar Habilidades Sob Demanda?

Habilidades são um padrão eficaz: mantenha apenas o índice no prompt do sistema, carregue o conhecimento completo conforme necessário.

1const systemPrompt = `
2Habilidades Disponíveis:
3- deploy: Processo completo de implantação em produção
4- code-review: Lista de verificação de revisão de código
5- git-workflow: Estratégia de branch e normas de PR
6`;
7
8async function executeLoadSkill(name: string): Promise<string> {
9  return fs.readFile(`./skills/${name}.md`, "utf-8");
10}

As descrições das habilidades devem ser curtas para evitar inchaço de tokens e devem atuar como condições de roteamento. Explique quando usar, quando NÃO usar e qual é a saída. Use "Use quando / Não use quando" com exemplos negativos. Muitas falhas de roteamento são devidas a limites pouco claros, não à capacidade do modelo. O prompt do sistema deve esclarecer as regras: verificar available_skills antes de cada resposta, carregar o SKILL.md específico em caso de correspondência e carregar apenas um de cada vez.

Os dados são claros: sem exemplos negativos, a precisão cai de 73% para 53%; adicioná-los a eleva para 85% e reduz o tempo de resposta em 18,1%. Exemplos negativos são fundamentais.

Os descritores de habilidades têm duas armadilhas. Primeiro, contagem de palavras: descrições longas para cada habilidade somam. Segundo, precisão: "ajudar com o backend" é muito vago. Descritores eficazes são condições de roteamento, não introduções de recursos. "Quando me usar" é mais importante do que "O que posso fazer".

Controle a quantidade: mantenha apenas habilidades de alta frequência no prompt permanente. Habilidades de baixa frequência podem ser introduzidas manualmente ou mantidas como documentos. Antipadrões típicos incluem enfiar centenas de linhas de manuais em uma habilidade ou ter uma habilidade cobrindo muitas tarefas distintas (revisão, implantação, depuração).

O que a Compressão Perde Mais Facilmente?

O problema mais comum não é que o resumo seja muito longo, mas que a prioridade de retenção está errada. Os LLMs frequentemente deletam informações que parecem reobtíveis. As saídas das ferramentas vão primeiro, mas as decisões arquiteturais relacionadas e os caminhos de falha frequentemente desaparecem também. Defina explicitamente as prioridades de retenção no CLAUDE.md:

1### Instruções de Compactação: Como reter informações chave
2Prioridade:
31. Decisões arquiteturais (não resumir)
42. Arquivos modificados e alterações chave
53. Status de verificação (aprovado/reprovado)
64. TODOs não resolvidos e notas de reversão
75. Saída de ferramenta (pode deletar, manter apenas a conclusão de aprovado/reprovado)

Outra armadilha: não altere identificadores. UUIDs, hashes, IPs e nomes de arquivo devem ser preservados exatamente. Um caractere errado em um hash de commit quebra chamadas de ferramenta subsequentes.

Por que Sistemas de Arquivos são Ótimas Interfaces de Contexto

A Cursor chama isso de "Descoberta Dinâmica de Contexto": forneça menos por padrão, leia quando necessário. Sistemas de arquivos são interfaces naturais. Chamadas de ferramenta frequentemente retornam JSON massivo; em vez de colocá-lo no contexto, escreva-o em um arquivo. O Agente pode usar grep ou rg para ler conforme necessário. Isso mantém o contexto limpo e é legível para desenvolvedores.

A Cursor verificou isso com ferramentas MCP: elas sincronizam descrições de ferramentas para pastas. Os Agentes veem apenas os nomes das ferramentas por padrão e consultam as definições conforme necessário. Em testes A/B, isso reduziu o consumo total de tokens em 46,9%.

Isso também funciona para compressão de tarefas longas. Em vez de descartar o histórico, salve o log completo do chat em um arquivo e referencie o caminho no resumo. Se o Agente precisar de detalhes, ele pode recuperá-los do arquivo, tornando a compressão uma operação com perdas, mas rastreável.

4. O Design de Ferramentas Determina o que um Agente Pode Fazer

O contexto determina o que o modelo vê; as ferramentas determinam o que ele pode fazer. Qualidade supera quantidade. Apenas 5 servidores MCP podem custar ~55.000 tokens em definições — quase 30% de um contexto de 200K antes mesmo do chat começar. Muitas ferramentas diluem a atenção do modelo.

A maioria dos problemas com ferramentas não é ter poucas, mas escolher a errada, descrições incompreensíveis ou retornar dados inúteis.

Como o Design de Ferramentas Evolui

O design de ferramentas passou por três estágios. No início, as APIs existentes eram apenas encapsuladas como ferramentas. Mais tarde, descobriu-se que os erros de seleção eram frequentemente devidos a ferramentas projetadas para engenheiros, não para Agentes.

1ª Geração: Encapsulamento de API: Cada endpoint é uma ferramenta. Muito granular; os Agentes devem coordenar várias ferramentas para um objetivo.

2ª Geração: ACI (Interface Agente-Computador): As ferramentas correspondem aos objetivos do Agente, não às APIs de baixo nível. Em vez de create_file e set_permissions, forneça create_script(path, content, executable).

3ª Geração: Uso Avançado de Ferramentas: Otimizando descoberta e chamada:

• Pesquisa de Ferramentas (Tool Search): Não coloque todas as definições de uma vez. Os Agentes encontram definições via search_tools. A retenção de contexto atinge 95%.
• Chamada Programática de Ferramentas (Programmatic Tool Calling): Deixe o modelo usar código para orquestrar várias chamadas. Os resultados intermediários permanecem no ambiente de execução, não no contexto do LLM. Os tokens podem cair de 150.000 para 2.000.
• Exemplos de Uso de Ferramentas (Tool Use Examples): Cada ferramenta recebe 1-5 exemplos reais. O JSON Schema descreve os tipos, mas os exemplos mostram o uso. A precisão pode subir de 72% para 90%.

Princípios de Design de Ferramentas ACI

O design de ferramentas afeta os Agentes diretamente. Não se trata apenas de "pode ser chamada", mas de "pode se autocorrigir se chamada errado?"

Designs ruins têm parâmetros vagos e erros não corrigíveis. Designs bons usam betaZodTool para vincular definição e implementação, usando Zod para restrições de formato e sugestões de erro estruturadas:

1const updateTool = betaZodTool({
2  name: "update_yuque_post",
3  description: "Atualiza o conteúdo de um post do Yuque; não para criar novos posts",
4  inputSchema: z.object({
5    post_id: z.string().describe("ID do post do Yuque, string numérica como '12345678'"),
6    title: z.string().optional().describe("Título do post, omitir se não houver alteração"),
7    content_markdown: z.string().describe("Corpo em Markdown"),
8  }),
9  run: async (input) => {
10    const post = await getPost(input.post_id);
11    if (!post) throw new ToolError("O ID do post não existe", {
12      error_code: "POST_NOT_FOUND",
13      suggestion: "Chame list_yuque_posts primeiro para obter um post_id válido",
14    });
15    return await updatePost(input.post_id, input.title, input.content_markdown);
16  },
17});

Um design ruim apenas diz o que faz, não quando usá-lo. Um bom design ACI tem limites claros e erros estruturados, ajudando os Agentes a escolher corretamente e corrigir falhas rapidamente. Depure as ferramentas primeiro; a maioria dos erros está nas descrições, não na capacidade do modelo.

Por que Isolar Mensagens de Ferramentas?

Os frameworks geram eventos internos (compressão, notificações). Eles devem estar no histórico da sessão, mas não devem ser enviados ao LLM, pois desperdiçam tokens e confundem o modelo. A solução são dois tipos de mensagem: AgentMessage para a camada do aplicativo (com campos personalizados) e Message padrão (usuário, assistente, tool_result) para o LLM.

5. Projetando o Sistema de Memória

Os Agentes não têm continuidade temporal nativa. O contexto é limpo após uma sessão. Para alcançar consistência entre sessões, uma camada de memória deve ser projetada como infraestrutura, não como uma reflexão tardia.

Onde Vivem os Quatro Tipos de Memória?

Categorizados pelo problema que resolvem:

• Janela de Contexto (Memória de Trabalho): Informação mínima para a tarefa atual. Tokens limitados; deve ser gerenciada.
• Habilidades (Memória Processual): Como fazer as coisas (fluxos de trabalho, normas). Carregado sob demanda.
• Histórico de Sessão JSONL (Memória Episódica): O que aconteceu. Persistido em disco; pesquisável.
• MEMORY.md (Memória Semântica): Fatos estáveis escritos pelo Agente. Injetado em prompts do sistema.

Como MEMORY.md e Habilidades Colaboram

O núcleo é manter fatos importantes enquanto controla o volume de conteúdo.

Memória de 4 Camadas do ChatGPT: Estrutura simples. Metadados da Sessão (não persistidos), Memória do Usuário (~33 fatos, persistida/injetada), Resumo da Conversa (~15 resumos recentes, persistido), Sessão Atual (janela deslizante).

Recuperação Híbrida do OpenClaw: Logs diários (memory/YYYY-MM-DD.md), MEMORY.md para fatos selecionados e memory_search usando recuperação híbrida (70% similaridade vetorial + 30% palavra-chave). Para a maioria dos Agentes, Markdown estruturado + pesquisa por palavra-chave é suficiente para depurabilidade e custo.

Acionando e Revertendo a Consolidação de Memória

Quando tokenUsage / maxTokens >= 0,5, acione a consolidação. Resuma as mensagens, anexe ao MEMORY.md e atualize o índice. Se falhar, escreva as mensagens brutas em um arquivo morto. O processo deve ser reversível; mova os ponteiros, não delete os dados brutos.

6. Aumentando Gradualmente a Autonomia do Agente

A autonomia requer três peças de infraestrutura: retomada entre sessões, restrições de progresso dentro da sessão e E/S em segundo plano para tarefas lentas.

Como Continuar Tarefas Longas Entre Sessões

Tarefas longas falham quando as sessões terminam antes da conclusão. Uma abordagem estável usa um Agente Inicializador e um Agente de Codificação. O Inicializador é executado uma vez para criar feature-list.json, init.sh e claude-progress.txt. O Agente de Codificação então é executado em várias sessões, retomando desses arquivos, implementando um recurso, executando testes e atualizando o arquivo de progresso. Isso torna a tarefa um estado externo.

Mantenha o progresso em arquivos, não no contexto. Use JSON para estrutura. A tarefa só é concluída quando todos os recursos em feature-list.json estão com passes: true.

Por que Escrever Explicitamente o Estado da Tarefa?

Sem âncoras externas, os Agentes se desviam ou terminam prematuramente. Registre o estado como um objeto de controle externo:

1{
2  "tarefas": [
3    {"id": "1", "desc": "Ler configuração", "status": "concluída"},
4    {"id": "2", "desc": "Modificar esquema", "status": "em_andamento"}
5  ]
6}

Restrição: apenas um em_andamento por vez. Atualize o estado após cada etapa.

Integrando E/S em Segundo Plano

E/S lenta (operações de arquivo, rede) não deve bloquear o loop principal. Coloque subprocessos lentos em threads em segundo plano e injete os resultados via uma fila de notificação antes da próxima chamada do LLM. Isso é mais sustentável do que um runtime assíncrono complexo.

7. Organizando Sistemas Multi-Agente

A engenharia de sistemas multi-agente é sobre isolamento e colaboração.

Modo Diretor: Síncrono. Humano interage de perto com um Agente. O contexto é perdido quando a sessão termina.

Modo Coordenador: Delegação assíncrona. Humano define metas, Agentes trabalham em paralelo, humano revisa a saída. A saída torna-se artefatos persistentes (PRs, branches).

Um Orquestrador gerencia sub-agentes que trabalham em paralelo, comunicando-se via protocolos de caixa de entrada JSONL e usando Worktrees para isolamento.

Para que Servem os Sub-Agentes?

Pesquisa e tentativa e erro não devem poluir o contexto do Agente principal. O Agente principal só precisa da conclusão.

1const result = await runAgentLoop(tarefa, { messages: [] });
2return summarize(result); // O contexto principal vê apenas esta linha

Por que Escrever a Colaboração como um Protocolo?

A colaboração em linguagem natural falha à medida que os Agentes esquecem promessas. Use um protocolo estruturado:

1{ request_id, from_agent, to_agent, content, status: 'pendente', timestamp }

Use uma caixa de entrada JSONL somente anexação para recuperação de falhas. Isolamento primeiro, depois colaboração.

Alucinações se Amplificam em Sistemas Multi-Agente

Erros em cascata entre Agentes. A validação cruzada quebra essa cadeia, tendo um Agente independente ou feedback externo (testes, compiladores) para julgar a conclusão.

8. Como Avaliar Agentes

A avaliação requer casos de teste, padrões de pontuação e verificação automatizada.

A avaliação tradicional de turno único (Prompt -> Resposta) é insuficiente. A avaliação de Agentes requer ferramentas e ambientes. A pontuação é baseada no que aconteceu no ambiente, não apenas no que o Agente disse.

Conceitos chave: Tarefa, Tentativa, Avaliador. Transcrição (log de execução) vs Resultado (estado final). Você precisa de ambos. Um Agente pode dizer "ingresso reservado" (transcrição), mas falhar ao criar o registro no banco de dados (resultado).

Status e Métricas de Avaliação

Muitas equipes ainda dependem de revisão manual ou de avaliadores LLM. Métricas comuns: Pass@k (consegue teoricamente fazer?) e Pass^k (é estável para produção?). Não as misture.

Três Tipos de Avaliadores

1. Avaliadores de Código: Correspondência de strings, testes unitários. Maior certeza.
2. Avaliadores de Modelo: LLM julgam com base em critérios. Bom para qualidade semântica.
3. Avaliadores Humanos: Revisão de especialistas. Lento, mas estabelece a linha de base.

Construindo um Sistema de Avaliação do Zero

Comece com 20 a 50 casos reais de falha. Garanta o isolamento do ambiente para que os testes não se contaminem mutuamente. Inclua casos positivos e negativos. Se dois especialistas discordarem sobre um caso, os critérios ainda não estão claros.

Corrija a Avaliação Antes de Corrigir o Agente

Se as pontuações caírem, verifique primeiro o sistema de avaliação. Problemas de ambiente (limites de memória, bugs nos avaliadores) parecem degradação do modelo.

9. Rastreando o Processo de Execução

Sem rastros, as falhas não podem ser reproduzidas. Métricas APM (latência, taxa de erro) não são suficientes; você precisa da cadeia de raciocínio.

O que Registrar em um Rastro?

Prompt completo, mensagens de múltiplas rodadas, chamadas/args/retornos de ferramentas, cadeia de pensamento, saída final, tokens e latência.

Observabilidade em Duas Camadas

1. Amostragem Manual: Amostragem baseada em regras de erros ou feedback negativo para encontrar padrões de falha.
2. Autoavaliação LLM: Cobertura total dos rastros usando a camada manual como linha de base de calibração.

Fluxos de Eventos como Fundação

Emita eventos em tool_start, tool_end e turn_end. Sistemas downstream (logs, UI, avaliação) consomem esses eventos sem alterar o código do loop principal.

10. Implantando Agentes com OpenClaw

OpenClaw usa cinco camadas desacopladas: Gateway, Adaptadores de Canal, Pi Agent (loop principal), Toolsets (design ACI) e Contexto/Memória.

Desacoplamento do Barramento de Mensagens

Um Barramento de Mensagens separa os canais do Agente. Os canais lidam apenas com E/S; o Agente lida apenas com o processamento.

Prompts de Sistema em Camadas

SOUL.md define identidade e padrões de conclusão. Os prompts são em camadas: Informações de runtime -> Identidade -> Memória -> Habilidades -> Injeção dinâmica.

Limites de Segurança Primeiro

Antes de adicionar funcionalidades, estabeleça: Listas de Permissão de Usuário, Isolamento de Workspace (verificações de caminho) e Logs de Auditoria.

Proteção contra Injeção de Prompt: Trate o conteúdo externo como não confiável. Use separação fonte-destino. Não dê aos Agentes ferramentas que eles não precisam. Exija confirmação humana explícita para ações sensíveis.

Fallback de Provedor: Troque automaticamente de provedor (Anthropic -> OpenAI) se um falhar.

11. Anti-Padrões Comuns

1. Prompt de sistema como base de conhecimento (muito longo).
2. Proliferação de ferramentas (Agente escolhe ferramentas erradas).
3. Falta de loops de verificação.
4. Sistemas multiagente sem limites.
5. Sem consolidação de memória (qualidade cai após 20 rodadas).
6. Sem sistema de avaliação.
7. Complexidade multiagente prematura.
8. Confiar em expectativas em vez de restrições mecânicas.

12. Conclusão

1. O núcleo do agente é um loop estável; novas funcionalidades devem ser externalizadas.
2. O Harness determina a convergência mais do que o modelo.
3. A engenharia de contexto previne a "Deterioração do Contexto".
4. O design de ferramentas ACI foca em objetivos e correção de erros.
5. A memória é em camadas (Trabalho, Procedimental, Episódica, Semântica).
6. Tarefas longas dependem de estado e arquivos externalizados.
7. Sistemas multiagente precisam de protocolos e isolamento.
8. Avalie Pass@k para capacidade, Pass^k para qualidade.
9. O rastreamento é o pré-requisito para depuração.
10. Agentes estáveis dependem de detalhes de engenharia como desacoplamento e limites de segurança.