Cloudflare | OpenAI API

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

Consulta los ejemplos de aprovisionamiento desde la aplicación y aprovisionamiento 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 los webhooks de la sesión a un Worker en tu cuenta de Cloudflare.
El Worker inicia o vuelve a conectar un contenedor dedicado a 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 y el Worker de referencia se encarga de aprovisionar el sandbox. Consulta el ciclo de vida del sandbox para ver cómo funcionan la conexión y la recuperación.

Antes de empezar

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 contenedor 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 contenedor, 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 consultar 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 cuyas sesiones gestiona 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 los pasos para configurar un webhook y registra $WORKER_URL/webhook en tu proyecto de OpenAI. Habilita los eventos que se indican 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 el valor de OPENAI_WEBHOOK_SECRET por el secreto de firma que devuelve OpenAI y despliega la nueva versión del Worker. Verifica su configuración. Estos ejemplos usan clientes HTTP estándar para enviar solicitudes al Worker:

Verificar 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 debe incluir tanto "configured": true como "webhook_configured": true.

Una acción requerida de tipo environment_connection indica que se debe volver a conectar un ejecutor que está sin conexión. Un evento de inactividad por sí solo no indica que sea seguro apagar el ejecutor. Consulta el comportamiento durante el ciclo de vida.

Ejecuta una sesión

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

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

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 más datos de entrada. Si el ejecutor está sin conexión, al enviar nuevos datos de entrada se solicita una conexión con el entorno y se espera a que el Worker vuelva a conectar el ejecutor. La reconexión por sí sola no restaura los archivos de un contenedor anterior.

Ejecuta tu aplicación en un Worker

La aplicación básica para Workers de Cloudflare usa el SDK de TypeScript @openai/agents-api para crear sesiones, enviar datos de entrada al inicio y durante la sesión, y liberar recursos. Su punto de acceso POST /demo ejecuta el flujo de trabajo.

Esta aplicación también usa el aprovisionamiento mediante webhooks. Aunque tu aplicación se ejecute en un Worker, no es necesario que aprovisione 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:

Limpiar 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. Al eliminar la sesión no se envía ningún webhook, así que realiza ambas operaciones para liberar los recursos de inmediato. Recupera los archivos que necesites antes de liberar el contenedor.

Uso avanzado: aprovisionamiento desde la aplicación

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

Referencias

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

Sugerencias

Primeros pasos

Conceptos fundamentales

SDK y CLI

Proveedores de servicios en la nube

Recursos

API heredadas

Elige un modelo

Texto y código

Redacción de prompts

Razonamiento

Imágenes

Tiempo real y audio

Modelos especializados

API de agentes

Agents SDK

ChatKit

Búsqueda y recuperación de información

Conecta herramientas y datos

Crea flujos de trabajo con herramientas

Computadora y código

Multimedia

GPT-Live

Realtime API

Desarrollar aplicaciones de voz

Conexiones

Procesamiento de audio

Pasa a producción

Rendimiento y calidad

Evaluación

Costo y rendimiento

Seguridad y gobernanza

Infraestructura y acceso

Operaciones

Conceptos básicos

Planificación

Desarrollo

Pruebas y publicación

Especificaciones de conversión

Guías

Recursos

Identidad

Uso del plan de ChatGPT

Guías

Carga de archivos

API

Medición

API para anunciantes

Referencia de la API

Primeros pasos

Primeros pasos

Fundamentos

Explorar

Disponible en

Versiones

Flujos de trabajo

Capacidades

Sites

dots

ChatGPT Espacio

Referencia

Personalización

Archivo de configuración

Configuración de agentes

Ampliar las funciones de ChatGPT y Codex

Linux

Windows

Flujos de trabajo de desarrollo

Ampliar funciones y automatizar

Entornos

Codex Cloud

Desarrollar con Codex

Integraciones de terceros

Referencia

Permisos

Codex Security

Ciberseguridad

Primeros pasos

Configuración de funciones

Identidad y acceso