عملی رہنما

Agents API کو Cloudflare Containers میں چلائیں: webhook پہلے محفوظ کریں

|مصنف: QUASA ادارتی ٹیم|6 منٹ مطالعہ| 1
Agents API کو Cloudflare Containers میں چلائیں: webhook پہلے محفوظ کریں

Agents API کو Cloudflare Containers میں محفوظ self-hosted execution کے ساتھ چلانے کی بنیادی ترتیب یہ ہے: OpenAI session اور orchestration سنبھالے، جبکہ Cloudflare Worker صرف تصدیق شدہ webhook کے بعد متعلقہ session کا container شروع یا بحال کرے۔ signature، duplicate event اور session ownership جانچے بغیر container چلانا غیر معتبر request کو compute action میں بدل سکتا ہے۔

OpenAI کا Agents API تعارف بتاتا ہے کہ managed harness OpenAI چلاتا ہے، مگر execution environment OpenAI-hosted sandbox، developer کی اپنی infrastructure یا partner sandbox ہو سکتا ہے۔ اسی تقسیم میں Cloudflare runtime، workspace، network access، secrets اور container lifecycle کی حفاظت application team کی ذمہ داری رہتی ہے۔

1۔ deployment کی حدود اور ضروریات طے کریں

Cloudflare account میں Containers access، Agents API access، ایک OpenAI API key، agent ID، curl اور عوامی Worker URL درکار ہیں۔ manual deployment کے لیے موجودہ Cloudflare ہدایت Node.js 24 یا جدید تر ورژن، npm، Docker اور Wrangler بھی مانگتی ہے۔

Cloudflare کی Agents API ہدایت میں ہر agent session کو container-backed Durable Object سے منسلک کیا گیا ہے؛ container میں codex exec-server چلتا ہے اور کام /workspace میں ہوتا ہے۔ Worker signed events وصول کرتا ہے، session state پڑھتا ہے اور executor کو OpenAI سے outbound رابطہ دیتا ہے۔

configuration کو کم از کم ان الگ قدروں میں تقسیم کریں:

  • OPENAI_API_KEY: Worker کے لیے application key، جسے session state پڑھنے کی api.agents.read اجازت چاہیے۔
  • OPENAI_EXECUTOR_API_KEY: container میں استعمال ہونے والی restricted key، جس کے مطلوبہ scopes api.model.read اور api.agents.environments.connect ہیں۔
  • OPENAI_AGENT_ID: وہ agent جس کی sessions یہ deployment قبول کرے گی۔
  • OPENAI_WEBHOOK_SECRET: OpenAI project میں webhook رجسٹر کرنے کے بعد ملنے والا signing secret۔
  • EXECUTOR_CLIENT_SECRET: Cloudflare executor کے manual cleanup endpoint کے لیے الگ shared secret۔

application اور executor keys ایک ہی OpenAI organization، project اور user یا service-account owner سے وابستہ ہونی چاہییں۔ signing secret، executor key یا cleanup secret کو repository، Dockerfile، build argument یا browser code میں نہ رکھیں؛ انہیں Worker secrets یا runtime bindings سے فراہم کریں۔

2۔ webhook کو container action سے پہلے محفوظ کریں

OpenAI webhook کی signature اور webhook ID جانچنے کے بعد ہی container کا کام background queue میں جاتا ہے

webhook endpoint کو OpenAI کے لیے عوامی طور پر قابلِ رسائی رکھنا ضروری ہے، مگر backend action صرف کامیاب signature verification کے بعد ہونا چاہیے۔ raw request body اور اصل headers کو برقرار رکھ کر official SDK کا webhook helper استعمال کریں؛ verification ناکام ہو تو session lookup، Durable Object resolution اور container start میں سے کوئی قدم نہ چلائیں۔

OpenAI کی webhook دستاویزات فوری 2xx جواب، بھاری کام کو background worker میں منتقل کرنے، ناکام delivery کی retry اور webhook-id سے duplicate events کو deduplicate کرنے کی ہدایت دیتی ہیں۔ اس لیے webhook-id کو idempotency key بنائیں اور ایسا durable record رکھیں جو ایک ہی event کو دوبارہ container action چلانے سے روکے۔

  1. صرف POST اور متوقع payload قبول کریں۔
  2. raw body، headers اور OPENAI_WEBHOOK_SECRET سے signature verify کریں۔
  3. webhook-id پہلے قبول ہو چکا ہو تو action دہرائے بغیر 2xx واپس کریں۔
  4. صرف مطلوبہ lifecycle event types کو allowlist کریں۔
  5. Agents API سے تازہ session state لے کر agent ID، session ID اور environment ID ملائیں۔
  6. قبول شدہ event کو idempotently درج کریں، جلد 2xx دیں اور باقی کام background execution میں بھیجیں۔

Cloudflare template agent.session.created، agent.session.action_required، agent.session.in_progress، agent.session.idle اور agent.session.failed events استعمال کرتا ہے۔ event type payload سے آنے والا حکم نہیں بلکہ allowlisted lifecycle signal ہونا چاہیے؛ container کی identity ہمیشہ تصدیق شدہ server-side session state سے اخذ کریں۔

