بناء وكلاء ذوي حالة باستخدام OpenAI Responses API: دليل عملي

النقاط الرئيسية

• Responses API هو العنصر الأساسي الموصى به من OpenAI لجميع المشاريع الجديدة، وقد أُوقفت Assistants API في 26 أغسطس 2026 — نافذة الترحيل مغلقة؛ يظل Chat Completions مدعومًا لكنه ليس حيث تصل أولًا قدرات الوكيل الجديدة.
• تُظهر تقييمات OpenAI الداخلية تحسنًا بنسبة 3% على SWE-bench واستخدامًا أفضل للذاكرة المؤقتة بنسبة 40–80% مقارنة بـ Chat Completions عند استخدام نماذج الاستدلال مثل GPT-6 Astra عبر Responses API — الحلقة الوكيلية ليست مجرد راحة، بل تحسّن جودة المخرجات بشكل قابل للقياس.
• خوادم MCP البعيدة هي نوع أدوات من الدرجة الأولى في Responses API — تتصل بأي خادم MCP باستخدام server_url وserver_label، ويكتشف النموذج أدواته ويستدعيها داخل نفس الطلب، دون الحاجة إلى تنسيق مخصص.
• مرصد الانحراف في GPT-6 Astra يوقف مهام API مباشرة عند رصد سلوك غير مصرح به — لا يوجد مسار للاستئناف؛ يجب أن يكون سير العمل قابلًا للاسترداد من حالة دائمة، وهذا هو القيد المعماري الأهم للاعتماد في الإنتاج.
• الوضع ذو الحالة أبطأ بحوالي 2 ضعف من Chat Completions عديم الحالة وفقًا لتقارير مطورين متعددين — راحة previous_response_id تأتي مع ضريبة زمن انتقال تهم في التدفقات الموجهة للمستخدم والحساسة للزمن.

OpenAI Responses API هو عنصر API الموصى به من الشركة لجميع التطويرات الجديدة، وأوقفت Assistants API رسميًا في 26 أغسطس 2026. يظل Chat Completions مدعومًا، لكن Responses API هو حيث تصل أولًا القدرات الوكيلية الجديدة — الأدوات المدمجة، المحادثات ذات الحالة، MCP البعيد، وضع الخلفية، التوجيه في منتصف الدورة. لفريق يبني وكلاء إنتاج على GPT-6 Astra، لم يعد السؤال ما إذا كان يجب الترحيل بل كيفية تصميم البنية حول نموذج حالة API، وخصائص زمن الانتقال، والقيود الحاكمة التي يفرضها مرصد Astra وقت التشغيل. يوضّح هذا الدليل القدرات الخمس المهمة، والقرارات الثلاثة التي تحدد الاعتماد، والنمط المعماري الذي يبقي وكيلك قابلًا للنقل بين المزودين.

ما الذي تغير في Responses API

Chat Completions API عديم الحالة: ترسل سجل المحادثة الكامل مع كل طلب، وتُرجع API رسالة واحدة. Responses API يقدم ثلاثة تغييرات هيكلية تؤثر على كيفية بناء الوكلاء.

عناصر بدلًا من الرسائل. يُرجع Chat Completions مصفوفة choices، يحتوي كل منها على message. يُرجع Responses API مصفوفة عناصر output، حيث كل عنصر هو اتحاد مُنمَّط — message، أو function_call، أو function_call_output، أو ملخص استدلال، أو استدعاء أداة. هذا ليس تجميليًا: يعني أن استدعاءات الأدوات والاستدلال والنص هي كائنات من الدرجة الأولى في الاستجابة، وليست حقولًا ملتصقة برسالة. عند تسلسل الاستجابات باستخدام previous_response_id، تحافظ API على جميع أنواع العناصر — بما في ذلك الاستدلال المشفّر — عبر الأدوار، وهذا ما يجعل تدفقات العمل الوكيلية متعددة الأدوار تعمل دون إعادة تشغيل السياق يدويًا.

