Agent Harness: Dentro ou Fora da Sandbox? Guia para Agentes de IA

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

Com a crescente adoção de agentes de IA para automatizar tarefas complexas, a arquitetura subjacente que os impulsiona se torna crucial. Um "agent harness" é o loop que alimenta um LLM, gerenciando prompts, respostas, execuções de ferramentas e feedback contínuo. A principal questão é onde esse harness opera: dentro ou fora de uma "sandbox". Essa escolha impacta diretamente a segurança, a capacidade de resposta a falhas e o potencial do agente. Vamos explorar as nuances de cada abordagem, especialmente no contexto de ambientes multiusuário.

As Duas Arquiteturas

Harness Dentro da Sandbox

Neste modelo, o loop de execução reside no mesmo container que o código que ele manipula. As chamadas para LLMs são feitas de dentro desse container, e as execuções de ferramentas (como comandos bash ou acesso a arquivos) acontecem localmente. Habilidades, memórias e outros dados relevantes são armazenados como arquivos no sistema de arquivos do container. Essa é a abordagem comum em ambientes de desenvolvimento locais, como ao usar o Claude Code em seu laptop, ou em containers remotos. Para desenvolvedores individuais, essa configuração oferece simplicidade e rapidez na implementação.

Harness Fora da Sandbox

Em contraste, o loop de execução opera no seu backend. Quando uma ferramenta precisa ser executada, uma chamada é feita para uma sandbox através de uma API. A sandbox executa a ferramenta e retorna o resultado, sem que o loop principal jamais entre nela. Essa arquitetura oferece maior controle e segurança, especialmente em ambientes colaborativos.

Tradeoffs

Executar o harness dentro da sandbox oferece simplicidade: um único container, um único processo, um único sistema de arquivos, um único ciclo de vida. É possível reutilizar harnesses prontos com facilidade, e as habilidades e memórias funcionam sem alterações, pois assumem um sistema de arquivos local.

Por outro lado, o harness fora da sandbox desbloqueia funcionalidades que a abordagem interna não permite. Suas credenciais permanecem seguras no backend, longe da sandbox. O loop armazena chaves de API, tokens de usuário e acesso ao banco de dados, enquanto a sandbox contém apenas o ambiente necessário para a execução das tarefas. Isso elimina o risco de fuga de credenciais e simplifica o modelo de permissões.

Além disso, a sandbox pode ser suspensa quando não está em uso, economizando recursos. Uma grande parte do tempo de um agente é gasta em tarefas que não exigem uma sandbox, como raciocínio, chamadas de API, resumo ou espera por processos de CI. Com o harness externo, a sandbox é provisionada apenas quando necessário e suspensa quando o agente está inativo. Essa otimização é impossível quando o harness reside dentro da sandbox.

Sandboxes se tornam recursos gerenciáveis. Se uma sandbox falhar durante uma sessão, uma nova é provisionada automaticamente, garantindo a continuidade do processo. Em ambientes multiusuário, compartilhar habilidades e memórias se torna mais fácil. Em vez de lidar com um sistema de arquivos distribuído, é possível usar um banco de dados compartilhado para armazenar e acessar informações de forma consistente.

Está pensando em implementar Agentes de IA na sua empresa? Conheça a Toolzz e descubra como podemos te ajudar a otimizar seus processos.

No entanto, migrar para uma arquitetura externa exige superar alguns desafios. Harnesses locais prontos para uso podem não funcionar, e a execução durável se torna sua responsabilidade, pois uma sessão de agente pode durar horas e deve sobreviver a implantações. Além disso, o conceito de "sistema de arquivos" se torna abstrato, pois o harness e a sandbox residem em máquinas diferentes.

Nossa Escolha: Fora da Sandbox

Optamos pela arquitetura externa devido aos benefícios em termos de segurança, escalabilidade e gerenciamento de recursos. Para tornar essa abordagem viável, precisamos resolver três desafios principais:

Execução Durável

Um loop de agente é uma função de longa duração, que pode durar minutos ou até horas. Ele precisa sobreviver a implantações contínuas, eventos de escalabilidade e falhas de instância. Manter o loop na memória de um servidor API não é uma solução, pois ele morre na primeira nova versão.

