0Pricing
AI Agents · Aula

Ambientes isolados para agentes baseados em Docker

Criando contêineres descartáveis para executar código gerado por agentes.

Ambientes isolados para agentes baseados em Docker é uma aula grátis de AI Agents no CoddyKit. Esta é a aula 1 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de AI Agents, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de AI Agents inclui 4 aulas no total.

Por que os agentes precisam de ambientes isolados

Quando um agente executa código escrito por um LLM, esse código é não confiável. Ele pode tentar ler arquivos confidenciais, estabelecer conexões de saída ou consumir recursos ilimitados.

Um ambiente isolado separa a execução do código para que os danos fiquem contidos, independentemente do que o código faça.

Docker como camada de isolamento

Os contêineres Docker fornecem um isolamento leve no nível do OS. Cada trecho de código é executado dentro de um contêiner novo, com limites explícitos de recursos e restrições de rede.

O SDK Python do Docker docker permite criar e destruir contêineres programaticamente a partir do agente.

import docker

client = docker.from_env()
print(client.version()['Version'])

Execução básica de um contêiner

client.containers.run() inicia um contêiner, executa um comando e retorna a saída como bytes. Definir auto_remove=True limpa o contêiner depois que ele é encerrado.

import docker

client = docker.from_env()

output = client.containers.run(
    'python:3.12-slim',
    'python -c "print(2 + 2)"',
    auto_remove=True
)

print(output.decode())  # '4'

Limites de memória e CPU

Sem limites, um script malicioso pode esgotar a memória da máquina hospedeira. Passe mem_limit e nano_cpus para limitar o uso de recursos.

Se o processo exceder mem_limit, o contêiner será encerrado por OOM e uma exceção será levantada.

output = client.containers.run(
    'python:3.12-slim',
    'python -c "x = [0]*10**8"',   # tries to allocate ~800 MB
    mem_limit='256m',
    nano_cpus=1_000_000_000,        # 1 CPU
    auto_remove=True
)
# Raises docker.errors.ContainerError if OOM-killed

Desativação da rede

Definir network_disabled=True impede que o contêiner faça chamadas de rede de saída ou de entrada — até mesmo as consultas DNS falham. Isso impede a exfiltração de dados e as conexões de comando e controle.

output = client.containers.run(
    'python:3.12-slim',
    'python -c "import urllib.request; urllib.request.urlopen(\"http://example.com\")"',
    network_disabled=True,
    auto_remove=True
)
# Raises ContainerError: network unreachable

Tempo limite de execução

Um loop infinito dentro do ambiente isolado bloquearia seu agente para sempre. Passe um timeout (em segundos) para containers.run() para que o Docker encerre o contêiner após o prazo.

import docker
from docker.errors import ContainerError

client = docker.from_env()

try:
    output = client.containers.run(
        'python:3.12-slim',
        'python -c "while True: pass"',
        mem_limit='256m',
        network_disabled=True,
        auto_remove=True,
        timeout=30
    )
except Exception as e:
    print(f'Sandbox timeout or error: {e}')

Função auxiliar completa para o ambiente isolado

Agrupar todas as configurações em uma função reutilizável facilita sua chamada pelas ferramentas do agente. Retorne tanto a saída padrão quanto um indicador de status para que o agente possa agir diante de falhas.

import docker

client = docker.from_env()

def run_in_sandbox(code: str, timeout: int = 30) -> dict:
    cmd = f'python -c "{code.replace(chr(34), chr(39))}"'
    try:
        out = client.containers.run(
            'python:3.12-slim',
            cmd,
            mem_limit='256m',
            nano_cpus=500_000_000,
            network_disabled=True,
            auto_remove=True,
            timeout=timeout
        )
        return {'success': True, 'output': out.decode()}
    except Exception as e:
        return {'success': False, 'error': str(e)}

Montagem de um espaço de trabalho temporário

Se o código precisar ler arquivos de entrada ou gravar arquivos de saída, monte um diretório temporário da máquina hospedeira no contêiner. Use volumes com o modo 'rw' para o espaço de trabalho e nada mais.

import tempfile, os