حلقة وكيلية في طلب واحد. صُمِّم Responses API كحلقة وكيلية: يمكن للنموذج استدعاء أدوات متعددة — web_search، وfile_search، وcomputer_use، وcode_interpreter، وimage_generation، وخوادم MCP البعيدة، والدوال المخصصة — ضمن استدعاء API واحد، متكررًا حتى يصل إلى شرط التوقف. مع Chat Completions، تنفذ هذه الحلقة بنفسك: تستدعي النموذج، تحلل استدعاء الأداة، تنفذه، تضيف النتيجة، تستدعي مرة أخرى. ينفذ Responses API الحلقة على جانب الخادم. تُظهر تقييمات OpenAI الداخلية تحسنًا بنسبة 3% على SWE-bench بنفس الموجه والإعداد عند استخدام نماذج الاستدلال عبر Responses API، بالإضافة إلى استخدام أفضل للذاكرة المؤقتة بنسبة 40–80% — الحلقة على جانب الخادم تستفيد من命中ات الذاكرة المؤقتة التي لا يمكن للحلقة اليدوية تكرارها.

سياق ذو حالة عبر previous_response_id. بدلًا من إرسال السجل الكامل مع كل طلب، تمرر معرف الاستجابة السابقة والإدخال الجديد للمستخدم. تُعيد API بناء السياق على جانب الخادم، بما في ذلك عناصر الاستدلال. تُخزَّن الاستجابات افتراضيًا لمدة 30 يومًا؛ أي استجابة مرفقة بـ محادثة تحافظ على عناصرها دون TTL. يمكنك تعطيل التخزين باستخدام store: false لتدفقات العمل ذات الاحتفاظ الصفري بالبيانات، لكنك ستحتاج حينها إلى إعادة تشغيل سجل العناصر الكامل يدويًا — بما في ذلك عناصر الاستدلال المشفّر — للحفاظ على سياق الاستدلال عبر الأدوار.

القدرات الخمس المهمة

قدرات Responses API ترسم خمس قرارات معمارية، لكل منها مقايضة محددة:

1. previous_response_id: تسلسل ذو حالة

أبسط نمط ذو حالة يربط الاستجابات عبر المعرّف:

from openai import OpenAI
client = OpenAI()

first = client.responses.create(
    model="gpt-6-astra",
    input="What is the capital of France?",
    store=True,
)

second = client.responses.create(
    model="gpt-6-astra",
    previous_response_id=first.id,
    input="And its population?",
    store=True,
)

الاستدعاء الثاني لا يعيد إرسال السؤال أو الإجابة الأولى. تُعيد API بناء السياق الكامل من الاستجابة المخزنة، بما في ذلك أي استدلال أجراه النموذج. هذا هو النمط للوكلاء المحادثيين ومساعدي البحث وأي تدفق عمل يعتمد فيه متابعة المستخدم على الأدوار السابقة.

المقايضة هي زمن الانتقال. تشير تقارير مطورين متعددة على منتدى مجتمع OpenAI وMicrosoft Q&A إلى أن المسار ذا الحالة أبطأ بحوالي 2 ضعف من Chat Completions عديم الحالة — 1 ثانية مقابل 0.5 ثانية في الحالات النموذجية، وبطء يصل إلى 9 أضعاف (2.9 ثانية مقابل 0.3 ثانية) تحت الحمل. لوكيل بحث في الخلفية يعمل لدقائق، هذا غير ذي صلة. لمحادثة موجهة للمستخدم يجب أن تستجيب في أقل من 500 مللي ثانية، قد تبرر ضريبة زمن الانتقال البقاء على Chat Completions مع إدارة يدوية للسياق.

2. خوادم MCP البعيدة كأداة مدمجة

يدعم Responses API خوادم MCP البعيدة كنوع أدوات من الدرجة الأولى. تسجل خادمًا عبر URL، ويكتشف النموذج أدواته ويستدعيها داخل الحلقة الوكيلية:

response = client.responses.create(
    model="gpt-6-astra",
    tools=[{
        "type": "mcp",
        "server_label": "inventory",
        "server_description": "NetSuite inventory and pricing lookups",
        "server_url": "https://your-mcp-server.example.com/mcp",
        "require_approval": "never",
    }],
    input="Check stock levels for SKU A100-23 and suggest a reorder quantity.",
)

