Cloudflare | OpenAI API

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

Consulte os exemplos de provisionamento gerenciado pelo aplicativo e gerenciado por webhooks no OpenAI Cookbook.

Como funciona

Seu aplicativo cria uma sessão da API de Agentes e envia dados de entrada.
A OpenAI envia webhooks da sessão a um Worker na sua conta da Cloudflare.
O Worker inicia ou reconecta um contêiner exclusivo da sessão que executa codex exec-server. O executor inicia uma conexão de saída com a OpenAI para que o agente possa executar comandos e trabalhar com arquivos.

Seu aplicativo usa a API de Agentes, e o Worker de referência gerencia o provisionamento do sandbox. Consulte Ciclo de vida do sandbox para entender como funcionam a conexão e a recuperação.

Antes de começar

Você precisa de uma conta da Cloudflare com acesso ao Cloudflare Containers. Use OPENAI_API_KEY nas solicitações do aplicativo. Atribua a OPENAI_EXECUTOR_API_KEY o valor de uma chave de ambiente e passe apenas essa chave para o contêiner como CODEX_API_KEY.

Crie um agente e salve o ID dele em OPENAI_AGENT_ID. Use o mesmo ID de agente no aplicativo e no Worker de referência.

Implante o Worker de referência

O Worker de referência da Cloudflare inclui o código que processa os webhooks, a imagem do contêiner, a configuração de implantação e o endpoint de limpeza.

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

openssl rand -hex 32

Implante o Worker na sua conta da Cloudflare:

Implantar na Cloudflare

Informe os valores a seguir quando solicitado:

Variável	Valor
`OPENAI_API_KEY`	Chave que o Worker usa para consultar 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` na primeira implantação
`EXECUTOR_CLIENT_SECRET`	Segredo gerado para a limpeza

Salve a URL do Worker implantado em WORKER_URL.

Registre o webhook

Siga as instruções de configuração do webhook para registrar $WORKER_URL/webhook no seu projeto da OpenAI. Habilite os eventos listados na 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 o valor de OPENAI_WEBHOOK_SECRET pelo segredo de assinatura retornado pela OpenAI e implante a nova versão do Worker. Verifique a configuração do Worker. Os exemplos a seguir usam clientes HTTP padrão para chamar o Worker:

Verificar o funcionamento 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.

Quando a sessão exige a ação environment_connection, reconecte o executor que está offline. Um evento de inatividade, por si só, não indica que é seguro desligar o executor. Consulte Comportamento do ciclo de vida.

Execute uma sessão

Siga as etapas para executar uma sessão usando a OPENAI_API_KEY do aplicativo e o mesmo OPENAI_AGENT_ID configurado no Worker. Crie uma sessão auto-hospedada e peça ao agente que escreva no arquivo /workspace/hello.txt e leia seu conteúdo.

O Worker recebe os webhooks da sessão e conecta o executor do sandbox. Seu aplicativo transmite a saída do agente em tempo real pela API de Agentes.

Salve o ID da sessão em SESSION_ID. Para continuar a conversa, abra o fluxo de eventos da sessão antes de enviar novos dados de entrada. Se o executor estiver offline, o envio desses dados 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 contêiner anterior.

Execute seu aplicativo em um Worker

O aplicativo básico da Cloudflare para Workers usa o SDK @openai/agents-api para TypeScript para criar sessões, enviar dados de entrada no início e ao longo da sessão e liberar recursos. O endpoint POST /demo do aplicativo executa esse fluxo de trabalho.

Esse aplicativo também usa provisionamento gerenciado por webhooks. Mesmo quando o aplicativo é executado em um Worker, ele não precisa provisionar o sandbox diretamente.

Limpeza

Quando o aplicativo não precisar mais do sandbox, chame o endpoint de limpeza do Worker de referência, que exige autenticação:

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 dispara um webhook, portanto execute as duas operações para liberar os recursos imediatamente. Recupere os arquivos de que precisa antes de liberar o contêiner.

Uso avançado: provisionamento gerenciado pelo aplicativo

Para controlar diretamente o provisionamento do sandbox, use o Cloudflare Sandbox SDK e siga as orientações sobre o ciclo de vida gerenciado pelo aplicativo e as instruções para conectar o executor. Use um único controlador de provisionamento por sessão.

Referências

Consulte Como usar 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.
Consulte a documentação do Cloudflare Sandbox.
Consulte a referência do SDK do Cloudflare Sandbox para TypeScript.

Sugestões

Primeiros passos

Conceitos fundamentais

SDKs e CLI

Provedores de nuvem

Recursos

APIs legadas

Escolha um modelo

Texto e código

Como escrever prompts

Raciocínio

Imagens

Tempo real e áudio

Modelos especializados

API de agentes

SDK de agentes

ChatKit

Busca e recuperação de informações

Conecte ferramentas e dados

Crie fluxos de trabalho com ferramentas

Computador e código

Mídia

GPT-Live

Realtime API

Desenvolver aplicações de voz

Conexões

Processamento de áudio

Coloque em produção

Desempenho e qualidade

Avaliação

Custo e taxa de processamento

Segurança e governança

Infraestrutura e acesso

Operações

Conceitos fundamentais

Planejar

Desenvolver

Testar e publicar

Especificações de conversão

Guias

Recursos

Identidade

Uso do plano do ChatGPT

Guias

Envio de arquivos

API

Mensuração

API para anunciantes

Referência da API

Primeiros passos

Primeiros passos

Fundamentos

Explorar

Disponível em

Versões

Fluxos de trabalho

Capacidades

Sites

dots

ChatGPT Space

Referência

Personalização

Arquivo de configuração

Configuração de agentes

Ampliar os recursos do ChatGPT e do Codex

Linux

Windows

Fluxos de trabalho de desenvolvimento

Ampliar recursos e automatizar tarefas

Ambientes

Codex Cloud

Desenvolver com o Codex

Integrações de terceiros

Referência

Permissões

Codex Security

Segurança cibernética

Primeiros passos

Configuração de recursos

Identidade e acesso