Agent Harness: Sandbox Interno vs. Externo para Agentes de IA

Lucas Moraes (CEO Toolzz AI)
17 de abril de 2026

Em um mundo onde agentes de IA estão transformando a maneira como empresas operam, a arquitetura subjacente desses agentes é crucial. O 'agent harness' – o loop que impulsiona um LLM, enviando prompts, executando ferramentas e repetindo até a conclusão – é um componente fundamental. A questão não é se um agente tem um harness, mas onde ele é executado. Existem duas abordagens principais: dentro do sandbox ou fora do sandbox, cada uma com suas próprias vantagens e desvantagens, especialmente quando se trata de implantações multiusuário.

As Duas Arquiteturas

Harness Dentro do Sandbox

Nesta arquitetura, o loop do agente reside no mesmo container que o código que está sendo executado. As chamadas para LLMs são feitas de dentro do container, e as chamadas para ferramentas (como comandos bash, leitura ou escrita de arquivos) são executadas localmente. Habilidades, memórias e qualquer outro dado rastreado pelo harness são armazenados como arquivos no sistema de arquivos do container. Esta é a abordagem comum quando você executa um LLM localmente no seu laptop, ou ao utilizar soluções como o Claude Code em um container remoto. É um ponto de partida fácil para agentes de usuário único.

Harness Fora do Sandbox

Em contraste, o loop roda no seu backend. Quando precisa executar uma ferramenta, ele faz uma chamada a um sandbox via API. O sandbox executa a ferramenta e retorna o resultado. O loop nunca entra diretamente no sandbox. Esta arquitetura oferece um controle de segurança e gerenciamento aprimorado, algo crucial para implantações em larga escala.

Tradeoffs

Executar o harness dentro do sandbox oferece simplicidade. O modelo de execução é direto: um container, uma árvore de processos, um sistema de arquivos e um ciclo de vida unificado. Você pode reutilizar harnesses pré-construídos sem modificações significativas. Habilidades e memórias funcionam como esperado, pois assumem um sistema de arquivos local.

No entanto, a arquitetura fora do sandbox desbloqueia recursos que a abordagem interna não consegue igualar. Suas credenciais permanecem seguras fora do sandbox. O loop detém as chaves de API LLM, os tokens de usuário e o acesso ao banco de dados, enquanto o sandbox contém apenas o ambiente necessário para a execução da tarefa. Isso elimina o risco de fugas de credenciais e simplifica o modelo de permissões.

Além disso, você pode suspender o sandbox quando o agente não estiver em uso, otimizando o consumo de recursos. Muitos agentes não precisam de um sandbox o tempo todo; tarefas como pensar, fazer chamadas de API ou resumir não exigem um ambiente isolado. Com o harness externo, você provisiona um sandbox apenas quando necessário e o suspende quando estiver ocioso. Isso é impossível com o harness interno.

Sandboxes tornam-se recursos efêmeros e substituíveis. Se um sandbox falhar durante uma sessão, o loop provisiona um novo sem interrupção. Com o harness dentro do sandbox, a perda do sandbox significa a perda da sessão.

E, para organizações que compartilham o mesmo agente entre múltiplos engenheiros, a arquitetura externa transforma a gestão de dados em um problema de banco de dados compartilhado, em vez de um problema complexo de sistema de arquivos distribuído.

Por outro lado, adaptar harnesses pré-construídos para fora do sandbox exige esforço, pois eles geralmente assumem um sistema de arquivos local. A execução duradoura se torna sua responsabilidade, pois as sessões de agente podem durar horas e precisam sobreviver a implantações. E, uma vez que o harness e o sandbox residem em máquinas diferentes, o conceito de 'sistema de arquivos' deixa de ser uma entidade física e precisa ser abstraído.

Na Toolzz, optamos pelo modelo externo, e as próximas seções detalham as soluções que implementamos para superar seus desafios. Se você busca entender como implementar essa arquitetura em sua empresa, conheça a Toolzz AI e suas soluções inovadoras.

Execução Duradoura

Um loop de agente é uma função de longa duração. Mantê-lo em memória em um servidor de API é inviável, pois ele morre na primeira implantação de uma nova versão. Precisamos de uma maneira de garantir a persistência do estado do agente durante todo o ciclo de vida da operação.