حقل require_approval يتحكم فيما إذا كان النموذج يحتاج إلى موافقة بشرية قبل استدعاء أدوات الخادم. لعمليات نشر الإنتاج، خيارات تصفية أدوات MCP — allowed_tools لإدراج أسماء أدوات محددة في القائمة البيضاء، وسياسات موافقة مخصصة لكل أداة — هي طبقة الحوكمة التي تمنع النموذج من استدعاء عمليات مدمرة دون إذن صريح.

هذه هي القدرة الأكثر صلة بنمط تكامل IdeaBosque. وحدة MCP مخصصة تغلف واجهات NetSuite أو HubSpot أو BigCommerce يمكن تسجيلها كخادم MCP بعيد في استدعاء Responses API، ويستخدمها النموذج بنفس طريقة استخدام web_search أو code_interpreter. الطبقة الدلالية — مخططات مُنمَّطة، سجلات تدقيق، معالجة حدود المعدل — تعيش في وحدة MCP، وليست في الموجه. لا يحل Responses API مشكلة الطبقة الدلالية؛ بل يجعل وحدة MCP نقطة التكامل الطبيعية. لمعالجة أعمق لهذا النمط، راجع MCP Module Code Standard.

3. وضع الخلفية للمهام طويلة التشغيل

وضع الخلفية يفصل استدعاء النموذج عن اتصال العميل. تقبل API الطلب، وتُرجع معرف استجابة فورًا، وتنفذ عمل النموذج بشكل غير متزامن. تستطلع الحالة أو تستقبل النتائج عبر البث عند وصولها:

resp = client.responses.create(
    model="gpt-6-astra",
    input="Analyze all 200 RFQs from last week and categorize by supplier risk tier.",
    background=True,
)

while resp.status in {"queued", "in_progress"}:
    sleep(2)
    resp = client.responses.retrieve(resp.id)

print(resp.output_text)

للوكلاء ذوي الأفق الطويل — توليف الأبحاث، تحليل المستندات الدفعي، تدفقات عمل المشتريات متعددة الخطوات — وضع الخلفية هو النمط الذي يصمد أمام انقطاعات الشبكة وانتهاء مهل العميل. استجابة خلفية تستغرق ست دقائق لا تعتمد على اتصال HTTP نشط؛ إذا انقطع العميل، يستمر العمل، وتعيد الاتصال عبر استئناف البث باستخدام رقم التسلسل الأخير.

الفخ التشغيلي هو أن وضع الخلفية ليس قائمة مهام. كما تقول إحدى التحليلات: تنفذ API استدعاء النموذج، لكن تطبيقك لا يزال يملك حالة المهمة — ما تعرضه واجهة المستخدم، كيف تتجنب معالجة webhook مرتين، متى تلغي عملًا لم يعد مهمًا. للإنتاج، تحتاج إلى نظام مهام دائم حول الاستجابة الخلفية، وليس مجرد معرف الاستجابة. هذا هو نفس النمط الموصوف في Long-running Agent Patterns: وقت تشغيل الوكيل، وليس API النموذج، هو طبقة الموثوقية.

4. استدلال مشفّر لتدفقات العمل ذات الاحتفاظ الصفري بالبيانات

عند store: false، لا تحتفظ API بالاستجابة، لكنها تُرجع عناصر استدلال مشفّرة في المخرجات. تمرر هذه العناصر مرة أخرى في إدخال الطلب التالي للحفاظ على سياق الاستدلال عبر الأدوار دون تخزين أي شيء على خوادم OpenAI. هذا هو النمط للبيئات المنظمة حيث يُحظر الاحتفاظ بالبيانات — أنظمة عالية المخاطر في EU AI Act، تدفقات عمل صحية تحت HIPAA، تدفقات عمل دفاعية تحت ITAR.

المقايضة هي أنك تصبح مخزن الحالة. يجب عليك تسلسل وتخزين وإعادة تشغيل مصفوفة العناصر الكاملة — بما في ذلك كتل الاستدلال المشفّر المعتمة — في كل دور. إذا فقدت عناصر الاستدلال المشفّرة، يفقد النموذج سياق استدلاله، وتتدهور جودة المخرجات. هذا هو نفس عبء إدارة الحالة كما في Chat Completions، لكن مع نوع عنصر إضافي يجب التعامل معه.

5. مرصد إيقاف مهام Astra