3۔ ہر session کو الگ execution identity دیں

دو Agents API sessions الگ Durable Objects، containers اور workspaces میں محفوظ طور پر چلتے ہیں

Durable Object کا lookup key تصدیق شدہ session ID سے بنائیں، user کا دیا ہوا arbitrary container name قبول نہ کریں۔ چلتا ہوا container صرف اسی وقت reuse کریں جب محفوظ server-side state میں session ID اور environment ID دونوں موجودہ connection سے مطابقت رکھتے ہوں۔

action_required event پر Worker تازہ session state حاصل کرے، configured OPENAI_AGENT_ID سے ownership کی تصدیق کرے اور اسی state سے remote connection details پڑھے۔ /workspace اسی session تک محدود رہے، جبکہ cleanup route میں آنے والے session ID کو authorization کے بعد Durable Object کی state سے ملایا جائے۔

multi-tenant SaaS میں OpenAI agent ownership اور application authorization الگ checks ہیں۔ درست Agents API session یہ ثابت نہیں کرتی کہ موجودہ end user اسے دیکھ، چلا یا حذف کر سکتا ہے؛ authenticated principal، tenant ID اور session ID کی mapping اپنی database میں نافذ کریں۔

4۔ secrets، network اور files کا دائرہ محدود رکھیں

controller key، webhook secret اور cleanup secret Worker تک محدود رہیں۔ restricted executor key container میں CODEX_API_KEY کے طور پر پہنچتی ہے، اس لیے container کے process کو اس تک رسائی حاصل ہونے کا مفروضہ رکھیں اور key کو صرف لازمی scopes دیں۔ rotation کے وقت نئی key deploy کرنے، پرانی key revoke کرنے اور زیرِ عمل sessions کے رویّے کا طریقہ پہلے طے کریں۔

Cloudflare مثال codex exec-server کے OpenAI سے رابطے کے لیے outbound Internet کھولتی ہے۔ production میں destinations محدود کریں؛ database، Git provider یا internal API کے لیے پوری طاقت والی مستقل credential دینے کے بجائے scoped token، مختصر مدت کی credential یا Worker-mediated endpoint استعمال کریں۔ Authorization headers، webhook signatures، connection details اور user files کو logs میں redact کریں۔

/workspace ephemeral container storage ہے۔ snapshots دستیاب ہوں تو بھی Cloudflare انہیں best-effort session recovery کہتا ہے، durable backup نہیں؛ مزید یہ کہ container snapshots فی الحال private beta ہیں۔ مستقل files کے لیے علیحدہ durable storage، مثلاً محدود یا read-only R2 mount، استعمال کریں اور agent کو صرف مطلوبہ path تک رسائی دیں۔

5۔ deadline، recovery اور teardown ایک ساتھ نافذ کریں

deadline پر session state دوبارہ جانچ کر غیر فعال Cloudflare container اور عارضی workspace صاف کیے جاتے ہیں

EXECUTOR_KEEP_ALIVE_SECONDS کو workload کے مطابق محدود رکھیں۔ container start، environment connection اور in-progress event deadline کو arm کر سکتے ہیں؛ deadline آنے پر Worker authoritative session state دوبارہ پڑھے، inactive container روکے اور active session کو صرف نئی محدود مہلت دے۔ اپنی application میں فی tenant concurrent containers، session کی زیادہ سے زیادہ عمر اور compute budget کی حد بھی مقرر کریں۔

failed-session webhook یا session lookup کے 404 جواب پر container اور محفوظ snapshot صاف ہونا چاہیے۔ OpenAI session حذف کرنے سے container cleanup webhook نہیں آتا، اس لیے کامیاب teardown کے دو الگ actions ہیں: OpenAI session delete کریں اور authenticated DELETE request سے متعلقہ Cloudflare executor release کریں۔ دونوں actions کو idempotent رکھیں اور جزوی ناکامی کے لیے retry queue بنائیں۔

production checklist:

  • invalid signature یا duplicate webhook کوئی container action شروع نہیں کرتا۔
  • ہر قابلِ عمل event میں agent، session اور environment identity دوبارہ ملائی جاتی ہے۔
  • application، executor، webhook اور cleanup credentials الگ اور کم سے کم اجازت والے ہیں۔
  • keep-alive، concurrency، session age اور compute budget کی واضح حدود موجود ہیں۔
  • idle expiry، failed event، 404 اور explicit delete سب teardown tests میں شامل ہیں۔
  • durable files snapshot پر منحصر نہیں اور logs میں secrets یا user content ظاہر نہیں ہوتے۔

اس architecture میں webhook محض notification endpoint نہیں بلکہ OpenAI-managed orchestration اور Cloudflare-hosted execution کے درمیان حفاظتی boundary ہے۔ signature، idempotency اور server-side ownership check مکمل ہونے کے بعد ہی per-session container چلانا عنوان میں وعدہ کیے گئے محفوظ deployment کی بنیاد ہے۔

یہ بھی پڑھیں:

شیئر کریں:

ہمارا نیوز لیٹر سبسکرائب کریں

ویب 3، AI اور کرپٹو کی تازہ خبریں براہ راست اپنے اِن باکس میں پائیں۔

0