Sandboxes hospedados pela OpenAI: crie um analista financeiro de IA com segurança

Agentes de IA já foram muito além da simples geração de texto. Eles escrevem código, executam comandos, manipulam arquivos, corrigem erros e concluem tarefas de múltiplas etapas por conta própria.

Mas LLMs nem sempre são previsíveis. 

Mesmo com instruções claras, um agente pode gerar um comando inesperado ou alterar algo que não deveria. Executar esse código diretamente no seu computador local ou no servidor da aplicação pode, portanto, introduzir riscos desnecessários.

Neste tutorial, vou usar um sandbox hospedado pela OpenAI para construir um analista financeiro de IA com segurança. Vamos fazer upload de um conjunto de dados financeiros, conectar um agente ao ambiente isolado, deixar que ele realize a análise e gere artefatos lá dentro e, em seguida, baixar os relatórios, gráficos e arquivos de dados resultantes.

O analista financeiro é apenas um exemplo. O objetivo principal é entender como dar a um agente de IA um ambiente controlado onde ele possa executar código e trabalhar com arquivos com segurança.

O que é o sandbox hospedado pela OpenAI?

Um sandbox é um ambiente isolado onde o código pode rodar sem ter acesso irrestrito ao sistema que hospeda sua aplicação.

Isso é especialmente útil para agentes de IA porque seu comportamento não é completamente previsível. 

Um agente pode ser instruído a modificar um arquivo, mas gerar um comando que afeta outro diretório, instalar uma dependência inesperada ou executar algo que você não antecipou.

Em vez de permitir que esses comandos rodem diretamente no seu notebook ou servidor, você pode colocar o agente dentro de um sandbox.

A OpenAI oferece seu próprio ambiente de sandbox hospedado para esse fim. 

Ele oferece ao agente um workspace Linux real com sistema de arquivos e shell, mantendo essa execução separada do seu sistema local.

Dentro do sandbox, o agente pode:

• Ler e escrever arquivos.
• Criar e executar scripts.
• Executar comandos de shell.
• Inspecionar a saída dos comandos.
• Corrigir erros e reexecutar o código.
• Gerar relatórios, datasets, gráficos e outros artefatos.

Você também pode controlar o que o sandbox acessa. 

Por exemplo, você pode enviar apenas os arquivos necessários para a tarefa e desativar o acesso à rede quando o agente não precisar de informação externa.

Maneiras de usar sandboxes da OpenAI

A OpenAI oferece algumas formas diferentes de executar agentes ou modelos em ambientes isolados. A principal diferença é quanto da execução e do fluxo do agente você quer que a OpenAI gerencie.

1. Shell Tool

A Shell tool é a opção mais simples. Ela permite que um modelo execute comandos de shell dentro de um container hospedado pela OpenAI via a Responses API.

response = client.responses.create(
    model=MODEL,
    tools=[{
        "type": "shell",
        "environment": {"type": "container_auto"}
    }],
    input="Analyze the files in /mnt/data."
)Tecnologia

É uma boa escolha quando você precisa principalmente de execução de código, processamento de arquivos ou tarefas de linha de comando.

2. Agents API

A Agents API é uma opção mais gerenciada. A OpenAI cuida tanto da sessão do agente quanto do ambiente hospedado.

stream = client.beta.agents.sessions.create(
    agent={
        "model": MODEL,
        "instructions": "Analyze the data and create a report."
    },
    environment={"type": "openai_hosted"},
    input="Analyze the files in the workspace.",
    stream=True,
)Tecnologia

É útil quando você quer que a OpenAI gerencie mais do runtime do agente e do ciclo de vida do sandbox para você.

3. SandboxAgent

SandboxAgent faz parte do Agents SDK e é projetado para agentes em que o workspace do sandbox é parte central da aplicação.

from agents.sandbox import SandboxAgent
from agents.sandbox.capabilities import Shell

agent = SandboxAgent(
    name="Financial Analyst",
    model=MODEL,
    capabilities=[Shell()],
)Tecnologia

Funciona bem quando você precisa de workspaces, arquivos e artefatos persistentes, ou flexibilidade sobre qual provedor de sandbox usar.

4. Agents SDK + ShellTool

Esta é a abordagem que usamos neste guia.

Criamos o container hospedado pela OpenAI e depois conectamos o agente a esse ambiente específico usando ShellTool.

sandbox_shell = ShellTool(
    environment={
        "type": "container_reference",
        "container_id": container.id,
    }
)Tecnologia

Escolhemos essa abordagem porque oferece um bom equilíbrio entre simplicidade e controle. 

A OpenAI gerencia a infraestrutura do sandbox, enquanto nós ainda controlamos o container, os arquivos, o acesso à rede, as instruções do agente, as ferramentas e o fluxo de execução.

