Agents API’yi Cloudflare’da iki ayrı anahtarla kurma

OpenAI Agents API’yi Cloudflare’da güvenli biçimde çalıştırmak için kontrol katmanını Worker’da, kod yürütme ortamını ise oturuma bağlı Container’da tutun. En kritik kural, oturum durumunu okuyan uygulama anahtarı ile Container içindeki codex exec-server’a verilen yürütücü anahtarını farklı izinlerle sınırlandırmaktır.

Kurulum sırası şöyledir: ön koşulları doğrulayın, çalışma zamanında kullanılacak iki kısıtlı OpenAI anahtarını hazırlayın, ajanı oluşturun, Worker ile Container’ı dağıtın, imzalı webhook’u kaydedin ve self-hosted bir oturumla akışı sınayın. İş bitince OpenAI oturumunu silmenin Cloudflare yürütücüsünü doğrudan temizlemediğini hesaba katarak iki kaynağı ayrı çağrılarla kapatın.

1. Kontrol katmanı ile yürütme ortamını ayırın

Agents API; ajan, ortam, kalıcı oturum, olay ve öğelerden oluşan bir çalışma modeli sunar. OpenAI’nin Agents API genel bakışı, oturumların, orkestrasyonun, bağlam sıkıştırmanın ve kurtarmanın yönetilen katmanda kaldığını; uygulamanın ise araçları ve çalışma ortamını seçtiğini açıklıyor. Aynı oturuma yeni girdi gönderilebildiği için konuşma bağlamını baştan kurmadan işe devam edilebilir.

Cloudflare düzeninde Worker, imzalı oturum olaylarını karşılayan kontrol noktasıdır. Oturum adına bağlı Durable Object ilgili Container’ın yaşam döngüsünü yönetir; Container ise codex exec-server’ı çalıştırarak /workspace içindeki dosya ve komutlara erişir. Böylece oturum verisini sorgulayan bileşen ile modelin ürettiği kodu çalıştıran bileşen aynı güven sınırında kalmaz.

Başlangıç için Containers erişimi olan bir Cloudflare hesabı, Agents API erişimi ve curl gerekir. Elle dağıtımda Node.js 24 veya üzeri, npm, Wrangler ve çalışan bir Docker daemon’u da hazırlanmalıdır. Ajanı oluşturacak kimliğin gerekli yönetim iznine sahip olduğundan emin olun; çalışma zamanında kullanılan ve yalnızca oturum okuyan uygulama anahtarına gereksiz oluşturma ya da yönetim izinleri bırakmayın.

2. İki OpenAI anahtarına farklı izinler verin

Worker’daki uygulama anahtarı ile Container’daki kısıtlı yürütücü anahtarının ayrı yetki sınırları

Worker’daki OPENAI_API_KEY, oturum durumunu almak için api.agents.read izniyle sınırlandırılır. Container’a CODEX_API_KEY olarak aktarılan OPENAI_EXECUTOR_API_KEY ise yalnızca api.model.read ve api.agents.environments.connect izinlerini alır. Cloudflare’ın resmi uygulama rehberi, iki anahtarın aynı organizasyona, projeye ve kullanıcı ya da servis hesabı sahibine bağlı olması gerektiğini; her oturumun Durable Object destekli ayrı bir Container ile yönetildiğini belirtiyor.

Bu ayrımın güvenlik sonucu nettir: yürütücü anahtarı Container içindeki süreçlerce okunabilirken uygulama anahtarı Worker’da kalır. Tek ve geniş yetkili bir anahtarı iki bileşene vermek, Container’daki bir süreç anahtara erişirse oturum yönetimi yetkilerini de gereksiz yere açar. Uygulama anahtarını Container’a, yürütücü anahtarını tarayıcıya veya genel istemci koduna koymayın.

OPENAI_WEBHOOK_SECRET ve EXECUTOR_CLIENT_SECRET bu iki OpenAI API anahtarından farklı sırlardır. İlki gelen olayların imzasını doğrular; ikincisi /executors/{SESSION_ID} temizleme yolunu korur. Dört gizli değeri de Worker secrets üzerinden sağlayın; Dockerfile’a, kaynak koduna, depo geçmişine veya örnek çıktılara yazmayın.

3. Ajanı oluşturup yürütücüyü dağıtın

