واجهة برمجة تطبيقات Responses API مقابل Chat Completions للوكلاء: اختيار العقد (Contract) المناسب

بالنسبة لأعباء عمل الوكلاء (Agents)، تُعد Responses API الخيار الافتراضي الأفضل: فهي توفر لك حالة محادثة من جانب الخادم عبر previous_response_id، وعناصر مخرجات محددة النوع (typed) بدلاً من كتلة رسالة واحدة، وأحداث بث دلالية (semantic streaming events). تقلل هذه الميزات من عمليات حفظ السجلات التي سيتعين على طبقة التنسيق الخاصة بك إدارتها بخلاف ذلك. تظل Chat Completions خياراً صالحاً عندما ترغب في تحكم كامل في سجل الرسائل أو عند التكامل مع أدوات مبنية حول تنسيق رسائل الدردشة الخاص بـ OpenAI، ولكن بالنسبة لوكلاء استدعاء الأدوات متعددة الجولات (multi-turn tool-calling agents)، فإن Responses هي الأكثر ملاءمة بشكل مباشر.

كلا نقطتي النهاية موثقتان في صفحات مرجع النماذج الحالية لـ GPT-5.6 و GPT-5.5، وعقد الطلب/الاستجابة المشترك لـ Responses محدد في مرجع إنشاء Responses.

أبرز النقاط

• Chat Completions تُدار بواسطة المُستدعي: أنت ترسل مصفوفة messages الكاملة في كل طلب وتقوم بإعادة بناء السجل بنفسك.
• Responses مدعومة من الخادم: أنت ترسل input بالإضافة إلى instructions اختيارية، ويمكنك ربط الجولات بـ previous_response_id بدلاً من إعادة إرسال السجل.
• يختلف استدعاء الأدوات هيكلياً: تقوم Chat Completions بتضمين الاستدعاءات تحت choices[0].message.tool_calls؛ بينما تُصدرها Responses كعناصر محددة النوع في مصفوفة output مسطحة.
• تتم مطابقة نتائج الأدوات بواسطة tool_call_id (في Chat) مقابل call_id في عنصر function_call_output (في Responses).
• البث (Streaming) عبارة عن أجزاء دلتا (chunk-based deltas) في Chat Completions مقابل أحداث دلالية مسماة في Responses.
• دعم الأدوات المستضافة (البحث على الويب، مفسر الكود، البحث في الملفات، إلخ) يعتمد على النموذج في كلا واجهتي البرمجة؛ تحقق من صفحة النموذج قبل افتراض التوفر.

مقارنة على مستوى الحقول

وجه المقارنة	Chat Completions	Responses
نقطة النهاية	POST /v1/chat/completions	POST /v1/responses
المدخلات الأساسية	messages: [] (المصفوفة الكاملة في كل استدعاء)	input (نص أو مصفوفة من العناصر)
توجيهات نمط النظام	messages[0].role = "system"	حقل instructions في المستوى الأعلى
استمرار الجولات المتعددة	المُستدعي يعيد إرسال سجل messages بالكامل	previous_response_id يشير إلى الجولة السابقة من جانب الخادم
شكل المخرجات	choices[0].message (كائن رسالة واحد)	output: []، مصفوفة من العناصر محددة النوع (رسالة، function_call، إلخ)
موقع استدعاء الأداة	choices[0].message.tool_calls[]	عناصر في output مع type: "function_call"
تقديم نتيجة الأداة	رسالة جديدة مع role: "tool"، tool_call_id	عنصر مع type: "function_call_output"، call_id
البث (Streaming)	أجزاء chunk.choices[0].delta	أحداث مسماة (response.output_text.delta، response.completed، إلخ)

previous_response_id: ماذا يفعل فعلياً؟

في Chat Completions، تقع مسؤولية ذاكرة المحادثة بالكامل على عاتقك. يجب أن يتضمن كل طلب سجل الرسائل الكامل، ولا يملك الخادم أي فكرة عن الجولة السابقة. بدلاً من ذلك، تُرجع Responses API معرفاً id في كل كائن استجابة. إذا قام تطبيقك بحفظ هذا المعرف id وتمريره مرة أخرى كـ previous_response_id في الاستدعاء التالي، يقوم الخادم بإعادة بناء حالة المحادثة السابقة من جانبه. أنت تحتاج فقط إلى إرسال input الجديد للجولة الحالية بالإضافة إلى instructions جديدة (اختيارياً). هذا ينقل إدارة الحالة من طبقة تطبيقك إلى بنية OpenAI التحتية، وهو أمر مهم للوكلاء الذين يقومون بالعديد من جولات استدعاء الأدوات المتسلسلة لأنك تتجنب إعادة تسلسل وإعادة إرسال سجل متزايد في كل قفزة.

