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 minha compreensão das camadas subjacentes dos Agentes não era profunda o suficiente. Combinado com a experiência significativa da nossa equipe em implementar soluções de negócio baseadas em Agentes, senti a necessidade de uma revisão sistemática. Então, revisei materiais, implementações open-source 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 multiagente, avaliação, tracing 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 divergiram 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 do 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. Funcionamento Básico do Loop do Agente

A lógica central de implementação 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 subagentes, compressão de contexto e carregamento de skills, o loop principal raramente muda. Novas capacidades geralmente são adicionadas externamente ao loop, em vez de modificar seu interior.

Novas capacidades são integradas principalmente de três maneiras: estendendo conjuntos de ferramentas e handlers, ajustando estruturas de system prompt 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 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 Agent?

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 Agent. A diferença central é quem detém o controle. Na realidade, muitos produtos rotulados como Agents 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 Agent; combinar alguns desses padrões é suficiente. O segredo é qual design se adequa à tarefa.

1. 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. 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. 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. Orchestrator-Workers: Um LLM central decompõe tarefas dinamicamente e as delega a LLMs workers, depois sintetiza os resultados. Este é o protótipo para a ferramenta spawn do nanobot e o modo subagente do learn-claude-code.
5. 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 se refere à infraestrutura de teste, verificação e restrição construída em torno de um Agent. 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 frequentemente 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 Agent-First 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. Conteúdo que o Agent não pode ver não existe: O conhecimento deve existir no próprio código-fonte. Documentos externos são invisíveis para um Agent 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 tipos ou regras de CI são executáveis. O分层 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. Agents verificam ativamente logs, métricas e traces.
4. Minimize o atrito de merge: Lidere com falhas de teste intermitentes com novas tentativas em vez de bloquear o progresso. Em ambientes de alto throughput, 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 ao Codex. UI Journeys também são entradas. Essa pilha de observabilidade é criada por tarefa e destruída após a conclusão. O Agent 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 da verificação para dividir as tarefas em quatro estados. O canto superior direito (objetivos claros, verificação automatizada) é a zona ideal para Agents. 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 Agents 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 do Contexto", onde o conteúdo irrelevante domina o contexto, fazendo com que a qualidade da decisão do Agent caia. 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 curto, firme e executável.
• Carregamento Sob Demanda: Skills 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 gravada em MEMORY.md. Não diretamente no system prompt; lido apenas quando necessário.
• Camada de Sistema: Hooks ou regras de código para lógica determinística. Fica 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 de Compressão Comuns

1. Sliding Window: Descarta mensagens antigas. Baixo custo, mas perde o contexto inicial. Bom para bate-papos curtos.
2. LLM Summary: O modelo gera um resumo. Custo médio, perde detalhes, mas mantém as decisões. Bom para tarefas longas.
3. Tool Result Replacement: Substitui a saída bruta por placeholders. Baixo custo, bom para tarefas com muitas ferramentas.

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

Prompt Caching 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 amigável ao cache centra-se na estabilidade: system prompts, 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 skills também ajuda, anexando conteúdo após o prefixo estável. Um ponto contraintuitivo: um system prompt grande e estável pode ser mais barato do que um pequeno que muda com frequência, porque o desconto de 90% nas leituras subsequentes supera o custo inicial da gravação.

Por Que Carregar Skills Sob Demanda?

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

