A primeira decisão é verificar se o agente precisa de um sistema de arquivos e de comandos próprios. Na Agents API, a sessão pode usar nenhum ambiente (none), um sandbox hospedado pela OpenAI (openai_hosted) ou um ambiente conectado por sua infraestrutura (self_hosted). Uma VPC própria é uma forma de implantar a terceira opção, não um quarto tipo da API. A escolha determina onde o código roda, quem controla a rede e como os arquivos são preservados. Consulte a arquitetura oficial.
Primeiro, separe sessão, ferramenta e sandbox
A sessão mantém o trabalho conversacional do agente; o ambiente é o local opcional em que ele executa shell, lê e altera arquivos. Um agente sem ambiente ainda pode acionar funções implementadas no seu aplicativo e servidores MCP remotos. Isso não lhe concede automaticamente um terminal ou diretório de trabalho. Um sandbox resolve tarefas em que a saída depende de arquivos, pacotes, scripts, prévias ou estado de execução. A documentação dos Sandbox Agents no Agents SDK também trata de provedores locais, Docker e hospedados, mas o SDK tem arquitetura de execução própria: não confunda a escolha do provedor no SDK com os três valores de ambiente da Agents API.
Comparação prática das três rotas
| Critério | Sem ambiente | Hospedado pela OpenAI | Infraestrutura/VPC própria |
|---|---|---|---|
| Execução | Funções do aplicativo e MCP remoto; sem shell nativo do agente. | Shell e arquivos em workspace Linux provisionado pela OpenAI. | Shell e arquivos no executor implantado por você. |
| Isolamento | Definido nos serviços e permissões das ferramentas. | Workspace separado por sessão, sujeito às políticas configuradas. | Definido por sua VM, contêiner, identidade e segmentação de rede. |
| Arquivos e estado | Itens da sessão e armazenamento externo do aplicativo. | Arquivos entre turnos enquanto o sandbox existir; saídas publicadas como artefatos. | Persistência, cópias e retenção sob responsabilidade do operador. |
| Rede e segredos | Governados por cada ferramenta ou servidor de integração. | Saída de rede configurável; segredos devem ficar fora do código gerado. | Políticas de VPC, proxy, secret manager e saída para serviços necessários. |
| Custo e operação | Sem computação de sandbox, mas há custos de modelo e ferramentas. | Contêiner cobrado separadamente do modelo; menos operação de infraestrutura. | Computação, rede, armazenamento, segurança e ciclo de vida geridos por você. |
Quando escolher nenhum ambiente
Escolha none quando a tarefa é interpretar solicitações, consultar dados por ferramentas de escopo definido ou produzir resposta estruturada, sem necessidade de shell, instalação de pacotes ou workspace próprio. Um fluxo de FAQ que chama uma busca autorizada, ou uma consulta de status por função somente de leitura, não precisa ganhar um computador apenas por usar IA.
A contrapartida é explícita: Bash, apply-patch, arquivos do workspace e MCPs executados dentro do executor não ficam disponíveis. Se um fluxo precisar processar um anexo, o aplicativo poderá fazê-lo por uma função controlada, mas essa computação ocorrerá no serviço da função e não em um sandbox do agente. Veja o desenho sem ambiente.
Quando usar ambiente hospedado
O tipo openai_hosted é apropriado quando o agente precisa receber arquivos, instalar dependências, executar scripts e entregar artefatos, sem que a equipe queira provisionar a máquina de execução. O ambiente é Linux, com diretório de trabalho /workspace; pacotes, comandos iniciais e arquivos podem ser configurados na criação da sessão. A configuração reutilizável de template não representa um workspace em execução.
A política de rede aceita saída habilitada, bloqueada ou restrita a hosts especificados. Como a documentação informa que a saída habilitada é o padrão fora de uma política herdada, um piloto com dados sensíveis deve definir a restrição explicitamente. O código gerado pode ler variáveis de ambiente; credenciais duradouras devem permanecer no cofre ou em um intermediário confiável, e não em prompts ou arquivos do agente.
Cada sessão usa seu próprio workspace. Arquivos persistem entre turnos enquanto o sandbox existir; arquivos colocados em /workspace/outputs são publicados como artefatos imutáveis ao terminar um turno e podem continuar disponíveis após a expiração do ambiente. A documentação descreve a possível exclusão se atividade e keep-alives cessarem por uma hora. Portanto, trate o workspace vivo como temporário e retenha o resultado no armazenamento apropriado. Confira configuração, rede, expiração e cobrança e arquivos e artefatos.
Quando conectar a própria VPC
Use self_hosted se o processamento depende de uma rede privada, imagem personalizada, bibliotecas internas, política de execução específica ou dados que precisam permanecer no seu domínio de infraestrutura. Na Agents API, o harness continua gerenciado pela OpenAI, mas o executor codex exec-server roda em uma máquina ou contêiner seu; não se trata de hospedar todo o serviço de agentes.
O executor registra o ambiente e mantém uma conexão WebSocket de saída para receber comandos. Planeje acesso de saída aos endpoints exigidos pela documentação e aos serviços liberados para a carga. Sua aplicação administra provisionamento, mapeamento entre sessão e computação, reconexão, desligamento, arquivos e retenção. Isole por usuário ou carga que não pode compartilhar dados: agentes no mesmo ambiente podem alcançar os mesmos arquivos e credenciais. Veja conexão e requisitos de rede e ciclo de vida do executor.
Uma VPC privada não torna toda integração automaticamente privada. Ferramentas MCP executadas dentro do executor saem pela sua rede; servidores MCP remotos são alcançados a partir do serviço da OpenAI e precisam ser acessíveis a ele. Esse caminho deve ser desenhado e aprovado separadamente.
Controles que importam nos três modelos
- Isolamento: separe tenants e cargas sensíveis, limite usuário do processo e acesso aos diretórios; não use uma pasta compartilhada como fronteira de segurança.
- Segredos: mantenha a chave da aplicação fora do sandbox. No self-hosted, use chave restrita de executor; para terceiros, prefira secret manager e proxy que injete credenciais apenas em destinos autorizados.
- Rede: bloqueie saída desnecessária; no hospedado, use domínios permitidos quando couber. Avalie redirecionamentos e caminhos distintos de MCP.
- Arquivos: limite dados de entrada, valide saídas e retenha artefatos fora do workspace; revise o que pode ser publicado ou baixado.
- Ações: imponha validação de parâmetros, menor privilégio e aprovação humana para escrita, envio externo ou operação irreversível.
Sandbox reduz a superfície de execução, mas não substitui autorização de ferramentas, inspeção das saídas nem política de dados. A orientação de segurança para sandboxes destaca que código gerado pode acessar tudo que estiver disponível naquele ambiente.
Persistência e custo: o que contabilizar
Separe três coisas: histórico da sessão, arquivos ativos no ambiente e artefatos ou dados retidos fora dele. No modo sem ambiente, não existe filesystem de sandbox. No hospedado, a permanência entre turnos depende da vida do ambiente e a publicação segue a regra de artefatos. No self-hosted, snapshots, volumes e backup dependem do seu provedor e da aplicação.
Compare o custo total por tarefa concluída, não apenas por chamada ao modelo: tokens, tempo de contêiner, inicialização de pacotes, armazenamento, tráfego, filas, monitoração e horas de operação. A hospedagem da OpenAI cobra contêiner e uso do modelo separadamente. Na VPC própria, some custos e trabalho de operar a computação, além da API. A opção sem ambiente evita o contêiner do agente, mas não os custos dos serviços acionados.
Três cenários de projeto
1. FAQ com consulta somente de leitura
O agente interpreta a pergunta e usa uma função que consulta uma base autorizada, devolvendo resposta com fonte. Comece sem ambiente. Faça a função validar o escopo da consulta, registrar acessos e não devolver dados de outros clientes. Só acrescente workspace se a tarefa passar a exigir transformação complexa de arquivos.
2. Relatórios a partir de planilhas enviadas
O agente recebe planilhas, executa Python, gera gráficos e entrega arquivos para download. O hospedado é um ponto de partida possível. Teste tipos e limites de arquivo, bloqueie rede se dispensável, publique os resultados em /workspace/outputs e armazene o que precisa sobreviver à sessão.
3. Auditoria interna ligada a ERP privado
O agente precisa consultar sistemas acessíveis só na VPC e usar pacotes internos. Implante executor próprio com credenciais de escopo mínimo, segmentação por cliente ou tarefa, logs e política de retenção. Uma alternativa para escopo menor é manter o agente sem ambiente e expor apenas funções de negócio que validem cada operação, sem dar acesso geral à rede interna.
Roteiro de piloto antes da produção
- Defina uma tarefa representativa e seus dados permitidos: só texto, anexos, código, rede privada ou escrita em sistemas.
- Registre o que pode executar, ler, gravar, publicar e acessar pela rede. Separe credenciais do agente e da aplicação.
- Implemente a opção mais simples que cumpra o requisito, mantendo funções com escopo definido quando bastarem.
- Teste entrada maliciosa, vazamento entre clientes, comandos inesperados, saída para domínio não autorizado e ações sem aprovação.
- Interrompa uma execução e retome a sessão: observe o estado realmente preservado e o comportamento após expiração ou reconexão.
- Valide a entrega e a remoção de arquivos, a retenção dos artefatos e a eliminação de segredos em logs e saídas.
- Meça sucesso da tarefa, latência, tempo de provisionamento, gasto por execução e esforço de suporte.
- Documente critérios de promoção e rollback, alertas, limites, dono do ambiente e procedimento de desligamento.
Regra operacional: sem ambiente para ferramentas pontuais sem workspace; hospedado para execução e arquivos com operação de infraestrutura delegada; VPC própria quando rede, software, isolamento ou políticas internas exigirem execução sob seu controle. A decisão deve ser validada por um piloto com os mesmos dados, ferramentas e riscos previstos para a produção.