يأتي GPT-6 Astra مع مراقبة الانحراف في كل طلب يستخدم أدوات. عندما يرصد المرصد سلوكًا غير مصرح به محتملًا، تتضمن استجابة النموذج إشارة توقف. في ChatGPT وCodex، يرى المستخدم مهمة متوقفة للمراجعة. في API، تتوقف المهمة مباشرة — لا يوجد مسار للاستئناف.

للوكلاء في الإنتاج المبنيين على Responses API، هذا هو القيد المعماري الأهم. مهمة تعمل لساعات عبر سلاسل previous_response_id أو وضع الخلفية يمكن إنهاؤها في منتصف الطيران بواسطة مصنف. يجب أن يكون تدفق عملك قابلًا للاسترداد من حالة دائمة — كل استدعاء أداة، كل نتيجة وسيطة، كل مخرج جزئي يجب أن يُحفظ في مخزنك الخاص قبل استدعاء API التالي. إذا أوقف المرصد المهمة في الخطوة 47 من 50، تحتاج إلى أن تكون قادرًا على الاستئناف من الخطوة 47، لا إعادة التشغيل من الصفر.

كشف كبير علماء OpenAI، Jakub Pachocki، في An Alien Mind (6 سبتمبر 2026) أن قدرة الشركة على الاعتماد على مراقبة سلسلة الأفكار "تتضاءل تدريجيًا" — النماذج أصبحت أفضل في الاستدلال حول عملية استدلالها الخاصة والتلاعب بها، والتحسين في التدريب المسبق يجعل النماذج أكثر ذكاءً حتى دون استدلال منطوق. المرصد الذي يوقف مهمتك هو أفضل طبقة تنفيذ وقت تشغيل متاحة، لكن مزوده قال إن الإشارة التي يعتمد عليها تتدهور. لمعالجة أعمق لطبقات التنفيذ التي لا تقرأ استدلال النموذج، راجع GPT-6 Astra Ships the Runtime Kill Switch.

قرارات الاعتماد الثلاثة

القرار 1: ذو حالة أم عديم الحالة؟

استخدم store: true مع previous_response_id عندما يكون تدفق عملك محادثيًا ومتعدد الأدوار ومتسامحًا مع زمن الانتقال. استخدم store: false مع إعادة تشغيل يدوية للعناصر عندما يتطلب تدفق عملك احتفاظًا صفريًا بالبيانات أو عندما تحتاج إلى تحكم كامل في إدارة السياق. فارق زمن الانتقال تقريبًا 2 ضعف — مقبول للوكلاء في الخلفية، ربما غير مقبول لمحادثة موجهة للمستخدم.

القرار 2: أدوات مدمجة أم دوال مخصصة؟

الأدوات المدمجة (web_search، وfile_search، وcode_interpreter، وcomputer_use، وimage_generation، وMCP البعيد) تعمل على جانب الخادم وتستفيد من تحسين الذاكرة المؤقتة للحلقة الوكيلية. الدوال المخصصة تتطلب أن تنفذ حلقة استدعاء الأدوات بنفسك. القاعدة العملية: استخدم الأدوات المدمجة للقدرات التي يقدمها OpenAI أفضل منك (البحث على الويب، تنفيذ الكود)، واستخدم خوادم MCP البعيدة لتكاملات نظامك الخاصة (NetSuite، HubSpot، BigCommerce). استخدم الدوال المخصصة فقط للقدرات التي لا يمكن كشفها كخادم MCP.

القرار 3: OpenAI فقط أم مرن في النماذج؟

Responses API هو عنصر OpenAI. إذا بنيت وكيلك بالكامل على previous_response_id والأدوات المدمجة، فأنت مقيد بمخزن حالة وأداة النظام البيئي لـ OpenAI. إذا كان متطلب الإنتاج الخاص بك يشمل مرونة النماذج — توجيه المهام الحساسة للتكلفة إلى نماذج الأوزان المفتوحة مثل Qwen3.8-27B، أو إلى Claude لقدرات محددة — فأنت بحاجة إلى طبقة تجريد تترجم بين نموذج عناصر Responses API وتنسيق رسائل Chat Completions الذي يستخدمه المزودون الآخرون.

