DigitalOcean

Veja os exemplos de gerenciamento pelo aplicativo e por webhook no OpenAI Cookbook.

Como funciona

O Managed Agents Runtime Services (M.A.R.S.) da DigitalOcean inicia uma microVM Firecracker usando a imagem codex-agentapi. A imagem inclui o Codex e inicia o executor, que estabelece uma conexão de saída com a API de Agentes.

Escolha o provisionamento gerenciado por webhook para iniciar ou retomar sandboxes a partir de eventos da OpenAI, ou o provisionamento gerenciado pelo aplicativo para controlá-los pelo seu aplicativo. Para um início rápido interativo, use o fluxo opcional da CLI da DigitalOcean. Consulte Ciclo de vida do sandbox para entender o comportamento de conexão e recuperação.

Antes de começar

Você precisa de uma conta da DigitalOcean habilitada para sandboxes com acesso a codex-agentapi e de um projeto da OpenAI com acesso à API de Agentes.

Para controladores de webhook ou aplicativos Python, defina DIGITALOCEAN_TOKEN e instale o SDK PyDo beta com suporte assíncrono (pydo[aio]). Use o SDK da OpenAI para requisições à API de Agentes. A instalação da CLI só é necessária para o fluxo que usa a CLI.

Gerenciado por webhook

1. Crie um agente armazenado e salve seu ID como OPENAI_AGENT_ID. Implante um controlador de webhook HTTPS na DigitalOcean App Platform com esse ID, OPENAI_API_KEY para consultar sessões, DIGITALOCEAN_TOKEN e OPENAI_EXECUTOR_API_KEY.
2. Registre o endpoint /webhook do controlador no seu projeto da OpenAI. Habilite agent.session.action_required e agent.session.failed, depois armazene o segredo de assinatura como OPENAI_WEBHOOK_SECRET e implante o controlador novamente.
3. Siga as etapas da sessão com o mesmo OPENAI_AGENT_ID e com /workspace como diretório de trabalho. Abra o fluxo de eventos e envie a entrada. Quando a OpenAI solicita uma environment_connection, o controlador verifica a assinatura, recupera a sessão atual e verifica o ID do agente e as ações necessárias da sessão. Ele busca mars-{session_id} na DigitalOcean e retoma um sandbox pausado ou cria um se nenhum estiver ativo.
4. Ao receber agent.session.failed, recupere a sessão novamente e exclua seu sandbox somente se o status atual da sessão ainda for failed.

A imagem conecta o executor ao ambiente da sessão. Seu aplicativo envia a entrada e transmite os resultados pela API de Agentes; o controlador cuida do provisionamento e da reconexão. Execute o provisionamento de cada sessão de forma sequencial para lidar com entregas duplicadas e simultâneas. Consulte as orientações sobre o ciclo de vida gerenciado por webhook para conhecer os requisitos do controlador.

Experimente com a CLI da DigitalOcean

A CLI cria os dois recursos e permite interagir com o agente pelo terminal. Ela provisiona o sandbox diretamente, sem um controlador de webhook.

Instale a versão beta do doctl que inclui harness-runtime e, em seguida, autentique-se:

doctl auth init

Salve este manifesto como agents.yaml:

12345678910111213141516name: openai-codex-session
agent: codex-agentapi
config:
  agent:
    model: gpt-5.6-sol
    instructions: Work from the files in /workspace.
  environment:
    type: self_hosted
    workspace_directory: /workspace
egress:
  - api.openai.com
  - codex-cloud-environments.chatgpt.com
env:
  CODEX_ENVIRONMENT_ID: ${ENV_ID}
secrets:
  CODEX_API_KEY: ${OPENAI_EXECUTOR_API_KEY}

O bloco config é a requisição de criação de sessão da OpenAI. A CLI autentica essa requisição com OPENAI_API_KEY, preenche ${ENV_ID} a partir da resposta e passa apenas a chave de ambiente para o sandbox. Mantenha os manifestos com os valores resolvidos fora dos logs e do controle de versão. Adicione a egress todos os destinos de que suas ferramentas precisam.

Crie a sessão e o sandbox:

doctl harness-runtime create --spec agents.yaml

Por padrão, o comando aguarda até 300 segundos para que os recursos estejam prontos. Salve o ID da sessão da OpenAI e o ID da sessão da DigitalOcean exibidos nos detalhes da sessão e conecte-se:

doctl harness-runtime launch openai-codex-session

Peça ao agente para gravar hello em /workspace/hello.txt e ler o conteúdo de volta. Pressione Ctrl+D para se desconectar sem excluir a sessão e execute o mesmo comando launch para se reconectar. Siga as instruções de Limpeza ao terminar.

Gerenciado pelo aplicativo