Já utilizávamos o Inngest para nossa pipeline de ingestão de CI, e decidimos estendê-lo para o loop do agente. A Inngest oferece uma excelente experiência de desenvolvimento, não exige que executemos nosso próprio cluster e atende às nossas necessidades sem a complexidade total do Temporal. O loop do agente é implementado como uma função Inngest, onde cada iteração é um passo e a Inngest faz o checkpoint de cada passo. Em caso de reinício do servidor, o loop retoma de onde parou.

Ciclo de Vida do Sandbox

O loop do agente está suspenso na maior parte do tempo: durante chamadas para LLMs, entre chamadas para ferramentas e durante a espera por workflows de longa duração, como CI. Desejamos que o sandbox também esteja suspenso quando o agente não estiver executando um comando, ativando-o apenas quando necessário. O problema é o tempo de inicialização a frio, que pode levar segundos – um tempo inaceitável em interações em tempo real.

Utilizamos o Blaxel para resolver este problema. O Blaxel nos oferece um tempo de retomada de 25ms a partir do modo de espera. Suspendemos o sandbox quando o agente não está executando um comando e o reativamos instantaneamente quando necessário. 25ms é tão baixo que o agente não percebe que o sandbox foi suspenso e reativado.

O Sistema de Arquivos

Harnesses de agente modernos não se limitam a comandos bash e LLMs. Eles utilizam habilidades (fragmentos de prompt que o agente lê sob demanda), memórias (anotações que o agente escreve para si ou para o usuário), subagentes, planos e listas de tarefas. Todos esses componentes assumem um sistema de arquivos local. Uma habilidade pode ser um arquivo em .claude/skills/foo.md, uma memória em .claude/memory/MEMORY.md. O harness lê e escreve esses arquivos usando as mesmas ferramentas que usa para o código fonte.

Isso funciona bem em um laptop, mas não quando o harness está fora do sandbox.

O sandbox é descartável. Tratamos-o como efêmero: suspenso, retomado, finalizado e reiniciado. Se ele falhar, qualquer coisa que o agente tenha escrito em .claude/memory/MEMORY.md se perde. Manter um sandbox de longa duração por sessão para preservar o estado é uma opção, mas isso anula os benefícios da arquitetura externa.

O outro problema é o multiusuário. Um laptop executa um agente para uma pessoa. Nosso agente executa para dezenas de engenheiros na mesma organização. Habilidades são organizacionais: todos em uma equipe compartilham o mesmo playbook de triagem. Memórias também. Se o agente aprender na segunda-feira que a equipe X sempre implanta de um branch de lançamento, a sessão de terça-feira de um engenheiro diferente na mesma equipe deve saber disso.

Você poderia simular um sistema de arquivos, escrever nele e sincronizar tudo com um banco de dados ao sair. Isso funciona no caso de usuário único, mas no multiusuário, você acaba com um problema de sistema de arquivos distribuído. Duas sessões em execução simultânea escrevem no mesmo arquivo de memória, e você precisa reconciliá-las. Três engenheiros acionam o agente no mesmo incidente, e todos veem estados desatualizados até que suas sessões terminem. Resolução de conflitos, consistência eventual, invalidação de cache.

A solução elegante é parar de fingir. Coloque memórias e habilidades em um banco de dados. O harness as lê quando o agente as solicita e as grava quando o agente as atualiza.

Uma Interface, Dois Backends

O harness virtualiza o acesso ao sistema de arquivos. O agente tem uma única ferramenta read, write e edit. Quando o agente as chama, o harness examina o caminho e roteia a chamada com base no significado do caminho.

Caminhos sob o workspace vão para o sandbox, como sempre. Caminhos sob os namespaces de habilidade e memória vão para o banco de dados. Uma gravação em um caminho de memória é uma transação de banco de dados, com escopo para a organização. Uma leitura de um caminho de memória também vem do banco de dados, para que duas sessões paralelas na mesma organização vejam a mesma memória instantaneamente após ser gravada.

O agente não sabe a diferença. Do ponto de vista dele, existe um sistema de arquivos e ele lê e grava arquivos. Alguns desses arquivos residem no Postgres, outros em um sandbox executado em outro estado.

