- API Agents, SDK Agents e API Responses
- O que é um Harness de Agente?
- Por que um agente ainda precisa de um Sandbox
- Novita Sandbox nesta arquitetura
- Ciclo de vida, persistência e trabalhos de longa duração
- Conectar Novita ao caminho auto-hospedado
- Segurança e credenciais
- Custos e limites
- Onde esta arquitetura se encaixa
- FAQ
- Artigos Recomendados
A API OpenAI Agents permite iniciar um agente de nuvem durável por meio de uma única chamada de criação de sessão, enquanto a OpenAI executa o harness do agente na nuvem. O Novita Sandbox não substitui a API Agents ou seu harness gerenciado pela OpenAI. Ele oferece um runtime isolado e com estado para o caminho de execução auto-hospedado documentado pela OpenAI: sua aplicação conecta o sandbox à sessão, o agente executa comandos e edita arquivos dentro desse runtime, e sua aplicação possui o ciclo de vida do sandbox. Essa divisão é importante quando você deseja um fluxo de trabalho de agente hospedado pela OpenAI, mas precisa de um ambiente separado e reutilizável para código, arquivos, navegadores, uso de computador e trabalhos de longa duração.
Este guia explica os principais conceitos da API, como o harness e o ambiente dividem responsabilidades, como conectar um Novita Sandbox ao caminho auto-hospedado e o que verificar antes de passar de um protótipo para produção. Se você precisa apenas da página do produto, Novita Sandbox é o melhor ponto de partida.
API Agents, SDK Agents e API Responses
A comparação de runtimes de agente da OpenAI separa três modelos de integração:
| Você quer | Use | O que gerencia o estado |
|---|---|---|
| Executar uma tarefa de longa duração por meio de um harness Codex gerenciado pela OpenAI | API Agents | Configuração de sessão, turnos e itens salvos |
| Manter o loop do agente em sua aplicação | SDK Agents | Estado da sua aplicação, sessões do SDK ou conversas do Responses |
| Chamar modelos diretamente e orquestrar tudo você mesmo | API Responses | Histórico da sua aplicação ou conversas do Responses |
A API Agents é a opção de nível mais alto. A OpenAI a descreve como acesso ao harness Codex por meio de uma API gerenciada pela OpenAI. Ela lida com sessões, orquestração, compactação de contexto e recuperação. O SDK Agents é executado dentro da sua aplicação e oferece mais controle sobre implantação, armazenamento, aprovações e integração de runtime. A API Responses é a mais próxima da camada de modelo. Essa divisão é útil porque “Agente” pode significar uma configuração reutilizável de modelo/ferramenta ou um agente durável em execução; a documentação da API usa esses termos de forma diferente em cada runtime.
O que é um Harness de Agente?
Um harness de agente é o serviço em nuvem que envolve uma iteração do agente. Ele envia instruções e contexto para o modelo, invoca ferramentas, rastreia o progresso, lida com interrupção e retomada e organiza o trabalho em um fluxo inspecionável. Na API Agents, esse harness é o harness Codex gerenciado.
O harness gerenciado oferece suporte a:
- Executar comandos e código quando um ambiente está anexado.
- Aplicar habilidades e instruções relevantes.
- Conectar-se a dados externos por meio de ferramentas ou MCP.
- Direcionar o agente enquanto ele trabalha.
- Resumir trabalhos anteriores para gerenciar a janela de contexto.
- Dividir o trabalho em subtarefas e delegar a subagentes.
- Retomar uma sessão de onde parou.
Isso não significa que sua aplicação desaparece. Sua aplicação ainda cria a sessão, envia entrada, recebe eventos, lida com aprovações ou chamadas de função e decide como armazenar IDs e artefatos. O harness reduz o trabalho de orquestração; ele não remove a política do produto.
Por que um agente ainda precisa de um Sandbox
Alguns agentes respondem perguntas ou chamam APIs remotas sem tocar em um sistema de arquivos. Outros precisam criar arquivos, instalar dependências, executar scripts, inspecionar um navegador, controlar uma área de trabalho ou manter uma tarefa de várias etapas ativa enquanto o usuário está ausente. Um sandbox oferece a essas ações um ambiente de execução substituível em vez de permitir que elas toquem no servidor do produto ou na máquina local.
A API Agents trata o ambiente como opcional. A documentação de arquitetura da OpenAI oferece suporte a três opções de execução:
none— o harness não possui shell ou sistema de arquivos. As chamadas de função retornam resultados para o harness.openai_hosted— a OpenAI provisiona e gerencia o sandbox.self_hosted— sua aplicação inicia e conecta o ambiente, permitindo que você use sua própria computação, rede privada ou software personalizado.
É aqui que o limite entre os dois sistemas fica mais claro. A API Agents e a OpenAI podem hospedar o harness, mas um ambiente auto-hospedado permite que sua equipe selecione a plataforma de execução. Essa escolha afeta isolamento, formato do sistema de arquivos, rede, SDKs, comportamento de pausa/retomada, faturamento e quanta infraestrutura você mantém.
Novita Sandbox nesta arquitetura
Novita Sandbox é um ambiente de execução gerenciado para agentes de IA. A visão geral oficial descreve runtimes isolados e com estado para executar código, instalar dependências, acessar arquivos, usar navegadores e preservar o estado entre sessões sem gerenciamento de infraestrutura. Em uma pilha direta apenas com Novita, sua aplicação cria o sandbox, o modelo ou framework de agente escolhe chamadas de ferramenta, o sandbox as executa, e sua aplicação mantém política, aprovações e armazenamento fora do runtime.
Com a API Agents, o enquadramento preciso recomendado é complementar, não nativo: os guias atuais de sandbox auto-hospedado da OpenAI listam Cloudflare, Daytona, DigitalOcean, E2B, Blaxel, Modal, Runloop, OCI e Vercel como provedores documentados. O Novita Sandbox não está atualmente nessa lista de provedores. O caminho prático é, portanto, usar o Novita como seu ambiente de execução gerenciado pela aplicação e conectá-lo a uma sessão da API Agents por meio do contrato de ambiente auto-hospedado da OpenAI. Isso preserva a separação útil — a OpenAI executa o harness durável, o Novita Sandbox fornece o runtime — sem reivindicar uma integração oficial de provedor que a documentação atual não suporta.
O Novita Sandbox é construído em torno de cinco conceitos:
| Conceito | O que oferece ao agente |
|---|---|
| Sandbox | Um runtime isolado com seu próprio sistema de arquivos e espaço de processos |
| Template | Uma imagem inicial reproduzível, dependências, configuração e setup |
| Snapshot | Um estado de sandbox salvo que pode ser reutilizado para evitar configuração repetida |
| Secret | Valores criptografados com escopo de equipe que evitam codificar credenciais |
| Region | A localização dos endpoints atuais US v1/v2 |
O runtime oferece suporte a cargas de trabalho do tipo agente de codificação, agente de navegador, análise de dados, pesquisa e RL. A visão geral do Novita Sandbox é a fonte para regiões atuais e comportamento do ciclo de vida.
Ciclo de vida, persistência e trabalhos de longa duração
O Novita Sandbox tem três estados de ciclo de vida: em execução, pausado e eliminado. Um sandbox em execução pode executar comandos e atender conexões. Um sandbox pausado preserva o sistema de arquivos e o estado na memória, incluindo processos em execução e variáveis, enquanto o faturamento de CPU e RAM é interrompido. As conexões de rede são interrompidas até a retomada. Um sandbox eliminado é encerrado e não pode ser restaurado.
Dois controles de tempo limite acionam as transições: um tempo limite de sandbox conta regressivamente a partir da criação, e um tempo limite de inatividade é acionado quando nenhum cliente esteve conectado pela duração configurada. Em qualquer um dos eventos, você pode escolher pausar em vez de eliminar e, opcionalmente, ativar a retomada automática. Isso é útil para uma tarefa de edição de código que aguarda revisão, uma sessão de navegador que pausa entre etapas ou um notebook de análise de dados que retoma mais tarde com dependências e variáveis intactas.
Snapshots são diferentes de pausa. Pausar retém o estado atual do sandbox para aquela instância. Um snapshot captura o estado como um ambiente reutilizável, de modo que um novo sandbox possa iniciar com dependências, configuração e arquivos já presentes. Em produção, use templates para imagens base repetíveis, snapshots para estados de trabalho reutilizáveis e secrets para credenciais, em vez de incorporá-las em um template ou snapshot.
Conectar Novita ao caminho auto-hospedado
O guia de sandbox auto-hospedado da OpenAI define o formato da conexão. Sua aplicação cria uma sessão com environment.type: "self_hosted", recebe o ID do ambiente e a URL remota, inicia um executor dentro do seu runtime e, em seguida, relata a sessão como conectada. O comando executor oficial é:
codex exec-server \
--remote "<session.environment.remote_url>" \
--environment-id "<session.environment.id>"
O fluxo de eventos da sessão relata agent.session.environment.pending, connected ou failed. Você deve deixar o executor em execução enquanto o agente trabalha e coordenar o desligamento antes de interromper a computação.
O esboço a seguir mostra o lado do Novita nesse fluxo usando o SDK oficial do Novita. Ele cria um sandbox, prepara a autenticação sem colocar uma chave secreta no código-fonte e fornece o local para iniciar o executor da OpenAI. A maneira exata de injetar a chave do executor e aguardar o fluxo de eventos depende da sua aplicação e da versão do SDK da OpenAI.
import os
from novita_sandbox import Novita
def create_agent_runtime() -> str:
novita = Novita(api_key=os.environ["NOVITA_API_KEY"])
sandbox = novita.sandbox.create(
"codex",
timeout=3600,
envs={"CODEX_API_KEY": os.environ["CODEX_EXECUTOR_KEY"]},
)
try:
sandbox.git.clone(
"https://github.com/your-org/your-repo.git",
path="/home/user/repo",
username="x-access-token",
password=os.environ["GITHUB_TOKEN"],
depth=1,
)
print(
"Create the Agents API session with environment.type=self_hosted, "
"then start codex exec-server here."
)
except Exception:
sandbox.kill()
raise
return sandbox.sandbox_id
Antes de usar este caminho em produção, verifique os objetos atuais do SDK da OpenAI, o nome da chave de ambiente, o comportamento da URL remota e os requisitos de ciclo de vida em relação ao guia de sandbox auto-hospedado da OpenAI. Não presuma que a API de sessão gerenciará o sandbox para você; com self_hosted, essa responsabilidade é explicitamente sua.
Para o fluxo de trabalho mais simples (sem a API Agents), o guia do agente Codex do Novita mostra como executar a CLI do Codex diretamente no template codex, transmitir sua saída e eliminar o sandbox quando terminar.
Segurança e credenciais
Trate o harness, o sandbox e o servidor da aplicação como domínios de confiança separados.
- Mantenha chaves de API da OpenAI, chaves de API do Novita, tokens Git e credenciais de banco de dados fora de prompts e arquivos de código-fonte.
- Use os Secrets do Novita Sandbox para valores confidenciais com escopo de equipe usados dentro do sandbox.
- Use os vaults da OpenAI para credenciais que, segundo as orientações da OpenAI, pertencem fora do sandbox.
- Prefira acesso seguro ao sandbox. Os documentos do Novita dizem que o acesso seguro é ativado automaticamente para sandboxes criados com a versão 2.0.0 ou posterior do SDK; templates personalizados mais antigos podem precisar de uma reconstrução.
- Defina uma política de rede explícita e amplie-a apenas quando uma tarefa precisar.
- Revise o código e os artefatos gerados antes que recebam permissões mais amplas ou alcancem sistemas de produção.
Esses controles funcionam juntos. Um sandbox reduz o raio de explosão do código gerado, mas não autoriza o agente, valida a intenção ou decide quais artefatos podem sair do runtime.
Custos e limites
A OpenAI fatura o uso do modelo da API Agents pelas taxas de API do modelo selecionado e as ferramentas da OpenAI pelas taxas padrão. Para um ambiente hospedado pela OpenAI, a taxa de contêiner se aplica. Para um caminho auto-hospedado, os recursos de execução são custo do seu provedor.
O faturamento do Novita Sandbox é por segundo para CPU e RAM enquanto um sandbox está em execução. Pausar interrompe os encargos de CPU e RAM. Os dados pausados são retidos como armazenamento persistente; cada conta inclui 60 GB de armazenamento persistente gratuito, com armazenamento adicional faturado por hora. Cada sandbox em execução inclui 20 GB de armazenamento efêmero. Os créditos e preços oficiais do Sandbox mudam, portanto, confirme os valores atuais na página de preços do Novita Sandbox.
Os limites de cota do Novita também são importantes para cargas de trabalho paralelas. No momento da redação deste artigo, contas gratuitas têm como padrão 5 sandboxes simultâneos e contas pagas, 100; o máximo de vCPU e memória por sandbox difere por nível. Os limites empresariais podem ser ajustados. Consulte o guia de limites de cota e Sandbox.get_quota() em vez de confiar em exemplos em páginas de marketing.
Onde esta arquitetura se encaixa
Um runtime Novita auto-hospedado é uma boa opção quando:
- O agente deve executar código, modificar arquivos, instalar dependências, executar testes, navegar na web ou interagir com uma área de trabalho.
- A aplicação precisa de sessões com estado através de atraso humano, repetições ou revisões de várias etapas.
- Você deseja execução isolada separada do servidor do seu produto.
- Sua carga de trabalho se beneficia de templates, snapshots, pausa/retomada ou ambientes reproduzíveis.
Não é a opção certa quando:
- A tarefa precisa apenas de chamadas de função remotas e nenhum sistema de arquivos ou shell.
- Você precisa de um ambiente gerenciado pela OpenAI e não quer gerenciar o ciclo de vida do ambiente.
- Você exige um provedor listado nos guias atuais de provedores de sandbox diretos da OpenAI.
- Seu modelo de conformidade exige controles de isolamento gerenciados pelo provedor que o Novita não documentou para sua implantação.
A avaliação mais segura é uma pequena prova de conceito com seu repositório real, comandos, política de rede, tratamento de segredos e caminhos de falha. Em seguida, meça a inicialização, pausa/retomada, conclusão da tarefa e o custo total de uma execução representativa.
FAQ
O Novita Sandbox se integra nativamente à API OpenAI Agents?
Não, de acordo com os guias atuais de provedores de ambiente da OpenAI. A arquitetura precisa é usar o caminho de ambiente auto-hospedado da API Agents, iniciar o Novita Sandbox como seu runtime gerenciado pela aplicação e executar o executor documentado dentro dele. Verifique os guias atuais antes do lançamento, pois as integrações de provedores podem mudar.
Ainda preciso do Novita se a OpenAI oferece um sandbox hospedado?
Depende dos seus requisitos. O sandbox hospedado da OpenAI é o caminho de baixa operação. O Novita Sandbox é útil quando você deseja uma escolha de runtime separada para imagens personalizadas, templates, snapshots, fluxos de trabalho de navegador ou uso de computador, pausa/retomada com estado ou controle no nível do provedor sobre recursos.
O agente pode manter processos e arquivos durante uma pausa?
Sim. A documentação de pausa/retomada do Novita diz que o sistema de arquivos e o estado na memória, incluindo processos em execução e variáveis, são preservados. As conexões de rede são interrompidas até que o sandbox seja retomado.
Isso é o mesmo que o SDK OpenAI Agents?
Não. O SDK Agents é executado em sua aplicação e oferece mais controle sobre o loop do agente. A API Agents usa o harness Codex gerenciado da OpenAI. O Novita Sandbox pode hospedar a execução para qualquer um dos padrões, mas o comportamento da sessão e da orquestração difere.
Por onde devo começar?
Experimente o guia de início rápido da API OpenAI Agents para entender as sessões e eventos do harness. Em seguida, crie um Novita Sandbox e decida se seu runtime, ciclo de vida, segurança e modelo de custos atendem às suas necessidades de produção.