Como usar o sandbox hospedado pela OpenAI

Vamos explorar como usar o sandbox hospedado pela OpenAI para criar um agente de análise financeira com segurança. 

1. Configure o ambiente e o projeto

Usaremos um Jupyter Notebook para configurar e testar o workflow. 

O notebook vai cuidar de tarefas como instalar os SDKs necessários, fazer upload do dataset, criar o sandbox, iniciar o agente e baixar os artefatos finais.

Porém, um ponto importante: a análise financeira em si não vai rodar dentro do Jupyter. 

Depois que o agente estiver conectado ao sandbox da OpenAI, a execução de código, os comandos de shell, a validação, os cálculos e a geração de artefatos vão acontecer dentro do ambiente hospedado.

Pense no Jupyter como a camada de controle, enquanto o sandbox é o ambiente de execução.

Comece instalando o OpenAI Python SDK e o OpenAI Agents SDK:

%pip install -q -U openai openai-agentsTecnologia

Você também precisa de uma chave de API da OpenAI disponível na variável de ambiente OPENAI_API_KEY.

Para este tutorial, vamos usar um dataset de uma empresa fictícia armazenado em:

financial_data/northstar_cloud_financial_statements.csvTecnologia

Em seguida, importe as bibliotecas necessárias e defina o modelo, o CSV de entrada, o diretório local de saída e os arquivos que esperamos que o agente gere.

import json
import os
from pathlib import Path

from IPython.display import Markdown, SVG, display


MODEL = os.getenv("OPENAI_MODEL", "gpt-6-luna")

STATEMENT_CSV = Path(
    "financial_data/northstar_cloud_financial_statements.csv"
)

OUTPUT_DIR = Path("financial_analysis_output")
OUTPUT_DIR.mkdir(exist_ok=True)

EXPECTED_ARTIFACTS = [
    "analyze_financials.py",
    "calculated_metrics.csv",
    "unusual_movements.csv",
    "financial_trends.svg",
    "investment_analysis.md",
    "analysis_run.json",
]

assert os.getenv("OPENAI_API_KEY"), \
    "Set OPENAI_API_KEY before continuing."

assert STATEMENT_CSV.exists(), \
    f"Missing input: {STATEMENT_CSV.resolve()}"

print(f"Model: {MODEL}")
print(
    f"Input: {STATEMENT_CSV} "
    f"({STATEMENT_CSV.stat().st_size:,} bytes)"
)Tecnologia

Saída:

Model: gpt-6-luna
Input: financial_data\northstar_cloud_financial_statements.csv (1,480 bytes)Tecnologia

As asserções fornecem um sanity check rápido antes de criarmos qualquer recurso da OpenAI. Se a chave de API estiver ausente ou o dataset não for encontrado, o notebook para imediatamente em vez de falhar mais adiante no fluxo.

OUTPUT_DIR é um diretório local do Jupyter onde vamos salvar os arquivos baixados do sandbox. 

EXPECTED_ARTIFACTS, por sua vez, define os arquivos que esperamos que o agente crie dentro do sandbox.

2. Faça upload dos dados financeiros

Antes que o sandbox possa trabalhar com nossos dados financeiros, precisamos primeiro enviar o CSV para a OpenAI.

O Jupyter Notebook realiza essa etapa. Ele lê o arquivo local e o envia pela OpenAI Files API.

from openai import OpenAI

client = OpenAI()

with STATEMENT_CSV.open("rb") as handle:
    uploaded_input = client.files.create(
        file=handle,
        purpose="user_data",
    )

print(f"Uploaded raw statements: {uploaded_input.id}")Tecnologia

Saída:

Uploaded raw statements: file-C6Pb6RhZrVPR4Fiq9tZ6HnTecnologia

Seu ID de arquivo será diferente.

O ID retornado é importante porque vamos usá-lo ao criar o sandbox. Em vez de copiar o conteúdo do CSV para um prompt, podemos anexar o arquivo original diretamente ao ambiente de trabalho do agente.

Neste ponto, as demonstrações financeiras da Northstar estão armazenadas na OpenAI, mas o agente ainda não tem um ambiente de execução.

Vamos criá-lo a seguir.

3. Crie o sandbox hospedado pela OpenAI

Agora podemos criar o ambiente hospedado onde o agente realmente fará a análise financeira.

Use a Containers API para criar um novo sandbox e anexar o CSV enviado usando seu ID de arquivo:

container = client.containers.create(
    name="northstar-financial-analysis",
    file_ids=[uploaded_input.id],
    memory_limit="4g",
    network_policy={"type": "disabled"},
)

print(f"OpenAI sandbox: {container.id}")Tecnologia

Saída:

OpenAI sandbox: cntr_6ab7a1080b4081938d8d08ab67ac963c084798905ec997e9Tecnologia