Use este fluxo quando seu aplicativo for responsável pela criação de sessões e pelo provisionamento de sandboxes. Primeiro, crie a sessão da OpenAI:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16import OpenAI from "openai";
const client = new OpenAI();

const session = await client.beta.agents.sessions.create({
  agent: {
    model: "gpt-6-astra",
    instructions:
      "You are a helpful coding assistant. Write clean code and verify that it works.",
  },
  environment: {
    type: "self_hosted",
    workspace_directory: "/workspace",
  },
});

console.log(session);

1
2
3
4
5
6
7
8
9
10
11
12from openai import OpenAI

client = OpenAI()

session = client.beta.agents.sessions.create(
    agent={
        "model": "gpt-6-astra",
        "instructions": "You are a helpful coding assistant. Write clean code and verify that it works.",
    },
    environment={"type": "self_hosted", "workspace_directory": "/workspace"},
)
print(session.to_json())

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
)

ctx := context.Background()
client := openai.NewClient()
result, err := client.Beta.Agents.Sessions.New(ctx,
	openai.BetaAgentSessionNewParams{
		Agent: openai.BetaAgentSessionNewParamsAgent{
			Model:        openai.String("gpt-6-astra"),
			Instructions: openai.String("You are a helpful coding assistant. Write clean code and verify that it works."),
		},
		Environment: openai.EnvironmentParamUnion{
			OfParamSelfHosted: &openai.EnvironmentParamSelfHosted{WorkspaceDirectory: "/workspace"},
		},
	})
if err != nil {
	panic(err)
}
fmt.Println(result)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.agents.EnvironmentParam;
import com.openai.models.beta.agents.sessions.SessionCreateParams;

OpenAIClient client = OpenAIOkHttpClient.fromEnv();
var result =
    client
        .beta()
        .agents()
        .sessions()
        .create(
            SessionCreateParams.builder()
                .agent(
                    SessionCreateParams.Agent.builder()
                        .model("gpt-6-astra")
                        .instructions(
                            "You are a helpful coding assistant. Write clean code and verify"
                                + " that it works.")
                        .build())
                .environment(
                    EnvironmentParam.SelfHosted.builder()
                        .workspaceDirectory("/workspace")
                        .build())
                .build());
System.out.println(result);

1
2
3
4
5
6
7
8
9
10
11
12
13
14require "openai"

client = OpenAI::Client.new
result = client.beta.agents.sessions.create(
  agent: {
    model: "gpt-6-astra",
    instructions: "You are a helpful coding assistant. Write clean code and verify that it works."
  },
  environment: {
    type: "self_hosted",
    workspace_directory: "/workspace"
  }
)
puts result

Salve session.id e o ID do ambiente conforme descrito em Conectar um sandbox. Salve este manifesto exclusivo do sandbox como sandbox.yaml; a configuração do agente já foi enviada à OpenAI:

12345678agent: codex-agentapi
egress:
  - api.openai.com
  - codex-cloud-environments.chatgpt.com
env:
  CODEX_ENVIRONMENT_ID: ${ENV_ID}
secrets:
  CODEX_API_KEY: ${OPENAI_EXECUTOR_API_KEY}

1. Crie um pydo.aio.Client usando DIGITALOCEAN_TOKEN e chame client.agents.create_session. Defina params.openai_session_id como o ID da sessão da OpenAI, body.manifest como o conteúdo de sandbox.yaml e body.variables como um mapeamento de ENV_ID e OPENAI_EXECUTOR_API_KEY para seus respectivos valores. Salve o session_id retornado pela DigitalOcean.
2. Abra o fluxo de eventos e envie a entrada, pedindo ao agente para gravar e ler /workspace/hello.txt. A entrada aguarda a conexão do executor. Confirme o evento de conexão e a conclusão de um turno, e inspecione a saída do agente para identificar falhas nas ferramentas.
3. Recupere o arquivo com workspace_download, usando o caminho relativo hello.txt. Mantenha os dois recursos para os próximos turnos ou faça a limpeza.

Defina limites de tempo para a configuração e a execução e trate as falhas de conexão no seu aplicativo. Não associe um manipulador de webhook de provisionamento a sessões que seu aplicativo ou CLI gerencia diretamente.

Limpeza

Salve os arquivos de que precisar, depois exclua a sessão da OpenAI e destrua o sandbox da DigitalOcean. A exclusão da sessão não emite um webhook, portanto, execute as duas operações e informe as falhas de limpeza.

Com o PyDo, chame client.agents.destroy_session com o ID da sessão da DigitalOcean. Com a CLI, passe esse ID ou o nome do sandbox:

doctl harness-runtime remove openai-codex-session

Remova o registro do webhook na OpenAI antes de excluir um controlador de webhook.

Referências

• Leia sobre a configuração de sandbox da DigitalOcean
• Leia sobre o SDK Python da DigitalOcean
• Leia sobre a versão beta da CLI da DigitalOcean