Cloudflare | OpenAI API

Esta guía usa el aprovisionamiento gestionado mediante webhooks con el Worker de referencia de Cloudflare.

Consulta los ejemplos de aprovisionamiento gestionado por la aplicación y gestionado mediante webhooks en el OpenAI Cookbook.

Cómo funciona

Tu aplicación crea una sesión de la API de agentes y envía datos de entrada.
OpenAI envía webhooks de sesión a un Worker en tu cuenta de Cloudflare.
El Worker inicia o reconecta un Container específico de la sesión que ejecuta codex exec-server. El ejecutor establece una conexión saliente con OpenAI para que el agente pueda ejecutar comandos y trabajar con archivos.

Tu aplicación usa la API de agentes; el Worker de referencia gestiona el aprovisionamiento del sandbox. Consulta Ciclo de vida del sandbox para conocer el comportamiento de conexión y recuperación.

Antes de comenzar

Necesitas una cuenta de Cloudflare con acceso a Containers. Usa OPENAI_API_KEY para las solicitudes de la aplicación. Configura OPENAI_EXECUTOR_API_KEY con una clave de entorno y pasa solo esa clave al Container como CODEX_API_KEY.

Crea un agente y guarda su ID como OPENAI_AGENT_ID. Usa el mismo ID de agente en tu aplicación y en el Worker de referencia.

Despliega el Worker de referencia

El Worker de referencia de Cloudflare incluye el controlador de webhooks, la imagen del Container, la configuración de despliegue y el punto de acceso de limpieza.

Genera un secreto para el punto de acceso de limpieza y guárdalo como EXECUTOR_CLIENT_SECRET:

openssl rand -hex 32

Despliega el Worker en tu cuenta de Cloudflare:

Desplegar en Cloudflare

Ingresa estos valores cuando se te soliciten:

Variable	Valor
`OPENAI_API_KEY`	Clave que usa el Worker para obtener el estado de la sesión
`OPENAI_EXECUTOR_API_KEY`	Clave de entorno que se pasa al ejecutor como `CODEX_API_KEY`
`OPENAI_AGENT_ID`	ID del agente atendido por este Worker
`OPENAI_WEBHOOK_SECRET`	`pending-webhook-registration` para el primer despliegue
`EXECUTOR_CLIENT_SECRET`	Secreto generado para la limpieza

Guarda la URL del Worker desplegado como WORKER_URL.

Registra el webhook

Sigue las instrucciones de configuración de webhooks para registrar $WORKER_URL/webhook en tu proyecto de OpenAI. Habilita los eventos indicados en la integración de referencia de Cloudflare:

agent.session.created
agent.session.action_required
agent.session.in_progress
agent.session.idle
agent.session.failed

Reemplaza OPENAI_WEBHOOK_SECRET por el secreto de firma que devuelve OpenAI y luego despliega la nueva versión del Worker. Verifica su configuración. Estos ejemplos usan clientes HTTP estándar para llamar al Worker:

Verifica el estado del Worker

Python

1
2
3
4
5
6
7
8// Replace the illustrative IDs and URLs below with your own resource values.

const response = await fetch(
  "https://worker.example.com".replace(/\/+$/, "") + "/health",
  { method: "GET" }
);
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
console.log(await response.text());

1
2
3
4
5
6
7# Replace the illustrative IDs and URLs below with your own resource values.
import urllib.request

url = "https://worker.example.com".rstrip("/") + "/health"
request = urllib.request.Request(url, method="GET")
with urllib.request.urlopen(request) as response:
    print(response.read().decode())

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24// Replace the illustrative IDs and URLs below with your own resource values.
import (
	"io"
	"net/http"
	"os"
	"strings"
)

