Cloudflare | OpenAI API

Ce guide utilise le Worker de référence de Cloudflare pour le provisionnement par webhook.

Consultez les exemples de provisionnement par l’application et par webhook 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 la session à un Worker de votre compte Cloudflare.
Le Worker démarre ou reconnecte un conteneur dédié à 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 manipuler des fichiers.

Votre application utilise l’API Agents. Le Worker de référence se charge du provisionnement du bac à sable. Consultez le cycle de vie du bac à sable pour savoir comment la connexion s’établit et se rétablit après une interruption.

Avant de commencer

Vous devez disposer d’un compte Cloudflare ayant accès à Cloudflare Containers. Utilisez OPENAI_API_KEY pour les requêtes de votre application. Attribuez à OPENAI_EXECUTOR_API_KEY la valeur d’une clé d’environnement et transmettez uniquement cette clé au conteneur 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 conteneur, 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 les valeurs suivantes 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 `CODEX_API_KEY`
`OPENAI_AGENT_ID`	Identifiant de l’agent dont ce Worker gère les sessions
`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 d’un webhook pour enregistrer $WORKER_URL/webhook dans votre projet OpenAI. Activez les événements indiqués dans 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 la valeur de OPENAI_WEBHOOK_SECRET par le secret de signature fourni par OpenAI, puis déployez la nouvelle version du Worker. Vérifiez sa configuration. Les exemples suivants utilisent des clients HTTP standard pour appeler le Worker :

Vérifier l’état 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 l’exécuteur hors ligne. Un événement d’inactivité ne suffit pas à déterminer si vous pouvez arrêter l’exécuteur en toute sécurité. Consultez les règles 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 le fichier /workspace/hello.txt, puis d’en lire le contenu.

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

Enregistrez l’identifiant de la 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, cet envoi déclenche une demande de connexion à l’environnement. Le traitement attend alors que le Worker reconnecte l’exécuteur. La reconnexion ne suffit pas à restaurer les fichiers d’un conteneur précédent.

Exécutez votre application dans un Worker

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

Cette application utilise elle aussi le provisionnement par webhook. Même si votre application s’exécute dans un Worker, elle n’a pas besoin de 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 en vous authentifiant :

Nettoyer 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 ne déclenche aucun webhook. Effectuez donc les deux opérations pour libérer immédiatement les ressources. Récupérez les fichiers dont vous avez besoin avant de libérer le conteneur.

Usage avancé : provisionnement par l’application

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

Références

Consultez le guide Utiliser Cloudflare Containers avec l’API Agents d’OpenAI pour en savoir plus sur la configuration, le déroulement 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

Premiers pas

Notions fondamentales

SDK et CLI

Fournisseurs de services cloud

Ressources

Anciennes API

Choisissez un modèle

Texte et code

Rédaction de prompts

Raisonnement

Images

Temps réel et audio

Modèles spécialisés

API Agents

Agents SDK

ChatKit

Recherche et récupération d’informations

Connectez des outils et des sources de données

Créez des workflows qui font appel à des outils

Ordinateur et code

Médias

GPT-Live

Realtime API

Créer des applications vocales

Connexions

Traitement audio

Mise en production

Performances et qualité

Évaluation

Coût et débit

Sécurité et gouvernance

Infrastructure et accès

Opérations

Concepts clés

Planification

Développement

Tests et publication

Spécifications de conversion

Guides

Ressources

Identité

Utilisation du forfait ChatGPT

Guides

Envoi de fichiers

API

Mesure des performances

API pour les annonceurs

Référence de l’API

Premiers pas

Premiers pas

Notions de base

Explorer

Disponible sur

Versions

Workflows

Capacités

Sites

dots

Espace ChatGPT

Référence

Personnalisation

Fichier de configuration

Configuration des agents

Étendre les fonctionnalités de ChatGPT et de Codex

Linux

Windows

Workflows de développement

Extensions et automatisation

Environnements

Codex Cloud

Développer avec Codex

Intégrations tierces

Référence

Autorisations

Codex Security

Cybersécurité

Premiers pas

Configuration des fonctionnalités

Identité et accès