المقايضة هي أن تطبيقك لا يزال بحاجة إلى حفظ المعرف id في مكان دائم (مخزن جلسة، صف في قاعدة بيانات) بين الجولات؛ لا تمنحك واجهة البرمجة احتفاظاً غير محدود أو بحثاً عبر الاستجابات السابقة، بل تسمح لك فقط بالإشارة إلى الاستجابة السابقة مباشرة كنقطة استمرار.

أمثلة على الطلبات الحالية (gpt-5.6)

Chat Completions: أنت تمتلك السجل الكامل:

{
  "model": "gpt-5.6",
  "messages": [
    { "role": "system", "content": "You are a support agent." },
    { "role": "user", "content": "Check order #4471 status." }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_order_status",
        "parameters": { "type": "object", "properties": { "order_id": { "type": "string" } } }
      }
    }
  ]
}

Responses: الجولة الأولى مع instructions و input:

{
  "model": "gpt-5.6",
  "instructions": "You are a support agent.",
  "input": "Check order #4471 status.",
  "tools": [
    {
      "type": "function",
      "name": "get_order_status",
      "parameters": { "type": "object", "properties": { "order_id": { "type": "string" } } }
    }
  ]
}

Responses: جولة المتابعة، لا يتم إعادة إرسال السجل:

{
  "model": "gpt-5.6",
  "previous_response_id": "resp_abc123",
  "input": "What about order #4472?"
}

دورة حياة استدعاء الوظيفة (Function-Call)

Chat Completions:

1. يُرجع النموذج choices[0].message.tool_calls، كل منها يحتوي على id واسم الوظيفة/الوسائط.
2. تقوم بتنفيذ الوظيفة محلياً.
3. تقوم بإلحاق رسالة المساعد (مع tool_calls) بمصفوفة messages الخاصة بك، ثم تلحق رسالة جديدة: { "role": "tool", "tool_call_id": "<id>", "content": "<result>" }.
4. تقوم بإعادة إرسال مصفوفة messages المحدثة بالكامل للمتابعة.

Responses:

1. تحتوي مصفوفة output على عنصر بنوع type: "function_call"، يتضمن call_id، وname، وarguments.
2. تقوم بتنفيذ الوظيفة محلياً.
3. ترسل طلباً جديداً مع ضبط previous_response_id على id الاستجابة السابقة، وinput يحتوي على عنصر بنوع type: "function_call_output"، يطابق call_id، والنتيجة.
4. لقد احتفظ الخادم بالفعل بسياق استدعاء الوظيفة، لذا فأنت لا تعيد إرسال الجولات السابقة.

الاختلاف الهيكلي بين عناصر المخرجات المسطحة محددة النوع ورسالة واحدة بمصفوفة متداخلة يميل إلى تبسيط منطق التحليل في Responses، حيث يمكنك التكرار عبر output والتبديل بناءً على type بدلاً من البحث في الحقول الاختيارية للرسالة.

قائمة فحص القرار

• هل تبني وكيلاً متعدد الجولات مع استدعاءات أدوات؟ اجعل Responses خيارك الافتراضي؛ previous_response_id يزيل عبء حفظ السجلات.
• هل تحتاج إلى تحكم دقيق فيما يوجد في السجل (تنقيح، تلخيص مخصص، حقن رسائل غير قياسية)؟ تمنحك Chat Completions هذا التحكم صراحةً، حيث تقوم بتجميع messages بنفسك.
• هل تقوم بترحيل تكامل Chat Completions موجود؟ وازن بين تكلفة إعادة الهيكلة وتوفير إدارة الحالة؛ بالنسبة للاستدعاءات قصيرة الأمد أحادية الجولة، تكون الفائدة أصغر.
• هل تعتمد على أدوات مستضافة (بحث، مفسر كود، أدوات ملفات)؟ تحقق من الدعم في صفحة النموذج المحددة قبل الالتزام، حيث يختلف التوفر حسب النموذج ونقطة النهاية.
• هل تحتاج إلى بث مع دلالات أحداث دقيقة (مثل التمييز بين دلتا النص ودلتا استدعاء الأداة دون فحص شكل الدلتا)؟ الأحداث المسماة في Responses أكثر وضوحاً من أجزاء الدلتا العامة في Chat Completions.
• هل تعمل ضمن إطار عمل أو SDK موجود مبني حول رسائل الدردشة؟ تأكد من نضج دعمها لـ Responses قبل تبديل العقود في منتصف المشروع.

