OpenAI Agents SDK: como executar agentes em sandboxes da Modal

O novo fluxo de trabalho de sandbox de Agents da OpenAI muda a forma como a execução do agente é estruturada. Em vez de manter agente, arquivos, ferramentas e runtime em um único loop confuso, o framework separa a camada de orquestração confiável do ambiente de execução.

Isso significa que sua aplicação cuida da lógica do agente, das chamadas de modelo e da tomada de decisão, enquanto o trabalho de fato acontece em um workspace isolado (sandbox) com acesso a arquivos, comandos e saídas geradas.

Essa configuração é especialmente útil quando o agente precisa ir além de apenas responder com base no contexto do prompt. Por exemplo, ele pode inspecionar um projeto, escrever ou modificar arquivos, executar código, testar resultados e gerar artefatos em um ambiente controlado.

Neste guia, vamos combinar o framework OpenAI Agents com Modal Sandboxes para construir uma aplicação agentic prática. O agente poderá rodar em um ambiente Modal isolado, executar comandos com segurança, trabalhar com arquivos e devolver saídas úteis para a aplicação principal.

Para uma introdução sem usar sandboxes, recomendo também ler nosso OpenAI Agents SDK Tutorial. 

O que há de novo no OpenAI Agents SDK?

A nova OpenAI Agents SDK traz uma forma mais limpa de construir agentes que trabalham com arquivos reais, ferramentas e ambientes de execução. Em vez de manter tudo dentro de um único loop de prompt, o SDK agora separa a camada de orquestração do agente da sandbox onde o trabalho acontece.

Principais atualizações:

• Suporte nativo a sandbox para executar agentes em ambientes isolados
• Manifest para definir os arquivos, pastas e saídas que o agente pode acessar
• SandboxAgent para conectar o agente a um workspace sandboxed
• SandboxRunConfig para controlar onde e como a execução na sandbox acontece
• Ferramentas no estilo Codex para edição de arquivos, comandos de shell e inspeção de projetos
• Suporte a MCP para permitir que agentes se conectem a ferramentas e serviços externos
• Suporte a Skills e AGENTS.md para instruções de projeto mais claras para os agentes
• Suporte a vários provedores de sandbox, incluindo Modal, E2B, Cloudflare, Daytona, Blaxel, Runloop e Vercel

Em conjunto, essas atualizações facilitam a criação de apps agentic que conseguem inspecionar projetos, rodar código, editar arquivos e retornar saídas geradas a partir de um workspace controlado.

1. configurando o projeto

Neste projeto de demonstração, vamos construir um pequeno exemplo de triagem de chamados de suporte usando o OpenAI Agents SDK e Modal Sandboxes. O app criará um workspace em sandbox, adicionará alguns arquivos de projeto e, em seguida, pedirá para um agente GPT-5.4-mini inspecionar esses arquivos antes de responder.

Comece instalando os pacotes necessários no seu ambiente:

pip install "openai-agents[modal]" modal

Antes de rodar o projeto, você vai precisar de duas contas:

• Conta na OpenAI: Crie uma conta na OpenAI Platform e adicione créditos de API usando um cartão de crédito. Garanta que sua conta esteja verificada para acessar os modelos mais recentes suportados.
• Conta na Modal: Cadastre-se na Modal. O plano gratuito inclui créditos mensais, suficientes para testar este guia.

Em seguida, adicione sua chave de API da OpenAI ao ambiente local.

• No macOS ou Linux: export OPENAI_API_KEY="your_openai_api_key"
• No Windows PowerShell: $env:OPENAI_API_KEY="your_openai_api_key"

Depois, autentique a Modal localmente:

modal setup

Isso vai abrir uma janela no navegador e pedir para você entrar na Modal. Após entrar, aprove a solicitação de geração de token. A Modal adicionará as credenciais automaticamente ao seu ambiente local.

Quando tudo estiver configurado, você deverá ver uma mensagem de sucesso no terminal confirmando que a autenticação na Modal foi concluída.

2. definindo o workspace da sandbox

Agora, crie um arquivo Python, por exemplo main.py, e adicione os imports necessários. Eles trazem o OpenAI Agents SDK, classes de configuração da sandbox e o cliente da Modal. 

import asyncio

from agents import ModelSettings, Runner
from agents.run import RunConfig
from agents.sandbox import Manifest, SandboxAgent, SandboxRunConfig
from agents.sandbox.entries import File
from agents.extensions.sandbox import ModalSandboxClient, ModalSandboxClientOptions

