Cloudflare | OpenAI API

Este guia usa provisionamento gerenciado por webhooks com o Worker de referência da Cloudflare.

Veja os exemplos de provisionamento gerenciado pela aplicação e gerenciado por webhooks no OpenAI Cookbook.

Como funciona

Sua aplicação cria uma sessão da API de Agentes e envia dados de entrada.
A OpenAI envia webhooks de sessão para um Worker na sua conta da Cloudflare.
O Worker inicia ou reconecta um Container específico da sessão que executa codex exec-server. O executor estabelece uma conexão de saída com a OpenAI para que o agente possa executar comandos e trabalhar com arquivos.

Sua aplicação usa a API de Agentes; o Worker de referência gerencia o provisionamento do sandbox. Consulte Ciclo de vida do sandbox para entender o comportamento de conexão e recuperação.

Antes de começar

Você precisa de uma conta da Cloudflare com acesso ao Containers. Use OPENAI_API_KEY para as requisições da aplicação. Defina OPENAI_EXECUTOR_API_KEY como uma chave de ambiente e passe apenas essa chave para o Container como CODEX_API_KEY.

Crie um agente e salve seu ID como OPENAI_AGENT_ID. Use o mesmo ID de agente na sua aplicação e no Worker de referência.

Implante o Worker de referência

O Worker de referência da Cloudflare inclui o manipulador de webhooks, a imagem do Container, a configuração de implantação e o endpoint de limpeza.

Gere um segredo para o endpoint de limpeza e salve-o como EXECUTOR_CLIENT_SECRET:

openssl rand -hex 32

Implante o Worker na sua conta da Cloudflare:

Implantar na Cloudflare

Insira estes valores quando solicitado:

Variável	Valor
`OPENAI_API_KEY`	Chave usada pelo Worker para obter o estado da sessão
`OPENAI_EXECUTOR_API_KEY`	Chave de ambiente passada ao executor como `CODEX_API_KEY`
`OPENAI_AGENT_ID`	ID do agente atendido por este Worker
`OPENAI_WEBHOOK_SECRET`	`pending-webhook-registration` para a primeira implantação
`EXECUTOR_CLIENT_SECRET`	Segredo gerado para limpeza

Salve a URL do Worker implantado como WORKER_URL.

Registre o webhook

Siga as instruções de configuração de webhooks para registrar $WORKER_URL/webhook no seu projeto da OpenAI. Habilite os eventos listados pela integração de referência da Cloudflare:

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

Substitua OPENAI_WEBHOOK_SECRET pelo segredo de assinatura retornado pela OpenAI e implante a nova versão do Worker. Verifique sua configuração. Estes exemplos usam clientes HTTP padrão para chamar o Worker:

Verificar a integridade do 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"

A resposta deve conter tanto "configured": true quanto "webhook_configured": true.

Uma ação obrigatória do tipo environment_connection é o sinal para reconectar um executor offline. Um evento de inatividade, por si só, não indica que é seguro encerrar o executor; consulte comportamento do ciclo de vida.

Execute uma sessão

Siga as etapas da sessão com a OPENAI_API_KEY da sua aplicação e o mesmo OPENAI_AGENT_ID configurado no Worker. Crie uma sessão auto-hospedada e peça ao agente para gravar e ler o arquivo /workspace/hello.txt.

O Worker recebe os webhooks da sessão e conecta o executor do sandbox. Sua aplicação transmite a saída do agente em streaming pela API de Agentes.

Salve o ID da sessão como SESSION_ID. Para continuar a conversa, abra o fluxo de eventos da sessão antes de enviar novas entradas. Se o executor estiver offline, a nova entrada solicita uma conexão com o ambiente e aguarda até que o Worker reconecte o executor. A reconexão, por si só, não restaura arquivos de um Container anterior.

Execute sua aplicação em um Worker

A aplicação básica em um Worker da Cloudflare usa o SDK para TypeScript @openai/agents-api para criar sessões, enviar entradas iniciais e subsequentes e limpar recursos. Seu endpoint POST /demo executa o fluxo de trabalho.

Esta aplicação também usa provisionamento gerenciado por webhooks. Executar sua aplicação em um Worker não significa que ela precise provisionar o sandbox diretamente.

Limpeza

Quando a aplicação não precisar mais do sandbox, chame o endpoint de limpeza autenticado do Worker de referência:

Limpar o sandbox do 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"

Exclua a sessão da API de Agentes separadamente. A exclusão da sessão não emite um webhook, portanto, execute as duas operações para fazer a limpeza imediata. Recupere os arquivos de que precisa antes de liberar o Container.

Avançado: provisionamento gerenciado pela aplicação

Para controlar diretamente o provisionamento do sandbox, use o Cloudflare Sandbox SDK com o ciclo de vida gerenciado pela aplicação e as instruções de conexão do executor. Use um controlador de provisionamento por sessão.

Referências

Leia Use o Cloudflare Containers com a API de Agentes da OpenAI para saber mais sobre configuração, comportamento do ciclo de vida, snapshots e personalização de imagens.
Leia a documentação do Cloudflare Sandbox.
Leia a referência do SDK para TypeScript do Cloudflare Sandbox.

Sugestões

Primeiros passos

Conceitos fundamentais

SDKs e CLI

Recursos

APIs legadas

Escolha um modelo

Texto e código

Criação de prompts

Raciocínio

Imagens e vídeo

Tempo real e áudio

Modelos especializados

API de Agentes

SDK de Agentes

ChatKit

Pesquisa e recuperação

Conecte ferramentas e dados

Crie fluxos de trabalho com ferramentas

Computador e código

Mídia

GPT-Live

Realtime API

Desenvolva com voz

Conexões

Processamento de áudio

Entre em produção

Desempenho e qualidade

Custo e taxa de processamento

Segurança e governança

Infraestrutura e acesso

Operações

Conceitos fundamentais

Plan

Build

Test and publish

Conversion specs

Guias

Recursos

Primeiros passos

Guias

File Upload

API

Measurement

Advertiser API

Referência da API

Primeiros passos

Fundamentos

Explorar

Disponível em

Versões

Fluxos de trabalho

Capacidades

Referência

Personalização

Arquivo de configuração

Configuração de agentes

Amplie os recursos do ChatGPT e do Codex

Linux

Windows

Fluxos de trabalho de desenvolvimento

Amplie e automatize

Ambientes

Desenvolva com o Codex

Integrações de terceiros

Referência

Permissões

Codex Security

Segurança cibernética

Primeiros passos

ChatGPT Work

Identidade e autenticação

Acesso, política e modelos do workspace

Controles de plug-ins e conectores

Uso, governança e conformidade

Implantação e provedores de modelos

Comunidade

Blog

Comunidade

Blog