وكلاء متعددون ومترجم العقود

نادراً ما يبقى الوكلاء مع مزود واحد لفترة طويلة. قد يوجه وكيل البرمجة العمل إلى Claude Sonnet 5 أو Kimi K2.7 Code لأعمال التنفيذ، أو يعتمد على DeepSeek V4 Flash أو Gemini 3.5 Flash لمسودات العمل الرخيصة، وأحياناً يستدعي GLM-5.2 أو Qwen3.7 Plus للتحكم في التكلفة للنماذج مفتوحة الأوزان. لا يكشف أي من هؤلاء المزودين بالضرورة عن عقد Chat Completions أو Responses الخاص بـ OpenAI بشكل أصلي.

هنا تبرز أهمية طبقة التوجيه (routing layer). تصف وثائق TokenLab على docs.tokenlab.sh سطح واجهة برمجة تطبيقات ومفتاحاً واحداً يُستخدم للوصول إلى مزودي نماذج متعددين، مما يزيل الحاجة إلى كتابة تكامل عميل منفصل يدوياً لكل عقد مزود. تغطي مقالتنا ذات الصلة حول أسماء مستعارة للرؤوس لتوافق العقود كيفية تعيين رؤوس الطلبات بحيث يمكن للكود المكتوب مقابل شكل عقد واحد الوصول إلى نماذج لا تتحدث به أصلاً. إذا كنت تبني روبوت محادثة أو وكيلاً يحتاج إلى استدعاء أكثر من عائلة نماذج واحدة، فإن دليلنا حول بناء روبوت محادثة AI بمفتاح API واحد يشرح الإعداد بمصطلحات أكثر واقعية.

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

القيود

لا تعيد هذه المقالة صياغة مرجع واجهة برمجة التطبيقات الدقيق على مستوى الحقول الخاص بـ OpenAI لأي من العقدين، لأن هذه التفاصيل ذات إصدارات ويمكن أن تتغير. لا تعامل مثال شكل الطلب أعلاه ككود جاهز للإنتاج. كما أننا لم نغطِ العقد الأصلي لكل مزود بالتفصيل هنا؛ حيث ينشر كل من Claude و Gemini و DeepSeek و GLM مراجع واجهة برمجة التطبيقات الخاصة بهم، ولا يلتزم أي منهم بمطابقة أشكال Chat Completions أو Responses الخاصة بـ OpenAI. إذا كان وكيلك يحتاج إلى ضمانات بشأن ترتيب استدعاء الأدوات، أو تنسيقات أحداث البث، أو سلوك المعالجة المجمعة، فتحقق من تلك التفاصيل مقابل الوثائق الحالية للمزود المسمى، وليس مقابل هذه المقالة.

الأسئلة الشائعة

هل Responses API بديل لـ Chat Completions؟ تضع وثائق البدء السريع لـ OpenAI واجهة Responses API كمسار حالي للتطوير الجديد، بما في ذلك حالات استخدام الوكلاء، بينما تظل Chat Completions جزءاً من سطح واجهة برمجة التطبيقات الموثقة لديهم. ما إذا كانت Chat Completions مهملة (deprecated) أو متوقفة أو مجرد قديمة في أي وقت معين هو أمر يجب عليك تأكيده مباشرة في وثائق OpenAI الحالية، حيث يمكن أن تتغير حالة الدعم.

هل يستخدم مزودون آخرون مثل Claude أو Gemini أو DeepSeek نفس العقود؟ ليس أصلاً. يحدد كل مزود شكل الطلب والاستجابة الخاص به. إذا كنت بحاجة إلى تشغيل وكيل عبر نماذج OpenAI ومزودين مثل Claude Sonnet 5 أو DeepSeek V4 Pro، فخطط لطبقة ترجمة بدلاً من افتراض وجود عقد مشترك.

هل يؤدي تبديل العقود إلى تغيير جودة مخرجات النموذج؟ لا. العقد هو وسيلة النقل وهيكل الطلب والاستجابة، وليس النموذج نفسه. تخضع جودة المخرجات للنموذج الذي تستدعيه (على سبيل المثال GPT-5.5 مقابل Claude Sonnet 5)، وليس لما إذا كنت قد استخدمت Chat Completions أو Responses API لاستدعائه.

إذا كنت تقيم أي عقد وأي نماذج تناسب وكيلك، فابدأ ببناء اختبار صغير مقابل نقاط النهاية الموثقة لـ TokenLab وقارن تكلفة التنسيق مباشرة. ابدأ في docs.tokenlab.sh لتشغيل تلك المقارنة مقابل عبء العمل الخاص بك.