Agora precisamos definir o workspace da sandbox. Neste exemplo, o workspace inclui um pequeno projeto de triagem de chamados com um README.md, um arquivo da aplicação e uma checklist de release.

manifest = Manifest(
    entries={
        "README.md": File(
            content=(
                b"# Support Ticket Triage\n\n"
                b"Small service that labels customer tickets by urgency and team.\n"
            )
        ),
        "src/app.py": File(
            content=(
                b"def route_ticket(subject: str, customer_tier: str) -> dict:\n"
                b"    urgent = customer_tier == \"enterprise\" or \"outage\" in subject.lower()\n"
                b"    return {\n"
                b"        \"priority\": \"high\" if urgent else \"normal\",\n"
                b"        \"team\": \"support-ops\" if urgent else \"customer-care\",\n"
                b"    }\n"
            )
        ),
        "docs/release-checks.md": File(
            content=(
                b"# Release Checks\n\n"
                b"- Confirm routing rules match the current support escalation policy.\n"
            )
        ),
    }
)

O Manifest informa ao agente quais arquivos existem dentro da sandbox. Isso dá ao agente uma estrutura de projeto real para inspecionar, editar e raciocinar, em vez de depender só do texto no prompt.

Neste caso, o agente poderá revisar a lógica de roteamento dos chamados, checar a documentação e fazer mudanças dentro do workspace em sandbox.

3. criando o agente da sandbox

Com o workspace definido, crie o agente respaldado por sandbox. Um SandboxAgent é projetado para trabalhar com um workspace real, o que significa que ele pode inspecionar arquivos, entender a estrutura do projeto e responder com base no que existe dentro da sandbox.

agent = SandboxAgent(
    name="Modal Sandbox Assistant",
    model="gpt-5.4-mini",
    instructions=(
        "You are a coding assistant reviewing a small production service. "
        "Inspect the sandbox workspace before answering. "
        "Keep the answer short and practical."
    ),
    default_manifest=manifest,
    model_settings=ModelSettings(tool_choice="required"),
)

Aqui estamos nomeando o agente como Modal Sandbox Assistant e usando o modelo gpt-5.4-mini para respostas mais rápidas. As instruções pedem para o agente inspecionar o workspace em sandbox antes de responder, o que é importante quando a resposta depende dos arquivos reais do projeto.

O default_manifest=manifest conecta o agente ao workspace que criamos antes. A configuração tool_choice="required" incentiva o agente a usar as ferramentas da sandbox disponíveis em vez de responder só de memória ou do contexto do prompt.

4. criando o cliente da Modal Sandbox

Em seguida, crie o cliente da Modal. Ele é a conexão entre o workflow do OpenAI Agents e a sandbox da Modal, onde a execução real de arquivos e comandos vai acontecer.

client = ModalSandboxClient()
options = ModalSandboxClientOptions(
    app_name="openai-agents-modal-demo",
    workspace_persistence="tar",
)

O ModalSandboxClient() indica ao agente que use a Modal como provedora da sandbox. Assim, o agente pode rodar em um ambiente Modal isolado em vez de rodar diretamente na sua máquina local.

O ModalSandboxClientOptions controla como a sandbox da Modal é configurada. Aqui, app_name dá um nome claro ao app na Modal, enquanto workspace_persistence="tar" informa à Modal como empacotar e persistir os arquivos do workspace durante a execução.

5. iniciando a sessão da sandbox

Com o cliente e as opções prontos, crie a sandbox a partir do manifest e inicie a sessão. 

sandbox = await client.create(
    manifest=manifest,
    options=options,
)

await sandbox.start()

A chamada client.create() cria uma nova sandbox na Modal usando os arquivos definidos no Manifest. Isso faz com que a sandbox comece com a mesma estrutura do projeto, incluindo README.md, src/app.py e docs/release-checks.md.

Depois, await sandbox.start() inicia a sessão da sandbox. A partir desse ponto, você tem um workspace isolado em produção na Modal, pronto para o agente inspecionar arquivos, rodar comandos e trabalhar no projeto.

6. executando o agente na sandbox

Com a sandbox ativa, rode o agente nela passando a sessão ao vivo por meio do SandboxRunConfig. Isso informa ao OpenAI Agents SDK que o agente deve usar o workspace da Modal durante a execução. 