O sandbox é criado com 4 GB de memória, e as demonstrações financeiras enviadas já ficam disponíveis nele desde o início.

Também desativamos o acesso à rede:

network_policy={"type": "disabled"}Tecnologia

Nossa análise financeira não requer informações da internet, então não há motivo para dar acesso externo à rede ao agente. Tudo o que ele precisa já está contido no CSV.

4. Defina a tarefa do analista financeiro

O sandbox dá ao agente um espaço seguro para trabalhar, mas ainda precisamos definir exatamente o que queremos que ele faça.

Em vez de dar ao modelo uma instrução vaga como "analise esta empresa", fornecemos uma tarefa detalhada que descreve os cálculos, checagens de validação, arquivos a serem gerados e como o agente deve verificar o próprio trabalho.

ANALYST_INSTRUCTIONS = """
You are a skeptical senior buy-side financial analyst preparing an investment-committee memo.

Every analytical operation must occur in the hosted shell container under /mnt/data. Do not
estimate results mentally or ask the caller to calculate anything.

Find the uploaded Northstar statement CSV. Write analyze_financials.py using only the Python
standard library and execute it. Validate required columns, numeric values, unique ordered years,
and total_assets = total_liabilities + equity for every row. Calculate revenue growth, gross/
operating/net margins, current and quick ratios, total-liabilities-to-equity, average-balance ROA
and ROE, interest coverage, free cash flow, FCF margin, cash conversion, receivables growth, and
inventory growth. Leave a ratio blank when its denominator makes it undefined.

Flag absolute year-over-year movements of at least 15%, operating-margin moves of at least two
percentage points, and receivables growth exceeding revenue growth by at least ten points. Create
calculated_metrics.csv, unusual_movements.csv, financial_trends.svg, investment_analysis.md, and
analysis_run.json in /mnt/data. The SVG must contain four readable chart panels without external
packages.

The report must cover Executive view, KPI table, Profitability, Liquidity and leverage, Cash flow
and earnings quality, Unusual movements, Bull case, Bear case, Diligence questions, Data
limitations, and Conclusion. Tie receivables, deferred revenue, stock compensation, capex, and
interest expense to evidence; separate facts from hypotheses and cite filenames and years.

analysis_run.json must contain input_filename, row_count, year_range, validation_results,
generated_filenames, and execution_directory='/mnt/data'. validation_results must include
accounting_equation_passed_every_row=true. Run the script, inspect every artifact, independently
recompute at least three 2025 metrics in a second command, and fix discrepancies. Do not finish
until all six required files exist and are non-empty.
"""Tecnologia

Há uma decisão de design importante aqui.

Não estamos pedindo que o modelo faça todo o raciocínio da análise financeira apenas na resposta. 

As instruções deixam claro que ele deve escrever código, executá-lo, inspecionar os resultados, verificar cálculos selecionados e corrigir quaisquer discrepâncias.

Também informamos ao agente que toda operação analítica deve acontecer em /mnt/data dentro do sandbox hospedado.

Isso dá ao agente um workflow claro:

Encontrar os dados → validar → escrever o script de análise → executar → gerar artefatos → inspecionar os resultados → conferir cálculos → corrigir erros se necessário.

Isso transforma o sandbox em um ambiente de trabalho real, não apenas um armazenamento temporário de arquivos.

5. Conecte o agente ao sandbox

Em seguida, conectamos um agente da OpenAI ao container que criamos anteriormente.

Fazemos isso usando o ShellTool.

from agents import Agent, ModelSettings, Runner, ShellTool

sandbox_shell = ShellTool(
    environment={
        "type": "container_reference",
        "container_id": container.id,
    }
)

analyst = Agent(
    name="Sandbox Financial Analyst",
    model=MODEL,
    instructions=ANALYST_INSTRUCTIONS,
    tools=[sandbox_shell],
    model_settings=ModelSettings(tool_choice="required"),
)Tecnologia

A parte importante é:

"type": "container_reference",
"container_id": container.id,Tecnologia

Isso indica ao ShellTool para conectar o agente ao sandbox que já criamos, em vez de criar ou usar outro ambiente de execução.

Também definimos:

tool_choice="required"Tecnologia

Isso força o agente a usar uma ferramenta durante a execução, em vez de concluir a tarefa apenas com uma resposta de texto normal.

Para este tutorial, é exatamente o que queremos. 

O agente não deve simplesmente explicar como calcular as métricas financeiras. Ele deve usar o shell, executar código dentro do sandbox e produzir os arquivos solicitados.

6. Deixe o agente executar a análise

Com o dataset enviado, o sandbox em execução e o agente conectado via ShellTool, podemos iniciar a análise.

result = await Runner.run(
    analyst,
    "Analyze Northstar entirely inside the sandbox and produce every required artifact.",
    max_turns=30,
)