Por que não apenas adicionar ferramentas?

A alternativa óbvia é dar ao agente ferramentas memory_read e memory_write ao lado de read e write. Isso funciona, e é o que a maioria das pessoas faz. Nós também fazíamos antes de termos a camada de virtualização.

O problema é que mais ferramentas prejudicam os agentes. Cada ferramenta dilui a atenção que o modelo presta a cada outra ferramenta, torna o prompt mais longo e adiciona outra decisão que o modelo deve tomar a cada iteração. Duas ferramentas que fazem quase a mesma coisa, read e memory_read, são especialmente ruins, pois o modelo deve diferenciá-las pelo contexto e às vezes escolhe a errada.

A outra razão é mais importante. A Anthropic e todos que treinam modelos de ponta quase certamente estão fazendo aprendizado por reforço em harnesses que se parecem com o Claude Code. Esse treinamento molda os modelos para serem bons em uma superfície de API específica: read(path), write(path, conteúdo), edit(path, antigo, novo). Se você inventar memory_read, você está fora do caminho treinado. Você obtém o que o modelo aprendeu em geral, menos o que ele aprendeu sobre as convenções exatas em que foi treinado.

A interface virtualizada mantém a superfície de API em que o modelo foi treinado e coloca a semântica do banco de dados onde precisamos no backend.

O Que Ainda É Difícil

O estado da arte evolui rapidamente. A cada poucas semanas, um novo padrão (subagentes, planos, tarefas de fundo) surge no Claude Code ou em algum lugar similar, e quase sempre assume um sistema de arquivos local. Podemos interceptar a maioria das coisas, mas sempre há uma lacuna entre um novo recurso ser lançado e nossa camada de virtualização lidar com ele corretamente. Não rodar o Claude Code padrão é um custo real.

Escolhemos prefixos de caminho (/skills/, /memory/) que espelham o layout local do Claude Code, e isso provavelmente vai nos prejudicar. O layout do Claude Code ainda está evoluindo e estamos a uma mudança de convenção de distância de ter que migrar tudo. A resposta correta pode ser expor uma interface completamente diferente. Mas, como mencionado anteriormente, o objetivo era manter a interface idêntica ao que o modelo foi treinado.

Bash é um vazamento. O harness pode interceptar read('/skills/foo.md') porque é uma chamada de ferramenta estruturada. Mas o agente também tem uma ferramenta bash, e nada impede que ele execute grep -r 'foo' /skills/ em uma sessão bash. Bash ignora a camada de virtualização e atinge o sistema de arquivos real do sandbox, onde /skills/ não existe. Tratamos isso com duas proteções melhores: o prompt do sistema diz ao agente para não usar bash para namespaces virtualizados e analisamos invocações bash com tree-sitter para detectar chamadas que alcançam esses caminhos. Nenhum deles é infalível. É bom o suficiente por enquanto.

Consistência é a parte que ainda não resolvemos. Quando duas sessões na mesma organização estão ambas atualizando a memória, o que elas devem ver? Serializabilidade estrita é tentadora e provavelmente errada, porque agentes não são bancos de dados e fazer uma sessão bloquear na gravação da outra abre padrões de deadlock para os quais não temos respostas. Estamos executando o último gravador por chave, o que é bom para os casos que encontramos e quase certamente vai quebrar de maneiras que podemos prever.

Estamos construindo a Toolzz (YC W26). Passamos uma década construindo e dimensionando sistemas de CI no Docker e Dagger, e o trabalho sempre se transformou em investigações longas e baseadas em estado que abrangem horas e vários engenheiros. Agentes são a forma certa para esse trabalho, mas o harness subjacente a eles realmente precisa suportá-lo.

Para empresas que buscam otimizar o atendimento ao cliente e automatizar tarefas complexas, a Toolzz oferece soluções de Agentes de IA personalizadas. Nossos agentes de voz e chatbots são projetados para lidar com uma ampla gama de casos de uso, desde suporte técnico até prospecção de vendas. Explore como a Toolzz pode transformar seus processos de negócios com inteligência artificial.

Pronto para elevar a eficiência da sua equipe com Agentes de IA? Conheça a Toolzz e descubra como podemos impulsionar seus resultados.