Agent Harness: Arquitetura Inside vs. Outside the Sandbox

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

Agentes de IA estão transformando a maneira como interagimos com sistemas complexos, automatizando tarefas e fornecendo insights valiosos. No coração de cada agente reside o agent harness, o loop que orquestra as interações com modelos de linguagem (LLMs) e ferramentas externas. A escolha de onde esse harness é executado – 'inside' ou 'outside the sandbox' – define suas capacidades, segurança e escalabilidade. Este artigo explora as nuances de cada abordagem, destacando os tradeoffs e as melhores práticas para implementações multiusuário.

As Duas Arquiteturas

A arquitetura de um agent harness impacta diretamente a segurança, a escalabilidade e as funcionalidades do agente. Existem duas abordagens principais: 'inside the sandbox' e 'outside the sandbox'.

Harness Inside the Sandbox

Nesse modelo, o loop do agente reside dentro do mesmo container que o código que ele manipula. As chamadas para LLMs são feitas a partir do container, e as execuções de ferramentas (como comandos bash, leitura e escrita de arquivos) ocorrem localmente. As habilidades, memórias e outros dados do agente são armazenados como arquivos no sistema de arquivos do container. Essa é a abordagem padrão quando se utiliza um LLM localmente ou em um container remoto, como com o Claude Code SDK.

Harness Outside the Sandbox

Nesta arquitetura, o loop do agente é executado no backend, e as execuções de ferramentas são delegadas a um sandbox através de uma API. O loop nunca entra no sandbox diretamente. Essa abordagem oferece maior controle e isolamento, separando as credenciais do ambiente de execução do agente.

Tradeoffs

Cada arquitetura apresenta vantagens e desvantagens distintas. A abordagem 'inside the sandbox' é mais simples de implementar, reutilizando harnesses existentes e aproveitando o sistema de arquivos local. No entanto, a abordagem 'outside the sandbox' oferece benefícios cruciais em termos de segurança, escalabilidade e gerenciamento de recursos.

Ao executar o harness fora do sandbox, suas credenciais (chaves de API, tokens de usuário, acesso ao banco de dados) permanecem protegidas, fora do ambiente isolado. O sandbox contém apenas o ambiente necessário para a execução das ferramentas, minimizando o risco de fuga de credenciais. Além disso, o sandbox pode ser suspenso quando não estiver em uso, otimizando o consumo de recursos e reduzindo custos. E, em caso de falha, o sandbox pode ser rapidamente substituído por um novo, garantindo a continuidade da operação.

Para ambientes multiusuário, a arquitetura 'outside the sandbox' se destaca, eliminando o problema de um sistema de arquivos distribuído e permitindo o compartilhamento de habilidades e memórias entre os usuários. Enquanto isso, a arquitetura 'inside the sandbox' pode tornar o gerenciamento de dados complexo e inconsistente.

Está pronto para levar a segurança e escalabilidade dos seus agentes para o próximo nível? Conheça a Toolzz AI e descubra como simplificar a construção e o gerenciamento de agentes de IA robustos.

Desafios na Implementação Outside the Sandbox

Embora a arquitetura 'outside the sandbox' ofereça vantagens significativas, a implementação apresenta desafios únicos. A execução duradoura do loop do agente, o gerenciamento do ciclo de vida do sandbox e a virtualização do sistema de arquivos são aspectos cruciais a serem considerados.

Execução Duradoura

O loop de um agente pode durar minutos ou horas, exigindo resiliência a reinicializações e eventos de escala. Uma solução eficaz é utilizar plataformas como Inngest, que garantem a execução contínua do loop, checkpointing cada etapa para permitir a retomada em caso de falha. Esta abordagem oferece uma alternativa mais simples e eficiente do que gerenciar um cluster complexo.

Ciclo de Vida do Sandbox

Para otimizar o uso de recursos, o sandbox deve ser suspenso quando o agente não estiver em execução e reativado sob demanda. Plataformas como Blaxel permitem a retomada do sandbox em milissegundos, garantindo uma experiência de usuário responsiva. Essa abordagem minimiza a latência e o consumo de recursos.

Virtualização do Sistema de Arquivos

Agentes de IA frequentemente utilizam habilidades (fragmentos de prompt), memórias (anotações) e outros dados armazenados em um sistema de arquivos local. Para replicar essa funcionalidade em um ambiente 'outside the sandbox', é necessário virtualizar o acesso ao sistema de arquivos, roteando as chamadas para o banco de dados (para habilidades e memórias) e para o sandbox (para arquivos de trabalho). Uma interface unificada simplifica essa interação, apresentando ao agente um sistema de arquivos consistente, independentemente do local de armazenamento dos dados.

Uma Interface, Dois Backends

O harness virtualiza o acesso ao sistema de arquivos, utilizando uma única API read, write e edit. Com base no caminho especificado, a chamada é roteada para o banco de dados ou para o sandbox. Essa abordagem mantém a compatibilidade com modelos treinados em ambientes com acesso a sistema de arquivos local, minimizando a necessidade de adaptações.

Conclusão

A escolha entre arquiteturas 'inside' e 'outside the sandbox' para agent harnesses depende das necessidades específicas de cada aplicação. Embora a abordagem 'inside' seja mais simples para casos de uso individuais, a arquitetura 'outside' oferece maior segurança, escalabilidade e flexibilidade para ambientes multiusuário e aplicações complexas. Ao implementar uma arquitetura 'outside the sandbox', é crucial abordar os desafios relacionados à execução duradoura, gerenciamento do ciclo de vida do sandbox e virtualização do sistema de arquivos. A Toolzz AI oferece uma plataforma robusta e escalável para construir e gerenciar agentes de IA, abstraindo a complexidade da infraestrutura e permitindo que você se concentre na criação de soluções inovadoras. Com a Toolzz AI, você pode aproveitar os benefícios da arquitetura 'outside the sandbox' sem a necessidade de construir e manter uma infraestrutura complexa.