display(Markdown(result.final_output))Tecnologia

Isso inicia o agente analista financeiro e dá a ele acesso ao sandbox que criamos anteriormente.

A saída final do agente confirma que a análise foi concluída com sucesso dentro de /mnt/data, incluindo validação dos dados, verificação de métricas e criação dos seis artefatos exigidos.

7. Baixe os artefatos gerados

A análise foi concluída, mas os arquivos gerados ainda estão dentro do sandbox da OpenAI.

Agora, listamos os arquivos no container, verificamos se todos os artefatos esperados foram criados e fazemos o download para o nosso diretório local.

remote_files = {
    Path(item.path).name: item
    for item in client.containers.files.list(container.id)
}

missing = [
    name for name in EXPECTED_ARTIFACTS
    if name not in remote_files
]

assert not missing, f"Sandbox did not create: {missing}"

for name in EXPECTED_ARTIFACTS:
    remote = remote_files[name]
    destination = OUTPUT_DIR / name

    client.containers.files.content.retrieve(
        remote.id,
        container_id=container.id,
    ).write_to_file(destination)

    assert destination.stat().st_size > 0, \
        f"Empty artifact: {destination}"

    print(
        f"Downloaded {name}: "
        f"{destination.stat().st_size:,} bytes"
    )Tecnologia

Saída:

Downloaded analyze_financials.py: 22,778 bytes
Downloaded calculated_metrics.csv: 3,740 bytes
Downloaded unusual_movements.csv: 25,405 bytes
Downloaded financial_trends.svg: 13,846 bytes
Downloaded investment_analysis.md: 12,159 bytes
Downloaded analysis_run.json: 1,522 bytesTecnologia

Neste ponto, você pode abrir o diretório local financial_analysis_output e inspecionar tudo o que o agente criou.

A pasta contém o script de análise, as métricas calculadas, os flags de movimentos atípicos, o memorando completo de investimento, o manifesto de validação e uma visualização SVG das tendências financeiras.

O arquivo investment_analysis.md contém a análise principal por escrito, incluindo visão executiva, lucratividade, liquidez, alavancagem, fluxo de caixa, movimentos atípicos e os cenários otimista e pessimista.

Você também pode abrir o financial_trends.svg para ver os resultados visuais. 

Ele oferece uma visão rápida das principais tendências financeiras, como receita, lucratividade, margens e outras métricas-chave, sem precisar ler o relatório completo primeiro.

Um detalhe importante é que não baixamos simplesmente quaisquer arquivos que o agente tenha criado. 

O notebook primeiro compara o conteúdo do sandbox com o EXPECTED_ARTIFACTS.

Se algum arquivo obrigatório estiver faltando, a asserção falha. Também verificamos que todo arquivo baixado não está vazio.

Isso nos dá uma etapa simples de verificação antes de aceitar a saída do agente.

8. Limpe o sandbox

Depois que os arquivos forem baixados e verificados, não precisamos mais do sandbox temporário nem do arquivo-fonte enviado.

Exclua ambos os recursos:

client.containers.delete(container.id)
client.files.delete(uploaded_input.id)Tecnologia

Isso remove o container hospedado e o dataset financeiro enviado após a conclusão do workflow.

Limpar recursos temporários é um bom passo final, especialmente quando você cria sandboxes regularmente como parte de um fluxo de agentes.

Considerações finais

A maior vantagem do sandbox hospedado pela OpenAI é que todo o workflow fica dentro de um único ecossistema.

Você não precisa conectar um provedor de sandbox separado, provisionar seu próprio ambiente em nuvem ou construir e manter sua própria infraestrutura de containers. 

Você pode criar um sandbox, anexar arquivos, controlar o acesso à rede, deixar o agente trabalhar nele, recuperar os resultados e excluir o ambiente quando terminar — tudo pela plataforma da OpenAI.

Isso deixa o fluxo muito mais simples de gerenciar.

Neste tutorial, usei o OpenAI Agents SDK com o ShellTool porque me dá uma forma direta de conectar um agente a um container existente mantendo controle sobre instruções, arquivos, ferramentas e fluxo de execução.

Há outras formas de construir o mesmo tipo de workflow dentro do ecossistema da OpenAI, incluindo APIs de agentes mais diretas e abstrações de sandbox em nível mais alto. 

Para este exemplo, porém, o Agents SDK ofereceu o equilíbrio certo entre simplicidade e controle.

A principal lição é que agora você pode dar a um agente de IA um ambiente real de execução sem sair do ecossistema da OpenAI:

Crie o sandbox → anexe os dados → conecte o agente → rode a tarefa → recupere os artefatos → exclua o sandbox.

Para aplicações com agentes que precisam executar código, manipular arquivos, gerar relatórios ou realizar análises de múltiplas etapas, esse é um padrão muito útil.