هذا هو القرار المعماري الذي يحدد ما إذا كانت Responses API هي وقت تشغيل الوكيل بالكامل أم خلفية واحدة من بين عدة خلفيات. البناء المرن في النماذج يبقي حلقة الوكيل في وقت تشغيلك الخاص، ويستخدم Responses API عندما تبرر قدراتها زمن الانتقال والربط، ويرجع إلى Chat Completions أو استدلال الأوزان المفتوحة عندما لا تبررها. اقتصاديات الاستدلال واضحة: 29% من حجم التوكن في الإنتاج يعمل بالفعل على نماذج الأوزان المفتوحة بأقل من 4% من الإنفاق. انضباط التوجيه هو واقع إنتاج، وليس خطة مستقبلية.

قائمة ترحيل

يقدم دليل الترحيل من OpenAI القائمة الكاملة. القرارات التي تؤثر على البنية، وليس فقط الكود:

• حدد نموذج حالتك. previous_response_id، أو إعادة تشغيل يدوية للعناصر، أو Conversations API. هذا يحدد ملف زمن الانتقال وموقف الاحتفاظ بالبيانات.
• دقق تعريفات الدوال. تُرحَّل الدوال المخصصة كما هي، لكن مخرجات استدعاء الدوال يجب أن تتضمن call_id الصحيح. إسقاط عناصر الاستدلال أو استدعاء الدوال عند نقل السياق يدويًا هو خطأ الترحيل الأكثر شيوعًا.
• انقل مخططات Structured Outputs من response_format إلى text.format — تغير اسم الحقل.
• أضف استمرارية الحالة الدائمة لأي تدفق عمل يعمل لأكثر من بضع ثوانٍ. مرصد إيقاف مهام Astra يمكن أن ينهي مهمة طويلة دون مسار استئناف؛ مخزن حالتك هو آلية الاسترداد.
• قارن زمن الانتقال واستخدام التوكن ومعدلات الخطأ قبل توجيه حركة مرور الإنتاج. تحسن 3% على SWE-bench وتحسن الذاكرة المؤقتة 40–80% هي متوسطات؛ حمل العمل الخاص بك قد يختلف.
• احتفظ باحتياطي Chat Completions إذا كانت مرونة النماذج مهمة. Responses API حصري لـ OpenAI؛ المزودون الآخرون يستخدمون Chat Completions.

قراءات ذات صلة

• GPT-6 Astra Ships the Runtime Kill Switch — حزمة التنفيذ وإفصاح القابلية للمراقبة التي تحدد كيف تصمم البنية حول قيد إيقاف المهام
• Inference Economics: Why Always-On Production Agents Are Now Affordable — بيانات التكلفة وراء قرار التوجيه المرن في النماذج، بما في ذلك نسبة 29% أوزان مفتوحة / 4% إنفاق
• Long-running Agent Patterns: Keeping Agents Alive Across Hours and Days — أنماط الحالة الدائمة والاسترداد التي يجعلها مرصد إيقاف Astra إلزامية

---

موزع متوسط الحجم يعمل على NetSuite وBigCommerce يريد إضافة وكيل يراقب طلبات RFQ الواردة، ويتحقق من المخزون وأسعار المستويات، ويصيغ ردود الأسعار. Responses API مع خادم MCP بعيد يغلف وحدة موصل NetSuite هو أسرع طريق إلى نموذج أولي عامل — استدعاء API واحد، حلقة أدوات مدمجة، دون تنسيق مخصص. لكن بنية الإنتاج تحتاج طبقة التوجيه المرنة في النماذج (نماذج الأوزان المفتوحة لـ 60% من حجم الاستدلال بتكلفة 4%)، ومخزن الحالة الدائم (مرصد Astra يمكن أن يوقف مهمة طويلة لتحليل RFQ في منتصف الطيران)، والطبقة الدلالية في وحدة MCP (مخططات مُنمَّطة، سجلات تدقيق، معالجة حدود المعدل التي لا يقدمها Responses API). هذا هو البناء الذي نحدد نطاقه: Responses API كخلفية تنفيذ واحدة، وحدات MCP كطبقة تكامل، وقت تشغيلك كطبقة موثوقية وتوجيه.

اطلب بناءًا محدد النطاق. اكتشاف لأسبوع واحد. تحصل على جرد نظام وخريطة تدفق عمل ونطاق ثابت — سواء تبني معنا أم لا.