result = await Runner.run(
    agent,
    (
        "Explain what this service does and name one production check "
        "before release. Keep it under 3 sentences."
    ),
    run_config=RunConfig(
        sandbox=SandboxRunConfig(session=sandbox),
        workflow_name="Modal sandbox example",
    ),
)

print(result.final_output)

É aqui que tudo se conecta. O modelo cuida do raciocínio, enquanto a sandbox dá acesso aos arquivos reais do workspace.

Neste exemplo, o agente pode inspecionar o projeto de triagem de chamados, entender o que o serviço faz, verificar as notas de release e retornar uma resposta curta com base nos arquivos dentro da sandbox da Modal.

7. limpando a sandbox

Depois que a execução do agente terminar, exclua a sandbox para não deixar sessões ociosas rodando na Modal.

await client.aclose(sandbox)

Isso remove a sessão após o término do trabalho. É um bom hábito, pois sessões em sandbox consomem recursos de computação enquanto estão ativas.

Em um projeto real, coloque isso dentro de um bloco finally. Assim, a limpeza acontece mesmo que a chamada ao agente falhe ou o script tenha algum erro.

8. exemplo de código completo

Aqui está o script completo em um só lugar. Ele cria o workspace, inicia uma sandbox da Modal, executa o agente dentro dela, imprime a saída final e, depois, limpa a sessão da sandbox. 

import asyncio

from agents import ModelSettings, Runner
from agents.extensions.sandbox import ModalSandboxClient, ModalSandboxClientOptions
from agents.run import RunConfig
from agents.sandbox import Manifest, SandboxAgent, SandboxRunConfig
from agents.sandbox.entries import File


async def main():
    manifest = Manifest(
        entries={
            "README.md": File(
                content=(
                    b"# Support Ticket Triage\n\n"
                    b"Small service that labels customer tickets by urgency and team.\n"
                )
            ),
            "src/app.py": File(
                content=(
                    b"def route_ticket(subject: str, customer_tier: str) -> dict:\n"
                    b"    urgent = customer_tier == \"enterprise\" or \"outage\" in subject.lower()\n"
                    b"    return {\n"
                    b"        \"priority\": \"high\" if urgent else \"normal\",\n"
                    b"        \"team\": \"support-ops\" if urgent else \"customer-care\",\n"
                    b"    }\n"
                )
            ),
            "docs/release-checks.md": File(
                content=(
                    b"# Release Checks\n\n"
                    b"- Confirm routing rules match the current support escalation policy.\n"
                )
            ),
        }
    )

    agent = SandboxAgent(
        name="Modal Sandbox Assistant",
        model="gpt-5.4-mini",
        instructions=(
            "You are a coding assistant reviewing a small production service. "
            "Inspect the sandbox workspace before answering. "
            "Keep the answer short and practical."
        ),
        default_manifest=manifest,
        model_settings=ModelSettings(tool_choice="required"),
    )

    client = ModalSandboxClient()
    options = ModalSandboxClientOptions(
        app_name="openai-agents-modal-demo",
        workspace_persistence="tar",
    )

    sandbox = await client.create(
        manifest=manifest,
        options=options,
    )

    await sandbox.start()

    try:
        result = await Runner.run(
            agent,
            (
                "Explain what this service does and name one production check "
                "before release. Keep it under 3 sentences."
            ),
            run_config=RunConfig(
                sandbox=SandboxRunConfig(session=sandbox),
                workflow_name="Modal sandbox example",
            ),
        )

        print(result.final_output)

    finally:
        await sandbox.aclose()

if __name__ == "__main__":
    asyncio.run(main())

Este script segue a estrutura atual de sandbox da OpenAI e usa a Modal como backend de execução. A lógica do agente fica no seu app Python, enquanto o workspace roda dentro de uma sandbox da Modal.

O bloco finally é importante porque fecha e exclui a sandbox mesmo se a execução do agente falhar. Isso ajuda a manter seu ambiente na Modal limpo e evita deixar sessões ociosas rodando.

9. testando o app localmente

Quando o script estiver pronto, execute-o localmente a partir do terminal na mesma pasta onde o main.py foi salvo:

python main.py

Se tudo estiver configurado corretamente, o script criará uma sandbox na Modal, carregará o manifest nela, executará o agente da OpenAI no workspace, imprimirá a resposta e depois fará a limpeza da sandbox.