with tempfile.TemporaryDirectory() as tmpdir:
    # Write input data
    with open(os.path.join(tmpdir, 'data.txt'), 'w') as f:
        f.write('hello sandbox')

    output = client.containers.run(
        'python:3.12-slim',
        'python -c "print(open(\"/workspace/data.txt\").read())"',
        volumes={tmpdir: {'bind': '/workspace', 'mode': 'rw'}},
        mem_limit='256m',
        network_disabled=True,
        auto_remove=True
    )
    print(output.decode())

Sistema de arquivos somente leitura

Defina read_only=True para montar o sistema de arquivos raiz do contêiner como somente leitura. O código só poderá gravar em volumes montados explicitamente. Isso impede gravações em /etc, /usr ou outros caminhos sensíveis dentro da imagem.

import tempfile

with tempfile.TemporaryDirectory() as tmpdir:
    output = client.containers.run(
        'python:3.12-slim',
        'python -c "open(\"/output/result.txt\",\"w\").write(str(1+1))"',
        volumes={tmpdir: {'bind': '/output', 'mode': 'rw'}},
        read_only=True,
        mem_limit='256m',
        network_disabled=True,
        auto_remove=True
    )
    print(open(f'{tmpdir}/result.txt').read())  # '2'

Integração do ambiente isolado a uma ferramenta de agente

Registre o executor do ambiente isolado como uma ferramenta que o LLM possa chamar. O agente gera código, a ferramenta o executa de forma isolada e a saída retorna à próxima etapa de raciocínio.

tools = [
    {
        'type': 'function',
        'function': {
            'name': 'execute_python',
            'description': 'Run a Python snippet in an isolated Docker sandbox.',
            'parameters': {
                'type': 'object',
                'properties': {
                    'code': {'type': 'string', 'description': 'Python code to execute.'}
                },
                'required': ['code']
            }
        }
    }
]

def handle_tool_call(name, args):
    if name == 'execute_python':
        return run_in_sandbox(args['code'])

Tratamento de erros e limpeza

Os contêineres podem falhar ao iniciar se o serviço do Docker não estiver em execução ou se a imagem não estiver armazenada em cache. Sempre trate docker.errors.DockerException e garanta que os contêineres sejam limpos mesmo quando ocorrerem exceções.

from docker.errors import DockerException, ImageNotFound

def safe_run(code: str) -> dict:
    try:
        return run_in_sandbox(code)
    except ImageNotFound:
        # Pull the image first
        client.images.pull('python:3.12-slim')
        return run_in_sandbox(code)
    except DockerException as e:
        return {'success': False, 'error': f'Docker unavailable: {e}'}
    except Exception as e:
        return {'success': False, 'error': str(e)}

Qual configuração do ambiente isolado é mais importante para impedir a exfiltração de dados?

Um ambiente isolado de agente deve impedir que o código executado envie dados roubados para um servidor externo. Qual parâmetro do Docker bloqueia diretamente o acesso de saída à rede?

Recapitulação dos ambientes isolados do Docker

Os ambientes isolados baseados em Docker fornecem um ambiente seguro de execução aos agentes ao combinar limites de memória e CPU, isolamento de rede, limites de tempo de execução e sistemas de arquivos somente leitura.

Agrupe essas configurações em uma função auxiliar reutilizável e exponha-a como uma ferramenta de agente para permitir que o LLM execute com segurança o código gerado, sem colocar o sistema hospedeiro em risco.

Perguntas Frequentes

A aula “Ambientes isolados para agentes baseados em Docker” é grátis?

Sim — o texto completo de “Ambientes isolados para agentes baseados em Docker” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de AI Agents, atualize para CoddyKit PRO. O curso de AI Agents inclui 4 aulas no total.

O que vou aprender em “Ambientes isolados para agentes baseados em Docker”?

Criando contêineres descartáveis para executar código gerado por agentes. Você pratica AI Agents com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar AI Agents?

Nenhuma experiência prévia é necessária. AI Agents no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 1 de 4.

Quanto tempo leva a aula “Ambientes isolados para agentes baseados em Docker”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de AI Agents?

Sim. Cada aula de AI Agents inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

  1. Ambientes isolados para agentes baseados em Docker
  2. Isolamento por VM para agentes de código de alta segurança
  3. E2B e serviços de ambientes isolados na nuvem
  4. Políticas de segurança para execução de código
← Voltar para AI Agents