DigitalOcean

Consulte os exemplos de provisionamento gerenciado pelo aplicativo e gerenciado por webhook no OpenAI Cookbook.

Como funciona

O serviço Managed Agents Runtime Services (M.A.R.S.) da DigitalOcean inicia uma microVM Firecracker com 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 em resposta a eventos da OpenAI, ou o provisionamento gerenciado pelo aplicativo para controlá-los pelo seu aplicativo. Para começar com um exemplo interativo, siga o procedimento opcional com a CLI da DigitalOcean. Consulte Ciclo de vida do sandbox para entender como funcionam a conexão e a recuperação.

Antes de começar

Você precisa de uma conta da DigitalOcean habilitada para sandboxes e com acesso a codex-agentapi, além 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 na versão 0.41.0 ou posterior com suporte a operações assíncronas (pydo[aio]). Use o SDK da OpenAI para fazer solicitações à API de Agentes. Só é necessário instalar a CLI se você optar pelo procedimento que a utiliza.

Provisionamento gerenciado por webhook

1. Crie um agente armazenado e salve o ID dele em 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, salve o segredo de assinatura em OPENAI_WEBHOOK_SECRET e implante o controlador novamente.
3. Siga as etapas para executar uma sessão usando o mesmo OPENAI_AGENT_ID e /workspace como diretório de trabalho. Abra o fluxo de eventos e envie os dados de entrada. Quando a OpenAI solicita uma environment_connection, o controlador verifica a assinatura, recupera a sessão atual e confere o ID do agente e as ações exigidas pela sessão. Ele procura mars-{session_id} na DigitalOcean e retoma o sandbox se estiver pausado ou cria um se não houver nenhum ativo.
4. Ao receber agent.session.failed, consulte a sessão novamente e exclua o sandbox dela somente se o status atual da sessão ainda for failed.

A imagem conecta o executor ao ambiente da sessão. Seu aplicativo envia dados de entrada e recebe os resultados em fluxo contínuo pela API de Agentes. O controlador cuida do provisionamento e da reconexão. Execute as operações de provisionamento de cada sessão uma por vez para lidar com entregas de eventos duplicadas ou simultâneas. Consulte as orientações sobre o ciclo de vida de sandboxes gerenciados por webhook para conhecer os requisitos do controlador.

Experimente com a CLI da DigitalOcean

A CLI cria a sessão e o sandbox e permite interagir com o agente pelo terminal. Ela provisiona o sandbox diretamente, sem um controlador de webhook.

Instale a versão 1.170.0 ou posterior do doctl, que inclui harness-runtime. Em seguida, faça a autenticação:

doctl auth init

Salve este manifesto como environment.yaml:

12345678910111213141516name: openai-codex-session
agent: codex-agentapi
config:
  agent:
    model: gpt-6.1-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 contém a solicitação de criação da sessão na OpenAI. A CLI autentica essa solicitação com OPENAI_API_KEY, preenche ${ENV_ID} com o valor recebido na resposta e passa apenas a chave de ambiente para o sandbox. Mantenha os manifestos com os valores já preenchidos fora dos logs e do controle de versão. Adicione a egress todos os destinos que suas ferramentas precisam acessar.

Crie a sessão e o sandbox:

doctl harness-runtime create --spec environment.yaml

Por padrão, o comando aguarda até 300 segundos para que os recursos fiquem prontos. Nos detalhes da sessão, localize e salve o ID da sessão da OpenAI e o ID da sessão da DigitalOcean. Em seguida, conecte o terminal à sessão:

doctl harness-runtime launch openai-codex-session

Peça ao agente que escreva hello em /workspace/hello.txt e depois leia o conteúdo do arquivo. Pressione Ctrl+D para desconectar o terminal sem excluir a sessão. Para se reconectar, execute o mesmo comando launch. Quando terminar, siga as etapas de limpeza.

Provisionamento gerenciado pelo aplicativo

Use este procedimento quando o seu aplicativo for responsável por criar a sessão e provisionar o sandbox. Crie primeiro 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 o manifesto a seguir como sandbox.yaml. Ele configura apenas o sandbox, pois 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 uma instância de pydo.aio.Client usando DIGITALOCEAN_TOKEN e chame client.agents.create_session. Defina params.openai_session_id com o ID da sessão da OpenAI, body.manifest com o conteúdo de sandbox.yaml e body.variables com 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 os dados de entrada. Peça ao agente que escreva no arquivo /workspace/hello.txt e leia seu conteúdo. Os dados de entrada ficam em espera até que o executor se conecte. Confirme que o evento de conexão ocorreu e que um turno foi concluído. Verifique na saída do agente se houve falhas nas ferramentas.
3. Baixe 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 tempos limite 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 gerenciadas diretamente pelo aplicativo ou pela CLI.

Limpeza

Salve os arquivos de que precisar. Em seguida, exclua a sessão da OpenAI e destrua o sandbox da DigitalOcean. A exclusão da sessão não dispara um webhook. Execute as duas operações e informe qualquer falha na limpeza.

Com o PyDo, chame client.agents.destroy_session com o ID da sessão da DigitalOcean. Na 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 o controlador de webhook.

Referências

• Consulte as instruções de configuração do sandbox da DigitalOcean
• Consulte o SDK Python da DigitalOcean
• Consulte as versões da CLI da DigitalOcean