Önce yeniden kullanılabilir ajanı oluşturun ve dönen agent_ önekli kimliği OPENAI_AGENT_ID olarak saklayın. Model seçiminin üretim projesinde izin verilen modelle uyuştuğunu kontrol edin. Komut çıktısı paylaşılacaksa Authorization başlığını, anahtarları ve hassas yanıt alanlarını kaldırın.

Dağıtımdan önce güçlü ve rastgele bir EXECUTOR_CLIENT_SECRET üretin. Worker’a OPENAI_API_KEY, OPENAI_EXECUTOR_API_KEY, OPENAI_AGENT_ID, OPENAI_WEBHOOK_SECRET ve EXECUTOR_CLIENT_SECRET değerleri gerekir. Webhook henüz kaydedilmediyse ilk dağıtımda OPENAI_WEBHOOK_SECRET için pending-webhook-registration yer tutucusu kullanılabilir; OpenAI imzalama sırrını verdikten sonra bu değer değiştirilip yeni Worker sürümü dağıtılmalıdır.

Kodu inceleyerek ilerleyecek ekipler için Cloudflare yürütücü şablonu, Worker kaynaklarını, Dockerfile’ı, Wrangler yapılandırmasını ve test dizinini birlikte sunuyor. Depoyu kurduktan sonra openai/agents-api dizininden sırları Wrangler ile ekleyip dağıtımı çalıştırabilirsiniz. Çalışma zamanı araçları Container imajına eklenebilir; gizli değerler imaj katmanlarına gömülmemelidir.

4. Webhook’u kaydedin ve oturumu sınayın

İmzalı webhook’un doğrulanması ve self-hosted oturumun /workspace testini tamamlaması

Dağıtılan Worker’ın genel /webhook adresini OpenAI proje ayarlarına ekleyin. agent.session.created, agent.session.action_required, agent.session.in_progress, agent.session.idle ve agent.session.failed olaylarına abone olun. Dönen imzalama sırrını Worker’a kaydedip yeniden dağıttıktan sonra /health yanıtında configured ve webhook_configured alanlarının true olduğunu doğrulayın.

OpenAI’nin /webhook yoluna etkileşimli oturum açmadan erişebilmesi gerekir. Diğer Worker yollarını Cloudflare Access ile koruyacaksanız webhook için yol bazlı bir istisna tanımlayın. Bu istisna imza kontrolünün yerini tutmaz; Worker her gelen webhook’un imzasını doğrulamalıdır.

Test oturumunda environment.type değerini self_hosted, workspace_directory değerini /workspace olarak ayarlayın ve dönen sess_ önekli oturum kimliğini saklayın. Bir bağlantıdan olay akışını izlerken diğerinden /workspace altında zararsız bir dosya yazıp okuyan görev gönderin. Ardından aynı oturuma dosyayı yeniden okuma talimatı verin; olayların ilerlemesi, Container bağlantısı ve dosyanın yeniden okunabilmesi birlikte doğrulanmalıdır.

5. Oturumu ve Container’ı ayrı çağrılarla kapatın

OpenAI oturumu silindikten sonra Cloudflare Container’ın ayrı temizlik isteğiyle durdurulması

İş tamamlandığında Agents API üzerinden oturumu silin. Ardından Worker’ın /executors/{SESSION_ID} yoluna EXECUTOR_CLIENT_SECRET taşıyan yetkili bir DELETE isteği göndererek Cloudflare yürütücüsünü hemen durdurun. OpenAI oturumunu silmek, Container temizleme webhook’u göndermez; bu nedenle ilk silme işlemi ikinci çağrının yerine geçmez.

Boşta kalan Container, yaşam döngüsü süresi dolunca durdurulabilir. Anlık görüntü özelliği hesapta kullanılabiliyor ve etkinse /workspace daha sonraki bağlantı için korunabilir; ancak bu mekanizma kalıcı yedek değildir. Başarısız oturum olayı, oturum sorgusundan 404 dönmesi veya açık temizlik isteği Container’ı durdurup kayıtlı anlık görüntüyü temizleyebilir.

Üretimde iki temizleme sonucunu ayrı ayrı kaydedin ve başarısız çağrıları sınırlı yeniden denemeyle ele alın. Günlüklere anahtarları değil, oturum kimliğini ve temizleme durumunu yazın. Böylece OpenAI’deki oturum kaydı ile Cloudflare’daki işlem kaynağı aynı iş akışında izlenir, fakat yanlışlıkla tek bir yaşam döngüsü gibi değerlendirilmez.

Ayrıca okuyun:

Agents API’yi Cloudflare’da kurmak: İki anahtarı tek anahtar sanmayın