Utilizamos o Inngest para garantir a execução durável. Cada etapa do loop é um evento, e o Inngest faz o checkpoint de cada etapa. Se o servidor reiniciar, o loop retoma de onde parou. Essa solução oferece boa experiência de desenvolvimento, sem a necessidade de gerenciar um cluster.

Ciclo de Vida da Sandbox

O loop fica inativo a maior parte do tempo, durante chamadas de LLM, entre execuções de ferramentas e durante a espera por fluxos de trabalho de CI. Queremos que a sandbox também seja suspensa quando o agente não estiver executando comandos, e retomada instantaneamente quando necessário. O problema é o tempo de inicialização a frio, que pode levar segundos, o que é inaceitável em interações em tempo real.

Implementamos essa funcionalidade com o Blaxel, que oferece retomada da sandbox em 25ms a partir do modo de espera. A sandbox é suspensa quando o agente não está executando um comando e retomada no momento em que é necessário. Essa latência é tão baixa que o agente não percebe a suspensão e retomada da sandbox.

O Sistema de Arquivos

Os harnesses 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 mesmo ou para o usuário), subagentes, planos e listas de tarefas. Todos esses componentes assumem um sistema de arquivos local.

Isso funciona bem em um laptop, mas não em uma arquitetura onde o harness está fora da sandbox.

A sandbox é descartável e deve ser tratada como efêmera. Se ela morrer e uma nova for iniciada, qualquer dado gravado em .claude/memory/MEMORY.md se perderá. Manter uma sandbox de longa duração por sessão seria uma solução, mas isso anularia os benefícios da arquitetura externa.

Para resolver esse problema, movemos as memórias e habilidades para um banco de dados. O harness as lê do banco de dados quando o agente as solicita e as grava quando as atualiza.

Uma Interface Única, Dois Backends

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

Caminhos sob o workspace são direcionados para a sandbox através de RPC. Caminhos sob os namespaces de habilidades e memórias são direcionados para o banco de dados. Uma gravação em um caminho de memória é uma transação no banco de dados, escopo para a organização. Uma leitura de um caminho de memória também vem do banco de dados, garantindo que duas sessões paralelas na mesma organização vejam a mesma memória instantaneamente.

O agente não percebe a diferença. Para ele, existe um sistema de arquivos, e ele lê e grava arquivos. Alguns desses arquivos residem no Postgres, outros em uma sandbox executada em outro local.

O Que Ainda é Desafiador

O estado da arte evolui rapidamente. A cada poucas semanas, um novo padrão (subagentes, planos, tarefas em segundo plano) surge no Claude Code ou em plataformas similares, e quase sempre assume um sistema de arquivos local. Estamos constantemente nos adaptando a essas mudanças, mas sempre há um atraso entre o lançamento de uma nova funcionalidade e a sua implementação em nossa camada de virtualização.

Nossa escolha de prefixos de caminho (/skills/, /memory/) pode nos trazer problemas no futuro, pois o layout do Claude Code ainda está em evolução. A alternativa seria expor uma interface diferente, mas nosso objetivo é manter a compatibilidade com a API treinada.

O uso de bash representa um risco. O harness pode interceptar read('/skills/foo.md') porque é uma chamada de ferramenta estruturada, mas o agente também tem uma ferramenta bash, que pode ser usada para executar comandos como grep -r 'foo' /skills/, contornando a camada de virtualização. Mitigamos isso com avisos no prompt e análise de sintaxe bash, mas não é uma solução totalmente segura.

A consistência é o aspecto que ainda não foi totalmente resolvido. Quando duas sessões na mesma organização estão atualizando a memória simultaneamente, o que elas devem ver? A serialização estrita é tentadora, mas pode levar a bloqueios e deadlocks. Atualmente, estamos usando o modelo "último a escrever vence", que funciona bem nos casos que encontramos, mas pode falhar de maneiras previsíveis.

Estamos construindo a Toolzz (líder em Agentes de IA e Educação Corporativa). Nossa experiência em CI/CD nos levou a criar uma plataforma que suporta agentes de IA robustos e escaláveis. Se você busca otimizar seus processos com agentes de IA personalizados, a Toolzz AI oferece a solução ideal. Explore nossos Agentes AI de Suporte para revolucionar seu atendimento ao cliente ou utilize nossos Agentes AI de Vendas para impulsionar suas vendas.