1const systemPrompt = `
2Available Skills:
3- deploy: Processo completo de deploy em produção
4- code-review: Checklist de revisão de código
5- git-workflow: Estratégia de branches 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 skills 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 system prompt 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 skill têm duas armadilhas. Primeiro, contagem de palavras: descrições longas para cada skill se acumulam. 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 skills de alta frequência no prompt permanente. Skills de baixa frequência podem ser introduzidas manualmente ou mantidas como docs. Antipadrões típicos incluem enfiar centenas de linhas de manuais em uma skill ou fazer uma skill cobrir muitas tarefas distintas (revisão, deploy, depuração).

O que a Compressão Perde com Mais Facilidade?

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 reobteríveis. Saídas de ferramentas vão primeiro, mas as decisões arquiteturais e caminhos de falha relacionados frequentemente desaparecem também. Defina explicitamente as prioridades de retenção em CLAUDE.md:

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

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

Por Que os Sistemas de Arquivos São Ótimas Interfaces de Contexto

A Cursor chama isso de "Dynamic Context Discovery": dê menos por padrão, leia quando necessário. Sistemas de arquivos são interfaces naturais. Chamadas de ferramentas frequentemente retornam JSON massivo; em vez de colocá-lo no contexto, escreva-o em um arquivo. O Agent 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. Agents veem apenas nomes de ferramentas por padrão e consultam 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 Agent precisar de detalhes, ele pode recuperá-los do arquivo, tornando a compressão uma operação lossy, 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 simplesmente encapsuladas como ferramentas. Mais tarde, descobriu-se que os erros de seleção eram frequentemente devidos a ferramentas projetadas para engenheiros, não para Agents.

1ª Geração: API Wrapping: Cada endpoint é uma ferramenta. Muito granular; Agents precisam coordenar múltiplas ferramentas para um objetivo.

2ª Geração: ACI (Agent-Computer Interface): Ferramentas correspondem aos objetivos do Agent, não a APIs de baixo nível. Em vez de create_file e set_permissions, forneça create_script(path, content, executable).

3ª Geração: Advanced Tool Use: Otimizando descoberta e chamada:

• Tool Search: Não coloque todas as definições de uma vez. Agents encontram definições via search_tools. A retenção de contexto chega a 95%.
• Programmatic Tool Calling: Deixe o modelo usar código para orquestrar múltiplas chamadas. Resultados intermediários ficam no ambiente de execução, não no contexto do LLM. Os tokens podem cair de 150.000 para 2.000.
• Tool Use Examples: Cada ferramenta recebe de 1 a 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 Agents diretamente. Não é apenas "pode ser chamada", mas "pode se autocorrigir se chamada errada?"

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, omita 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});

O design ruim apenas diz o que faz, não quando usá-lo. O bom design ACI tem limites claros e erros estruturados, ajudando os Agents 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 (user, assistant, tool_result) para o LLM.

5. Projetando o Sistema de Memória

Os Agents 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:

• Context Window (Working Memory): Informações mínimas para a tarefa atual. Tokens limitados; deve ser gerenciada.
• Skills (Procedural Memory): Como fazer as coisas (fluxos de trabalho, normas). Carregadas sob demanda.
• JSONL Session History (Episodic Memory): O que aconteceu. Persistido em disco; pesquisável.
• MEMORY.md (Semantic Memory): Fatos estáveis escritos pelo Agent. Injetados em system prompts.

Como MEMORY.md e Skills Colaboram

O cerne é manter fatos importantes enquanto se 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 Agents, Markdown estruturado + pesquisa por palavra-chave é suficiente para depuração e custo.

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

Quando tokenUsage / maxTokens >= 0,5, acione a consolidação. Resuma as mensagens, anexe a MEMORY.md e atualize o índice. Se falhar, escreva as mensagens brutas em um arquivo morto. O processo deve ser reversível; mova ponteiros, não delete 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 múltiplas 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 o Estado da Tarefa Explicitamente?

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

1{
2  "tarefas": [
3    {"id": "1", "desc": "Ler config", "status": "concluida"},
4    {"id": "2", "desc": "Modificar schema", "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 resultados via uma fila de notificação antes da próxima chamada LLM. Isso é mais sustentável do que um runtime async complexo.

7. Organizando Sistemas Multiagente

A engenharia de sistemas multiagente trata de isolamento e colaboração.

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

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

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

Para Que Servem os Subagentes?

Pesquisa e tentativa e erro não devem poluir o contexto do Agent principal. O Agent 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 Agents esquecem promessas. Use um protocolo estruturado:

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

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

Alucinações se Amplificam em Sistemas Multiagente

Erros em cascata entre Agents. A validação cruzada quebra essa corrente, fazendo com que um Agent independente ou feedback externo (testes, compiladores) julgue a conclusão.

8. Como Avaliar Agents

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 do Agent requer ferramentas e ambientes. A pontuação é baseada no que aconteceu no ambiente, não apenas no que o Agent disse.

Conceitos-chave: Task, Trial, Grader. Transcript (log de execução) vs Outcome (estado final). Você precisa de ambos. Um Agent pode dizer "ingresso reservado" (transcript), mas falhar ao criar o registro no banco de dados (outcome).

Status e Métricas de Avaliação

Muitas equipes ainda dependem de revisão manual ou juízes LLM. Métricas comuns: Pass@k (pode 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: Juízes LLM baseados 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. 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 rastreamentos, 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 Rastreamento?

Prompt completo, mensagens de múltiplas rodadas, chamadas de ferramentas/args/retornos, 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 rastreamentos 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), Conjuntos de Ferramentas (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 do Sistema em Camadas

SOUL.md define identidade e padrões de conclusão. Os prompts são em camadas: Informações de tempo de execução -> 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: Mude automaticamente de provedor (Anthropic -> OpenAI) se um falhar.

11. Anti-Padrões Comuns

1. Prompt do 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 multiagentes 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 (Operacional, Procedimental, Episódica, Semântica).
6. Tarefas longas dependem de estado e arquivos externalizados.
7. Sistemas multiagentes precisam de protocolos e isolamento.
8. Avaliação Pass@k para capacidade, Pass^k para qualidade.
9. Rastreamento é o pré-requisito para depuração.
10. Agentes estáveis dependem de detalhes de engenharia como desacoplamento e limites de segurança.