Cloudflare | OpenAI API

Ce guide utilise le provisionnement géré par webhooks avec le Worker de référence de Cloudflare.

Consultez les exemples de provisionnement géré par l’application et géré par webhooks dans l’OpenAI Cookbook.

Fonctionnement

Votre application crée une session de l’API Agents et envoie des données d’entrée.
OpenAI envoie les webhooks de session à un Worker dans votre compte Cloudflare.
Le Worker démarre ou reconnecte un Container propre à la session qui exécute codex exec-server. L’exécuteur établit une connexion sortante vers OpenAI pour que l’agent puisse exécuter des commandes et travailler avec des fichiers.

Votre application utilise l’API Agents ; le Worker de référence gère le provisionnement du bac à sable. Consultez la page Cycle de vie du bac à sable pour connaître le fonctionnement de la connexion et de la reprise.

Avant de commencer

Vous devez disposer d’un compte Cloudflare avec accès à Containers. Utilisez OPENAI_API_KEY pour les requêtes de l’application. Affectez une clé d’environnement à OPENAI_EXECUTOR_API_KEY et transmettez uniquement cette clé au Container dans la variable CODEX_API_KEY.

Créez un agent et enregistrez son identifiant dans OPENAI_AGENT_ID. Utilisez le même identifiant d’agent dans votre application et dans le Worker de référence.

Déployez le Worker de référence

Le Worker de référence de Cloudflare comprend le gestionnaire de webhooks, l’image du Container, la configuration de déploiement et le point de terminaison de nettoyage.

Générez un secret pour le point de terminaison de nettoyage et enregistrez-le dans EXECUTOR_CLIENT_SECRET :

openssl rand -hex 32

Déployez le Worker dans votre compte Cloudflare :

Déployer sur Cloudflare

Saisissez ces valeurs lorsque vous y êtes invité :

Variable	Valeur
`OPENAI_API_KEY`	Clé utilisée par le Worker pour récupérer l’état de la session
`OPENAI_EXECUTOR_API_KEY`	Clé d’environnement transmise à l’exécuteur dans la variable `CODEX_API_KEY`
`OPENAI_AGENT_ID`	Identifiant de l’agent pris en charge par ce Worker
`OPENAI_WEBHOOK_SECRET`	`pending-webhook-registration` pour le premier déploiement
`EXECUTOR_CLIENT_SECRET`	Secret généré pour le nettoyage

Enregistrez l’URL du Worker déployé dans WORKER_URL.

Enregistrez le webhook

Suivez les instructions de configuration des webhooks pour enregistrer $WORKER_URL/webhook dans votre projet OpenAI. Activez les événements indiqués par l’intégration de référence de Cloudflare :

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

Remplacez OPENAI_WEBHOOK_SECRET par le secret de signature renvoyé par OpenAI, puis déployez la nouvelle version du Worker. Vérifiez sa configuration. Ces exemples utilisent des clients HTTP standard pour appeler le Worker :

Vérifiez l’état de santé du 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 réponse devrait contenir à la fois "configured": true et "webhook_configured": true.

Une action requise de type environment_connection indique qu’il faut reconnecter un exécuteur hors ligne. Un événement d’inactivité ne suffit pas, à lui seul, à déterminer si l’arrêt peut se faire sans risque ; consultez le fonctionnement du cycle de vie.

Exécutez une session

Suivez les étapes d’exécution d’une session avec la clé OPENAI_API_KEY de votre application et le même identifiant OPENAI_AGENT_ID que celui configuré dans le Worker. Créez une session auto-hébergée et demandez à l’agent d’écrire dans /workspace/hello.txt, puis d’en lire le contenu.

Le Worker reçoit les webhooks de session et connecte l’exécuteur du bac à sable. Votre application diffuse la sortie de l’agent en continu via l’API Agents.

Enregistrez l’identifiant de session dans SESSION_ID. Pour poursuivre la conversation, ouvrez le flux d’événements de la session avant d’envoyer de nouvelles données d’entrée. Si l’exécuteur est hors ligne, ces nouvelles données déclenchent une demande de connexion à l’environnement et leur traitement attend que le Worker reconnecte l’exécuteur. La reconnexion ne restaure pas à elle seule les fichiers d’un Container précédent.

Exécutez votre application dans un Worker

L’application Worker de base de Cloudflare utilise le SDK TypeScript @openai/agents-api pour créer des sessions, envoyer les données d’entrée initiales et suivantes, et nettoyer les ressources. Son point de terminaison POST /demo exécute le workflow.

Cette application utilise également le provisionnement géré par webhooks. Exécuter votre application dans un Worker n’implique pas qu’elle doive provisionner directement le bac à sable.

Nettoyage

Lorsque l’application n’a plus besoin du bac à sable, appelez le point de terminaison de nettoyage du Worker de référence, qui nécessite une authentification :

Nettoyez le bac à sable du 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"

Supprimez la session de l’API Agents séparément. La suppression d’une session n’émet pas de webhook : effectuez donc les deux opérations pour un nettoyage immédiat. Récupérez les fichiers dont vous avez besoin avant de libérer le Container.

Avancé : provisionnement géré par l’application

Pour contrôler directement le provisionnement du bac à sable, utilisez le SDK Cloudflare Sandbox en suivant le cycle de vie géré par l’application et les instructions de connexion de l’exécuteur. Utilisez un seul contrôleur de provisionnement par session.

Références

Consultez Utilisez Cloudflare Containers avec l’API Agents d’OpenAI pour en savoir plus sur la configuration, le fonctionnement du cycle de vie, les instantanés et la personnalisation des images.
Consultez la documentation de Cloudflare Sandbox.
Consultez la référence du SDK TypeScript de Cloudflare Sandbox.

Suggestions

Bien démarrer

Concepts fondamentaux

SDK et CLI

Ressources

Anciennes API

Choisissez un modèle

Texte et code

Conception de prompts

Raisonnement

Images et vidéo

Realtime et audio

Modèles spécialisés

API Agents

SDK Agents

ChatKit

Recherche et récupération

Connectez des outils et des données

Créez des flux de travail avec des outils

Ordinateur et code

Médias

GPT-Live

Realtime API

Développez avec la voix

Connexions

Traitement audio

Passez en production

Performances et qualité

Coût et débit

Sécurité et gouvernance

Infrastructure et accès

Opérations

Concepts fondamentaux

Plan

Build

Test and publish

Conversion specs

Guides

Ressources

Bien démarrer

Guides

File Upload

API

Measurement

Advertiser API

Référence de l’API

Bien démarrer

Fondamentaux

Explorer

Disponible sur

Versions

Flux de travail

Capacités

Référence

Personnalisation

Fichier de configuration

Configuration des agents

Étendez les capacités de ChatGPT et de Codex

Linux

Windows

Flux de travail de développement

Étendre et automatiser

Environnements

Développer avec Codex

Intégrations tierces

Référence

Autorisations

Codex Security

Cybersécurité

Bien démarrer

ChatGPT Work

Identité et authentification

Accès à l’espace de travail, stratégies et modèles

Contrôles des plugins et des connecteurs

Utilisation, gouvernance et conformité

Déploiement et fournisseurs de modèles

Communauté

Blog

Communauté

Blog