LLM Sandbox: Implementando um Agente com Ambiente Isolado (Parte 2 - Prática)
Explore a implementação prática de um agente LLM que executa código em um ambiente Docker isolado. Este artigo detalha a arquitetura, os componentes e os desafios de custo associados à execução de código seguro em larga escala.
MundiX News·27 de junho de 2026·8 min de leitura·👁 1 views
LLM Sandbox: Implementando um Agente com Ambiente Isolado (Parte 2 - Prática)
Este artigo é a segunda parte de uma série focada na criação de um "LLM Sandbox", um ambiente seguro para a execução de código gerado por Large Language Models (LLMs). Na primeira parte, abordamos os riscos inerentes à execução de código por LLMs, as limitações de ambientes isolados (sandboxes) e exploramos diversas técnicas de isolamento como Docker, Wasm, gVisor e microVMs, além de apresentar uma arquitetura mínima para um agente com sandbox. Agora, mergulharemos na prática, detalhando a implementação de um agente que escreve e executa código dentro de um sandbox Docker.
O código completo, os "skills" (conjuntos de instruções para tarefas específicas), logs detalhados e artefatos deste exemplo estão disponíveis em um repositório público no GitHub. Para quem não me conhece, sou Evgeniy, um desenvolvedor e líder de equipe de ML, com foco em agentes, LLMs e Processamento de Linguagem Natural (NLP). Compartilho minhas experiências práticas e insights técnicos sobre IA e ML em meu canal no Telegram.
Arquitetura e Implementação do Agente com Sandbox
O agente opera seguindo um padrão híbrido ReAct + Plan-Execute, utilizando o framework LangGraph. Sua arquitetura é composta por:
Orchestrator (Orquestrador): O "cérebro" do agente. Ele recebe a tarefa do usuário, planeja a solução decompondo-a em sub-tarefas, delega essas sub-tarefas aos "sub-agentes" e, finalmente, agrega os resultados para sintetizar a resposta final.
Sub-agent (Sub-agente): Uma sessão dedicada com um LLM e um contexto limpo. O orquestrador envia uma tarefa específica e o contexto necessário para o sub-agente, permitindo que as sub-tarefas sejam executadas de forma independente sem sobrecarregar o agente principal.
LLM: Tanto o orquestrador quanto os sub-agentes interagem com um LLM, cada um com seus "system prompts" (instruções de sistema) específicos.
Skills Catalog (Catálogo de Habilidades): Um conjunto de instruções detalhadas para tarefas específicas. Por exemplo, o diretório skills/presentation descreve o processo completo de criação de apresentações. O orquestrador e os sub-agentes acessam essas instruções através da ferramenta read_skill.
As ferramentas disponíveis para o agente incluem:
Gerenciamento de Sub-tarefas:create_todo_list, complete_todo, start_next_todo, revise_todo_list, block_todo.
Gerenciamento de Arquivos:list_input_files, list_output_files, read_file_content, read_skill.
Execução de Código:write_python_file (salva scripts Python em /workspace/code) e run_python_file (executa scripts na sandbox).
O Docker Sandbox é o ambiente de execução isolada. Para cada sub-tarefa, um contêiner Docker é criado temporariamente. Ele é configurado com flags de segurança rigorosos como --network=none, --read-only, --cap-drop=ALL, --security-opt=no-new-privileges, executado como usuário não-root, com limites de CPU/RAM/PIDs, e utiliza tmpfs para /tmp e montagens read-only para diretórios de entrada e código. É crucial notar que esta configuração de Docker é uma solução prática para um MVP local; ambientes de produção podem exigir isolamento mais robusto.
Exemplo de Execução: Análise do Titanic e Criação de Apresentação
Para ilustrar o funcionamento, consideramos a tarefa: "Analise um conjunto de dados e prepare uma apresentação com as principais conclusões da EDA (Exploratory Data Analysis)". O conjunto de dados utilizado é o do famoso "Titanic". O objetivo principal deste exemplo é demonstrar a interação do agente com o sandbox, e não a capacidade do LLM de escrever código complexo.
O agente, utilizando o modelo Qwen3.5-27B (configurável via LLM_MODEL), primeiro cria uma lista de sub-tarefas: eda-analysis para a análise exploratória e create-presentation para a geração da apresentação. Cada sub-tarefa especifica as habilidades necessárias, arquivos de entrada/saída e critérios de sucesso.
O agente então inicia a sub-tarefa eda-analysis. Ele lista os arquivos de entrada, lê um fragmento do CSV (basic_dataset.csv) e utiliza write_python_file para gerar um script Python. Este script é executado na sandbox via run_python_file. O resultado da execução, incluindo estatísticas e resumos, é capturado no STDOUT e um arquivo eda_summary.csv é gerado no diretório de saída. Após o sucesso, a sub-tarefa é marcada como completa usando complete_todo.
Em seguida, o agente inicia a sub-tarefa create-presentation. Ele carrega as habilidades relevantes (presentation, python-scripts) e gera o código para criar a apresentação. Durante este processo, podem ocorrer erros (como um AttributeError ao tentar acessar slide_width), que o agente tenta corrigir em iterações subsequentes. O resultado final é um arquivo .pptx contendo os principais achados da EDA, juntamente com o arquivo eda_summary.csv e gráficos gerados.
Custo em Tokens e Considerações Práticas
A execução deste exemplo, monitorada pelo Langfuse, revela insights sobre o custo em tokens. O tempo total de execução foi de aproximadamente 182,6 segundos, com 29 chamadas LLM. O orquestrador consumiu uma pequena fração dos tokens (4,7%), pois foca em planejamento e síntese. O sub-agente de apresentação foi o principal consumidor (76% dos tokens e 70% do tempo), devido às múltiplas iterações de geração e execução de código, correções de erros e o crescimento do contexto ao longo do tempo. As chamadas para write_python_file foram significativamente mais caras em termos de tokens do que as de run_python_file.
O sandbox isola a execução do código, mas não o custo em tokens. Para gerenciar o orçamento de tokens, é essencial aplicar técnicas de engenharia de contexto, como sub-agentes com janelas de contexto limpas, limites para o tamanho do output das ferramentas, redução de stdout/stderr e carregamento de skills sob demanda (read_skill).
Conclusão
A implementação prática demonstra que o Docker Sandbox pode ser integrado como uma ferramenta valiosa no ciclo de um agente, ao lado de planejamento e operações de arquivo. A configuração de sandbox com flags de segurança rigorosos é viável para MVPs locais, proporcionando isolamento e um fluxo claro de artefatos. A arquitetura de orquestrador e sub-agentes ajuda a separar o planejamento do contexto de execução de código "sujo".
É fundamental entender que o sucesso do sandbox garante a execução do código e a criação de artefatos, mas não a correção automática do resultado. Para relatórios de usuário confiáveis, validação de conteúdo, qualidade visual e verificação de informações factuais ainda são necessárias. A teoria sobre riscos, limitações e alternativas (Wasm, gVisor, microVM) pode ser encontrada na primeira parte desta série. O código completo e os artefatos estão disponíveis no repositório do GitHub.
Convido a todos a se juntarem ao canal "Em Busca do NLP" (@chasing_nlp) no Telegram para mais novidades sobre IA/ML, anúncios de artigos e experiências no desenvolvimento de projetos com LLMs e agentes.
Série "LLM Sandbox":
Parte 1. Teoria: Riscos, limitações e métodos de isolamento.
Parte 2. Prática: Esta artigo.
Outros artigos:
Agent Harness: Um LLM, resultados diferentes - Qual o segredo?
Segundo Cérebro e LLM-Wiki: Guia prático para criar e manter sua base de conhecimento pessoal.
Sem cartão para começar · Planos a partir de R$49/mês
LLM Sandbox: Implementando um Agente com Ambiente Isolado (Parte 2 - Prática)
Este artigo é a segunda parte de uma série focada na criação de um "LLM Sandbox", um ambiente seguro para a execução de código gerado por Large Language Models (LLMs). Na primeira parte, abordamos os riscos inerentes à execução de código por LLMs, as limitações de ambientes isolados (sandboxes) e exploramos diversas técnicas de isolamento como Docker, Wasm, gVisor e microVMs, além de apresentar uma arquitetura mínima para um agente com sandbox. Agora, mergulharemos na prática, detalhando a implementação de um agente que escreve e executa código dentro de um sandbox Docker.
O código completo, os "skills" (conjuntos de instruções para tarefas específicas), logs detalhados e artefatos deste exemplo estão disponíveis em um repositório público no GitHub. Para quem não me conhece, sou Evgeniy, um desenvolvedor e líder de equipe de ML, com foco em agentes, LLMs e Processamento de Linguagem Natural (NLP). Compartilho minhas experiências práticas e insights técnicos sobre IA e ML em meu canal no Telegram.
Arquitetura e Implementação do Agente com Sandbox
O agente opera seguindo um padrão híbrido ReAct + Plan-Execute, utilizando o framework LangGraph. Sua arquitetura é composta por:
Orchestrator (Orquestrador): O "cérebro" do agente. Ele recebe a tarefa do usuário, planeja a solução decompondo-a em sub-tarefas, delega essas sub-tarefas aos "sub-agentes" e, finalmente, agrega os resultados para sintetizar a resposta final.
Sub-agent (Sub-agente): Uma sessão dedicada com um LLM e um contexto limpo. O orquestrador envia uma tarefa específica e o contexto necessário para o sub-agente, permitindo que as sub-tarefas sejam executadas de forma independente sem sobrecarregar o agente principal.
LLM: Tanto o orquestrador quanto os sub-agentes interagem com um LLM, cada um com seus "system prompts" (instruções de sistema) específicos.
Skills Catalog (Catálogo de Habilidades): Um conjunto de instruções detalhadas para tarefas específicas. Por exemplo, o diretório skills/presentation descreve o processo completo de criação de apresentações. O orquestrador e os sub-agentes acessam essas instruções através da ferramenta read_skill.
As ferramentas disponíveis para o agente incluem:
Gerenciamento de Sub-tarefas:create_todo_list, complete_todo, start_next_todo, revise_todo_list, block_todo.
Gerenciamento de Arquivos:list_input_files, list_output_files, read_file_content, read_skill.
Execução de Código:write_python_file (salva scripts Python em /workspace/code) e run_python_file (executa scripts na sandbox).
O Docker Sandbox é o ambiente de execução isolada. Para cada sub-tarefa, um contêiner Docker é criado temporariamente. Ele é configurado com flags de segurança rigorosos como --network=none, --read-only, --cap-drop=ALL, --security-opt=no-new-privileges, executado como usuário não-root, com limites de CPU/RAM/PIDs, e utiliza tmpfs para /tmp e montagens read-only para diretórios de entrada e código. É crucial notar que esta configuração de Docker é uma solução prática para um MVP local; ambientes de produção podem exigir isolamento mais robusto.
Exemplo de Execução: Análise do Titanic e Criação de Apresentação
Para ilustrar o funcionamento, consideramos a tarefa: "Analise um conjunto de dados e prepare uma apresentação com as principais conclusões da EDA (Exploratory Data Analysis)". O conjunto de dados utilizado é o do famoso "Titanic". O objetivo principal deste exemplo é demonstrar a interação do agente com o sandbox, e não a capacidade do LLM de escrever código complexo.
O agente, utilizando o modelo Qwen3.5-27B (configurável via LLM_MODEL), primeiro cria uma lista de sub-tarefas: eda-analysis para a análise exploratória e create-presentation para a geração da apresentação. Cada sub-tarefa especifica as habilidades necessárias, arquivos de entrada/saída e critérios de sucesso.
O agente então inicia a sub-tarefa eda-analysis. Ele lista os arquivos de entrada, lê um fragmento do CSV (basic_dataset.csv) e utiliza write_python_file para gerar um script Python. Este script é executado na sandbox via run_python_file. O resultado da execução, incluindo estatísticas e resumos, é capturado no STDOUT e um arquivo eda_summary.csv é gerado no diretório de saída. Após o sucesso, a sub-tarefa é marcada como completa usando complete_todo.
Em seguida, o agente inicia a sub-tarefa create-presentation. Ele carrega as habilidades relevantes (presentation, python-scripts) e gera o código para criar a apresentação. Durante este processo, podem ocorrer erros (como um AttributeError ao tentar acessar slide_width), que o agente tenta corrigir em iterações subsequentes. O resultado final é um arquivo .pptx contendo os principais achados da EDA, juntamente com o arquivo eda_summary.csv e gráficos gerados.
Custo em Tokens e Considerações Práticas
A execução deste exemplo, monitorada pelo Langfuse, revela insights sobre o custo em tokens. O tempo total de execução foi de aproximadamente 182,6 segundos, com 29 chamadas LLM. O orquestrador consumiu uma pequena fração dos tokens (4,7%), pois foca em planejamento e síntese. O sub-agente de apresentação foi o principal consumidor (76% dos tokens e 70% do tempo), devido às múltiplas iterações de geração e execução de código, correções de erros e o crescimento do contexto ao longo do tempo. As chamadas para write_python_file foram significativamente mais caras em termos de tokens do que as de run_python_file.
O sandbox isola a execução do código, mas não o custo em tokens. Para gerenciar o orçamento de tokens, é essencial aplicar técnicas de engenharia de contexto, como sub-agentes com janelas de contexto limpas, limites para o tamanho do output das ferramentas, redução de stdout/stderr e carregamento de skills sob demanda (read_skill).
Conclusão
A implementação prática demonstra que o Docker Sandbox pode ser integrado como uma ferramenta valiosa no ciclo de um agente, ao lado de planejamento e operações de arquivo. A configuração de sandbox com flags de segurança rigorosos é viável para MVPs locais, proporcionando isolamento e um fluxo claro de artefatos. A arquitetura de orquestrador e sub-agentes ajuda a separar o planejamento do contexto de execução de código "sujo".
É fundamental entender que o sucesso do sandbox garante a execução do código e a criação de artefatos, mas não a correção automática do resultado. Para relatórios de usuário confiáveis, validação de conteúdo, qualidade visual e verificação de informações factuais ainda são necessárias. A teoria sobre riscos, limitações e alternativas (Wasm, gVisor, microVM) pode ser encontrada na primeira parte desta série. O código completo e os artefatos estão disponíveis no repositório do GitHub.
Convido a todos a se juntarem ao canal "Em Busca do NLP" (@chasing_nlp) no Telegram para mais novidades sobre IA/ML, anúncios de artigos e experiências no desenvolvimento de projetos com LLMs e agentes.
Série "LLM Sandbox":
Parte 1. Teoria: Riscos, limitações e métodos de isolamento.
Parte 2. Prática: Esta artigo.
Outros artigos:
Agent Harness: Um LLM, resultados diferentes - Qual o segredo?
Segundo Cérebro e LLM-Wiki: Guia prático para criar e manter sua base de conhecimento pessoal.
Divulgação: alguns links são patrocinados. Podemos receber comissão se você comprar — sem custo extra para você. Só indicamos o que faz sentido para a comunidade.