Você deverá ver uma saída semelhante a esta:

This service triages customer support tickets by assigning urgency and routing them to the right team. One production check before release is to confirm the routing rules still match the current support escalation policy.

A execução pode levar alguns segundos. Enquanto estiver rodando, abra seu dashboard da Modal, clique no app openai-agents-modal-demo e confira os logs. Isso ajuda a confirmar que a sandbox foi criada, iniciada, usada pelo agente e limpa com sucesso.

10. criando um app web interativo 

O primeiro script é estático: você envia um pedido, recebe uma resposta e para por aí. Para facilitar o uso, podemos transformá-lo em um app web interativo usando o Gradio. Assim, dá para conversar com o agente na sandbox, fazer perguntas de acompanhamento, criar ou editar arquivos e rodar testes em uma interface simples no navegador.

Primeiro, instale a versão mais recente do Gradio:

pip install gradio

Depois, crie um novo arquivo chamado app.py e copie o código do app do Gradio (OpenAI-Agents-in-Modal/app.py) para ele. Esse app usa a mesma configuração de OpenAI Agents e Modal Sandbox, mas embrulhada em uma interface de chat. O código também reutiliza a sessão da sandbox quando possível, então cada mensagem não precisa criar uma sandbox totalmente nova do zero.

Rode o app com:

python app.py

Você verá uma URL local no seu terminal:

* Running on local URL:  http://127.0.0.1:7860
* To create a public link, set share=True in launch().

Abra a URL local no navegador para usar o app de chat. Você pode pedir para o agente inspecionar o projeto, explicar o que o serviço faz, criar novos arquivos auxiliares, editar arquivos existentes ou rodar testes dentro da sandbox da Modal.

Por exemplo, primeiro pedi para explicar o que o serviço do projeto faz e, em poucos segundos, ele retornou uma resposta detalhada com base nos arquivos da sandbox.

Em seguida, pedi para o agente criar um novo arquivo auxiliar de roteamento. Esse pedido levou um pouco mais de tempo porque o agente teve que modificar o workspace, adicionar testes e rodar a suíte de testes.

O agente criou src/routing_rules.py, adicionou um novo arquivo de teste em tests/test_routing_rules.py e verificou as mudanças com pytest. Os 6 testes passaram, confirmando que o novo helper funcionou corretamente e que a lógica existente de roteamento de chamados continuou íntegra.

Em linhas gerais, esse app com Gradio oferece um frontend simples para trabalhar com um agente da OpenAI rodando na Modal. O usuário manda uma mensagem pelo navegador, o app repassa para o SandboxAgent, o agente trabalha dentro da sandbox da Modal e a resposta final aparece na interface do chat.

considerações finais

OpenAI Agents com Modal Sandboxes oferece uma forma limpa de criar apps agentic que trabalham com arquivos reais, executam comandos e retornam saídas úteis de um ambiente isolado. 

O processo de configuração da Modal foi tranquilo, e criar a sandbox em si foi direto. Com tudo conectado, o agente conseguiu inspecionar o projeto, criar um novo arquivo auxiliar de roteamento, adicionar testes e confirmar que os 6 testes passaram.

Dito isso, construir o app interativo e configurar o modelo deu mais trabalho do que o esperado. As etapas de criação de arquivos e testes também demoraram mais porque, às vezes, a sandbox da Modal esgotava o tempo. Precisei aumentar o timeout da sandbox de 300 segundos para 600 segundos para dar tempo suficiente para o agente concluir todo o fluxo.

Outro ponto de dor foi o logging e a visibilidade. Enquanto aguardava o término do agente, nem sempre ficava claro o que o Agents SDK estava fazendo em segundo plano. Mesmo os logs da Modal nem sempre mostravam detalhes suficientes para entender se o agente estava inspecionando arquivos, editando código ou executando testes. 

No futuro, seria útil ter logs mais verbosos do agente, semelhantes ao que você vê em ferramentas como o Claude Code, onde dá para acompanhar cada etapa com mais clareza.

No geral, é um workflow sólido para construir apps com agentes em sandbox, especialmente se o agente precisar trabalhar com arquivos, código e saídas geradas. Você encontra o projeto completo no GitHub, pode clonar localmente e rodar: kingabzpro/OpenAI-Agents-in-Modal.

Se quiser aprender a fundo como construir sistemas de IA avançados, recomendo nosso curso Building Scalable Agentic Systems.