endpoint := strings.TrimRight("https://worker.example.com", "/") + "/health"
request, err := http.NewRequest("GET", endpoint, nil)
if err != nil {
	panic(err)
}
response, err := http.DefaultClient.Do(request)
if err != nil {
	panic(err)
}
defer response.Body.Close()
if response.StatusCode/100 != 2 {
	panic(response.Status)
}
if _, err := io.Copy(os.Stdout, response.Body); err != nil {
	panic(err)
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15// Replace the illustrative IDs and URLs below with your own resource values.
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String endpoint = "https://worker.example.com".replaceAll("/+$", "") + "/health";
var request =
    HttpRequest.newBuilder(URI.create(endpoint))
        .method("GET", HttpRequest.BodyPublishers.noBody())
        .build();
var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
if (response.statusCode() / 100 != 2)
  throw new IllegalStateException("Request failed: " + response.statusCode());
System.out.println(response.body());

1
2
3
4
5
6
7
8
9
10# Replace the illustrative IDs and URLs below with your own resource values.
require "uri"
require "net/http"

uri = URI("https://worker.example.com".sub(%r{/+\z}, "") + "/health")
request = Net::HTTP::Get.new(uri)
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
raise "Request failed: #{response.code}" unless response.is_a?(Net::HTTPSuccess)

puts response.body

1curl --fail-with-body "$WORKER_URL/health"

La respuesta debería contener tanto "configured": true como "webhook_configured": true.

Una acción requerida de tipo environment_connection es la señal para reconectar un ejecutor desconectado. Un evento de inactividad por sí solo no indica que sea seguro apagarlo; consulta el comportamiento del ciclo de vida.

Ejecuta una sesión

Sigue los pasos de la sesión con la OPENAI_API_KEY de tu aplicación y el mismo OPENAI_AGENT_ID configurado en el Worker. Crea una sesión autoalojada y pídele al agente que escriba y lea /workspace/hello.txt.

El Worker recibe los webhooks de sesión y conecta el ejecutor del sandbox. Tu aplicación transmite la salida del agente en streaming a través de la API de agentes.

Guarda el ID de la sesión como SESSION_ID. Para continuar la conversación, abre el flujo de eventos de la sesión antes de enviar datos de entrada de seguimiento. Si el ejecutor está desconectado, los nuevos datos de entrada solicitan una conexión al entorno y esperan a que el Worker vuelva a conectar el ejecutor. La reconexión por sí sola no restaura los archivos de un Container anterior.

Ejecuta tu aplicación en un Worker

La aplicación básica de Worker de Cloudflare usa el SDK de TypeScript @openai/agents-api para crear sesiones, enviar datos de entrada iniciales y de seguimiento, y limpiar recursos. Su punto de acceso POST /demo ejecuta el flujo de trabajo.

Esta aplicación también usa aprovisionamiento gestionado mediante webhooks. Ejecutar tu aplicación en un Worker no significa que deba aprovisionar el sandbox directamente.

Limpieza

Cuando la aplicación ya no necesite el sandbox, llama al punto de acceso de limpieza del Worker de referencia, que requiere autenticación:

Limpia el sandbox del Worker

Python

1
2
3
4
5
6
7
8// Replace the illustrative IDs and URLs below with your own resource values.

const response = await fetch("https://worker.example.com/executors/sess_123", {
  method: "DELETE",
  headers: { Authorization: `Bearer ${process.env.EXECUTOR_CLIENT_SECRET}` },
});
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
console.log(await response.text());

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17# Replace the illustrative IDs and URLs below with your own resource values.
import os
from urllib.parse import quote
import urllib.request

url = (
    "https://worker.example.com".rstrip("/")
    + "/executors/"
    + quote("sess_123", safe="")
)
request = urllib.request.Request(
    url,
    method="DELETE",
    headers={"Authorization": "Bearer " + os.environ["EXECUTOR_CLIENT_SECRET"]},
)
with urllib.request.urlopen(request) as response:
    print(response.read().decode())

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
26// Replace the illustrative IDs and URLs below with your own resource values.
import (
	"io"
	"net/http"
	"net/url"
	"os"
	"strings"
)

endpoint := strings.TrimRight("https://worker.example.com", "/") + "/executors/" + url.PathEscape("sess_123")
request, err := http.NewRequest("DELETE", endpoint, nil)
if err != nil {
	panic(err)
}
request.Header.Set("Authorization", "Bearer "+os.Getenv("EXECUTOR_CLIENT_SECRET"))
response, err := http.DefaultClient.Do(request)
if err != nil {
	panic(err)
}
defer response.Body.Close()
if response.StatusCode/100 != 2 {
	panic(response.Status)
}
if _, err := io.Copy(os.Stdout, response.Body); err != nil {
	panic(err)
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21// Replace the illustrative IDs and URLs below with your own resource values.
import java.net.URI;
import java.net.URLEncoder;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;

String endpoint =
    "https://worker.example.com".replaceAll("/+$", "")
        + "/executors/"
        + URLEncoder.encode("sess_123", StandardCharsets.UTF_8).replace("+", "%20");
var request =
    HttpRequest.newBuilder(URI.create(endpoint))
        .header("Authorization", "Bearer " + System.getenv("EXECUTOR_CLIENT_SECRET"))
        .method("DELETE", HttpRequest.BodyPublishers.noBody())
        .build();
var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
if (response.statusCode() / 100 != 2)
  throw new IllegalStateException("Request failed: " + response.statusCode());
System.out.println(response.body());

1
2
3
4
5
6
7
8
9
10
11# Replace the illustrative IDs and URLs below with your own resource values.
require "uri"
require "net/http"

uri = URI("https://worker.example.com".sub(%r{/+\z}, "") + "/executors/" + URI.encode_www_form_component("sess_123").gsub("+", "%20"))
request = Net::HTTP::Delete.new(uri)
request["Authorization"] = "Bearer #{ENV.fetch("EXECUTOR_CLIENT_SECRET")}"
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
raise "Request failed: #{response.code}" unless response.is_a?(Net::HTTPSuccess)

puts response.body

1
2
3
4curl --fail-with-body \
  --request DELETE \
  --header "Authorization: Bearer $EXECUTOR_CLIENT_SECRET" \
  "$WORKER_URL/executors/$SESSION_ID"

Elimina la sesión de la API de agentes por separado. La eliminación de la sesión no emite un webhook, así que realiza ambas operaciones para una limpieza inmediata. Recupera los archivos que necesites antes de liberar el Container.

Avanzado: aprovisionamiento gestionado por la aplicación

Para controlar directamente el aprovisionamiento del sandbox, usa el SDK de Cloudflare Sandbox con el ciclo de vida gestionado por la aplicación y las instrucciones de conexión del ejecutor. Usa un controlador de aprovisionamiento por sesión.

Referencias

Lee Usar Cloudflare Containers con la API de agentes de OpenAI para obtener información sobre la configuración, el comportamiento del ciclo de vida, las instantáneas y la personalización de imágenes.
Lee la documentación de Cloudflare Sandbox.
Lee la referencia del SDK de TypeScript de Cloudflare Sandbox.

Sugerencias

Primeros pasos

Conceptos fundamentales

SDK y CLI

Recursos

API heredadas

Elige un modelo

Texto y código

Diseño de prompts

Razonamiento

Imágenes y video

Tiempo real y audio

Modelos especializados

API de agentes

SDK de agentes

ChatKit

Búsqueda y recuperación

Conecta herramientas y datos

Crea flujos de trabajo con herramientas

Computadora y código

Contenido multimedia

GPT-Live

Realtime API

Desarrollar con voz

Conexiones

Procesamiento de audio

Pasa a producción

Rendimiento y calidad

Costo y rendimiento

Seguridad y gobernanza

Infraestructura y acceso

Operaciones

Conceptos fundamentales

Plan

Build

Test and publish

Conversion specs

Guías

Recursos

Primeros pasos

Guías

File Upload

API

Measurement

Advertiser API

Referencia de la API

Primeros pasos

Fundamentos

Explorar

Disponible en

Versiones

Flujos de trabajo

Capacidades

Referencia

Personalización

Archivo de configuración

Configuración de agentes

Ampliar las capacidades de ChatGPT y Codex

Linux

Windows

Flujos de trabajo de desarrollo

Extender y automatizar

Entornos

Crear con Codex

Integraciones de terceros

Referencia

Permisos

Codex Security

Seguridad cibernética

Primeros pasos

ChatGPT Work

Identidad y autenticación

Acceso, políticas y modelos del espacio de trabajo

Controles de complementos y conectores

Uso, gobernanza y cumplimiento

Implementación y proveedores de modelos

Comunidad

Blog

Comunidad

Blog