خلاصة سريعة
إن OpenAI Agents API هي منصة مُدارة لبناء وكلاء ذكاء اصطناعي قادرين على الاستدلال، واستخدام الأدوات، وتنفيذ الشيفرة، وإتمام المهام متعددة الخطوات. صُممت للتطبيقات التي تحتاج إلى مواصلة العمل عبر جولات متعددة، وتنفيذ الأدوات، والتعافي من الانقطاعات من دون أن تُنفِّذ حلقة الوكيل كاملة بنفسها. يساعد هذا الدليل المطورين على تقييم القدرات وخيارات التكامل والتكاليف.
على خلاف واجهة LLM التقليدية، تدعم OpenAI Agents API الجلسات الدائمة، وبيئات تنفيذ مُدارة، والتنسيق متعدد الوكلاء، وبثّ الأحداث، والـ artifacts. يمكن للمطورين استخدام نقاط نهاية OpenAI Agents API الأصلية للتنفيذ المُدار، أو دمج نماذج OpenAI المدعومة عبر CometAPI لبناء تدفقات عمل وكلاء مخصصة. هذان مسارا تكامل متميزان.
النقاط الأساسية
- تدير OpenAI Agents API الجلسات الدائمة والتنفيذ متعدد الخطوات، ما يقلل من عمليات الأوركسترة التي يتحملها المطوّر.
- تشمل قدراتها الأساسية تنفيذ الشيفرة في صندوق معزول، والأدوات واتصالات MCP، والوكلاء الفرعيين، والملفات الناتجة المحفوظة.
- تتكوّن تكلفة OpenAI Agents API من رموز النموذج والأدوات المؤهلة والحوسبة المستضافة الاختيارية؛ قَيِّم التكلفة لكل مهمة مُنجزة.
- المكاسب التي يذكرها العملاء تقدّم أدلة خاصة بحِمل العمل، لا معياراً موحداً لكل تطبيق.
- التنفيذ المُدار الأصلي والوكلاء المخصصون باستخدام CometAPI خيارا تكامل منفصلان مع مسؤوليات بنية تحتية مختلفة.
ما هي OpenAI Agents API؟
OpenAI Agents API هي خدمة تنفيذ مُدارة للتطبيقات التي تُجري مهام متعددة الخطوات باستخدام نماذج الاستدلال والأدوات الخارجية. إنها تعرض هيكل تشغيل Codex كخدمة. بدلاً من إدارة استدعاءات النموذج، وتنفيذ الأدوات، وحالة الجلسة، واستعادة المهام يدوياً، يستطيع المطورون تفويض كثير من هذا التنسيق إلى بيئة التشغيل.
يُنتج برنامج الدردشة التقليدي إجابة؛ أمّا الوكيل فيمكنه تخطيط الخطوات، وتشغيل الشيفرة في بيئة مُخوَّلة، وفحص الأخطاء، والمحاولة مجدداً، وتسليم ملفات مُولَّدة. وهذا يجعل الواجهة مناسبة لتدفقات العمل التشغيلية أكثر من الدردشة فقط.
سير عمل OpenAI Agents API
يجمع سير عمل الوكيل بين أربعة أجزاء: يعرّف الوكيل النموذج والتعليمات والأدوات المتاحة؛ وتوفّر البيئة الحوسبة والوصول إلى الملفات؛ وتحفظ الجلسة السياق والعمل المحفوظ؛ وتكشف الأحداث والعناصر التقدم والنتائج. معاً، تتيح هذه المكوّنات لتطبيقك إرسال مهمة، ومتابعة تنفيذها، ومواصلة العمل في جولات لاحقة. اطّلع على Agents API overview للمفاهيم الأساسية.
السير النموذجي: أنشئ جلسة؛ قدّم هدفاً؛ دَع النموذج يستدلّ ويختار الأدوات المسموح بها؛ نفّذ تلك الأدوات؛ تفحّص النتائج الوسيطة؛ وبثّ التقدم والمخرجات النهائية. يمكن متابعة الجلسة عند الحاجة.
يوضح الرسم البياني الرسمي تبادل التطبيق للمدخلات والأحداث مع الهيكل المُدار والصندوق المعزول. مخطط البنية من OpenAI Agents API architecture documentation؛ العمل الفني الأصلي من OpenAI.
ما هي الميزات الرئيسية في OpenAI Agents API؟
تشمل قدرات الهيكل المُدار تنفيذ الشيفرة، وإدارة السياق، واتصالات الأدوات، والتوجيه، والتفويض. كما تعتمد الإتاحة على البيئة والأدوات المهيأة.
الجلسات الدائمة وإدارة السياق
تحفظ الجلسات الإعدادات وسياق المحادثة والعمل المحفوظ عبر الجولات. يمكن للمطورين تقديم تعليمات جديدة لجلسة قائمة؛ تساعد إدارة السياق على دعم المهام الطويلة مع تقليل الحاجة لكتابة منطق ضغط المحادثات المخصص.
تنفيذ الشيفرة داخل صندوق معزول
| البيئة | البنية التحتية | أفضل استخدام |
|---|---|---|
| none | لا تنفيذ محلي |
يمكن للبيئات المستضافة تنفيذ Python وNode.js وبرامج سطر الأوامر في مساحة عمل معزولة. تتيح البيئة المستضافة ذاتياً للوكيل المُدار استخدام حوسبة يتحكم بها المطوّر. يشغّل المطوّر تلك البيئة ويؤمّنها، بينما تواصل Agents API إدارة هيكل الوكيل وحالة الجلسة.
التعاون متعدد الوكلاء
يمكن لوكيل مُنسّق أن يكلّف وكلاء متخصصين بمهام مستقلة. قد يفحص وكلاء البحث مصادر منفصلة بينما يوفّق وكيل أساسي بين الأدلة. قد يحسّن التوازي الإنتاجية، لكن الاستدعاءات الإضافية للنموذج والتنسيق قد يزيدان التكلفة. تدعم الواجهة ضبط التوازي وإعدادات الوكلاء الفرعيين.
OpenAI Agents API مقابل Agents SDK مقابل Responses API مقابل AgentKit
توفّر Agents API تنفيذًا مُدارًا؛ يناسب Agents SDK التطبيقات التي تملك طبقة الأوركسترة الخاصة بها؛ يناسب Responses API الاستدلال وتدفقات الأدوات الأخف؛ ويوفّر AgentKit مكونات تطوير مُكمّلة بدلاً من كونه وقت تشغيل وكيل مُدارًا مكافئًا.
كيفية البدء مع OpenAI Agents API
الخطوة 1: ضبط الوصول إلى الواجهة
استخدم مفتاح مشروع OpenAI Platform مع صلاحيات الوكيل والاستدلال المطلوبة وفقًا لـمتطلبات البدء السريع. تستهدف أمثلة curl صدفة متوافقة مع Bash مع تثبيت curl؛ مثال PowerShell يضبط فقط متغير البيئة. احتفظ بالمفاتيح خارج نظام التحكم بالإصدارات.
مثال شيفرة Bash: نفّذ الأوامر التالية في طرفية متوافقة مع Bash.
export OPENAI_API_KEY="your-openai-api-key"
مثال شيفرة PowerShell: اضبط مفتاح الواجهة في عملية PowerShell الحالية.
$env:OPENAI_API_KEY="your-openai-api-key"
الخطوة 2: أنشئ أوّل وكيل لك
مثال شيفرة Bash: نفّذ الأوامر التالية في طرفية متوافقة مع Bash.
curl --no-buffer --fail-with-body \
https://api.openai.com/v1/agents/sessions \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "OpenAI-Beta: agents=v1" \
-H "Content-Type: application/json" \
-d '{
"agent": {
"model": "gpt-6-astra",
"instructions": "Write reliable Python code, execute it, and report observed results."
},
"environment": {"type": "openai_hosted", "container_size": "small"},
"input": "Calculate the mean and standard deviation of [12,15,19,20,24] in Python.",
"stream": true
}'
تبدأ الجلسة جولتها الأولى وتبثّ أحداث الحالة أثناء تشغيل الوكيل للأدوات وتحضير الاستجابة.
الخطوة 3: فعّل التنفيذ متعدد الوكلاء
مثال شيفرة Bash: نفّذ الأوامر التالية في طرفية متوافقة مع Bash.
curl --no-buffer --fail-with-body \
https://api.openai.com/v1/agents/sessions \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "OpenAI-Beta: agents=v1" \
-H "Content-Type: application/json" \
-d '{
"agent": {
"model": "gpt-6-astra",
"instructions": "Delegate independent analyses and reconcile the results.",
"multi_agent": {"enabled": true, "max_concurrent_subagents": 2}
},
"environment": {"type": "none"},
"input": "Compare two release changes: date filtering in search and export URL behavior.",
"stream": true
}'
الخطوة 4: واصل جلسة قائمة
مثال شيفرة Bash: نفّذ الأوامر التالية في طرفية متوافقة مع Bash.
curl --fail-with-body \
"https://api.openai.com/v1/agents/sessions/$SESSION_ID/events" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "OpenAI-Beta: agents=v1" \
-H "Content-Type: application/json" \
-d '{"events":[{"type":"agent.session.input.message","input":[{"role":"user","content":[{"type":"input_text","text":"Summarize the findings in an executive report."}]}]}]}'
احفظ معرّفات الجلسة، وطبّق ضمانات إعادة المحاولة، وميّز بين التعليمات الجديدة والرسائل المستخدمة لتوجيه العمل النشط.
الخطوة 5: افحص النتائج ونظّف الموارد
مثال شيفرة Bash: نفّذ الأوامر التالية في طرفية متوافقة مع Bash.
curl --fail-with-body \
"https://api.openai.com/v1/agents/sessions/$SESSION_ID/items?order=asc&limit=100" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "OpenAI-Beta: agents=v1"
curl --fail-with-body -X DELETE \
"https://api.openai.com/v1/agents/sessions/$SESSION_ID" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "OpenAI-Beta: agents=v1"
استرجع الملفات الناتجة قبل إزالة الموارد المُدارة. قطع الاتصال من بثّ لا يُلغي بالضرورة العمل الجاري.
معلمات ضبط الجلسة
أنشئ جلسة عبر POST إلى https://api.openai.com/v1/agents/sessions. تستخدم أمثلة الإصدار التجريبي أدناه ترويسة OpenAI-Beta: agents=v1، وفقًا لـالدليل الرسمي للبدء السريع في Agents API.
يؤثر جهد الاستدلال في زمن الاستجابة، واستهلاك الرموز، وعمق التخطيط. اختر الجهد الذي يدعمه النموذج والواجهة المحددان باستخدام التوجيه الرسمي لـ GPT-6؛ لا ينبغي افتراض أن إعدادات مستوى النموذج تنطبق بشكل متماثل على كل نقطة نهاية.
كيف تبني وكيلاً ذكياً باستخدام CometAPI؟
يمكن لـ CometAPI توفير الاستدلال على النماذج لتطبيق وكيل مخصص. يظل تطبيقك مسؤولاً عن حلقة الوكيل، وتنفيذ الأدوات، وحالة الجلسة، والاستعادة، وأي توجيه بين النماذج المدعومة. يمنحك هذا تحكمًا في الأوركسترة، لكنه يجعل تلك البنية التحتية من مسؤوليتك تشغيلًا وإدارةً.
اختر تكامل Agents API الأصلي عندما تريد من OpenAI إدارة تنفيذ الوكيل وحالة الجلسة. واختر تطبيقًا قائمًا على CometAPI عندما تريد بناء وتشغيل أوركسترتك الخاصة حول واجهات نماذج مدعومة. الوصول إلى نموذج عبر CometAPI لا يؤسس بحد ذاته دعم نقاط نهاية جلسات Agents API الأصلية؛ تحقّق من الواجهة التي تنوي استخدامها. كما تتبع التكاليف مسارات مختلفة: يُفوتر الاستخدام الأصلي عبر OpenAI، بينما يجمع التطبيق المخصص بين رسوم CometAPI وتكاليف بنيتك التحتية.
الخطوة 1: الاتصال بـ CometAPI
مثال شيفرة Bash: نفّذ الأوامر التالية في طرفية متوافقة مع Bash.
pip install --upgrade openai
export COMETAPI_KEY="your-cometapi-key"
مثال شيفرة Python: أرسل طلب استدلال نموذج واطبع الاستجابة.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["COMETAPI_KEY"],
base_url="https://api.cometapi.com/v1",
)
response = client.responses.create(
model="gpt-6-astra",
input=(
"Analyze an API latency spike after a database migration. "
"Identify possible causes and prioritize diagnostic steps."
),
)
print(response.output_text)
يمكن للمطورين الوصول إلى GPT-6 Astra API in CometAPI. ينفّذ المثال أعلاه استدلال نموذج؛ تنفيذ حلقة الأدوات الموضحة أدناه مسؤولية منفصلة للتطبيق.
الخطوة 2: إضافة طبقة تنفيذ الأدوات
يمكن لمتحكّم مخصص أن يطالب النموذج، ويفحص طلبات استدعاء الأدوات، ويخوّل الإجراءات وينفذها، ويعيد النتائج، ويكرّر حتى الإكمال أو بلوغ حد مُعرّف مسبقًا. ضَع حدودًا على الجولات واستدعاءات الأدوات ووقت التنفيذ والإنفاق؛ واطلب تأكيدًا مستقلاً للعمليات المدمرة.
ما هي أفضل تطبيقات OpenAI Agents API؟
- الهندسة البرمجية: تحليل المشكلات، وتوليد تغييرات الشيفرة، وتشغيل الاختبارات، وتحضير المراجعات، مع موافقة قبل الدمج أو النشر.
- تحليل البيانات وإعداد التقارير: معالجة مجموعات البيانات المُحمّلة، وتشغيل حسابات Python، وإنشاء الرسوم البيانية، وتحويل النتائج إلى تقارير تدعم القرارات.
- الاستجابة لحوادث تقنية المعلومات: فحص التنبيهات، وربط السجلات، واستشارة أدلة التشغيل، والتوصية بالمعالجة، مع تفويض بشري للإجراءات عالية المخاطر.
- أتمتة دعم العملاء: استرجاع السجلات ذات الصلة، وتلخيص التذاكر، وصياغة الردود، وتوجيه الحالات غير المحلولة عبر وصول CRM المسموح.
- البحث ومعالجة المستندات: مقارنة المستندات، والتحقق من الادعاءات، واستخراج الحقائق، وإعداد نتائج مع استشهادات داعمة.
قيّم سير عملك
ابدأ بمهمة تمثيلية من حِمل عملك وحدد ما يعنيه الإكمال الناجح. قارِن الوكيل بعمليتك الحالية باستخدام المدخلات نفسها ومعايير القبول ذاتها. ضمّن طلبات المتابعة وإخفاقات الأدوات ليختبر التقييم التعافي إضافة إلى المسار المثالي.
اقرأ هذه المقاييس مجتمعةً. قد يكون سير عمل يُكمل مهام أكثر غير مناسب إن كان يتطلب تصحيحًا يدويًا متكررًا أو يتجاوز حدودك الزمنية والمالية. استخدم النتائج لتقرر ما الذي ستؤتمته، وما الذي ستُبقي عليه مراجعة بشرية، وأي الإخفاقات ستعالج قبل توسيع الاستخدام.
كم تبلغ تكلفة OpenAI Agents API؟
لا توجد رسوم منصة منفصلة للهيكل المُدار. تحدد رموز النموذج واستدعاءات الأدوات المؤهلة والحوسبة المستضافة الاختيارية إجمالي تكلفة الاستخدام. تُعرض أسعار النماذج أدناه بالدولار الأمريكي لكل مليون رمز لمعالجة Standard مع مطالبات قصيرة السياق (حتى 272K رمز إدخال)، وتم التحقق منها في 21 أكتوبر 2026. يمكن أن تغيّر المطالبات الأطول، وطبقات المعالجة الأخرى، وعمليات كتابة الذاكرة المؤقتة، والمعالجة الإقليمية السعر المطبق.
للوصول إلى النماذج عبر CometAPI، يمكن للمطورين استخدام GPT-6.1 Sol وGPT-6 Luna. يوضح الجدول أعلاه أسعار OpenAI؛ تتبع فوترة CometAPI أسعارها المطبقة الخاصة.
مثال: تقدير تكلفة مهمة
يفترض هذا الإجمالي الإيضاحي بقيمة $1.05 أحجام الرموز الموضحة، وبحثين، وفترة واحدة لحاوية صغيرة لمدة 20 دقيقة، ومن دون رموز محتوى بحث قابلة للفوترة إضافية أو عمليات كتابة للذاكرة المؤقتة. تعتمد التكلفة الفعلية أيضًا على مرات المحاولة، واستخدام الوكلاء الفرعيين، وسلوك الذاكرة المؤقتة، وقواعد فوترة الصندوق المعزول المطبقة على الجلسة. تتبّع التكلفة لكل مهمة مُكتملة بنجاح عبر حِمل عمل تمثيلي.
ما هي محدوديات OpenAI Agents API؟
القيود المتعلقة بالبيانات. تدعم Agents API حاليًا تخزين البيانات داخل الولايات المتحدة فقط ولا تدعم Zero Data Retention (ZDR). لا تغيّر البيئة المستضافة ذاتياً من أهلية ZDR. قبل إرسال مواد حساسة، تحقّق مما إذا كانت شروط الاحتفاظ والموضع الجغرافي للبيانات في الخدمة تلبي متطلباتك.
التوافق بين الواجهة والنموذج. قد تتغير واجهات الإصدار التجريبي العام، وقد تختلف الميزات المدعومة حسب النموذج. اختبر النموذج المحدد ونقطة النهاية وإعدادات الاستدلال والأدوات التي يستخدمها تطبيقك. كرر فحوصات التكامل عند تغيير نموذج أو اعتماد تحديث في الواجهة.
التحكم في التنفيذ. قد تراكم المهام متعددة الخطوات رموزًا، وتستغرق أزمنة متفاوتة، وتواجه إخفاقات في الأدوات. حدّد ميزانيات وحدودًا للجولات وزمن التنفيذ، امنح فقط الأذونات اللازمة للمهمة، وراقب الأعمال طويلة الأمد بشكل غير متزامن. خطّط لكيفية التعافي من استدعاءات الأدوات المنقطعة، واطلب موافقة بشرية للإجراءات ذات العواقب المهمة.
الأسئلة الشائعة
كيف ينبغي لعملاء OpenAI Agents API إعادة محاولة رسائل المتابعة؟
أعد استخدام مفتاح الإرسال نفسه عند إعادة محاولة الرسالة المنطقية ذاتها، وفق نمط إدخال الجلسة وإعادة المحاولة. احتفظ بمعرّف الجلسة ومفتاح الإرسال معًا في حالة التطبيق. يجب أن تستخدم التعليمات الجديدة مفتاحها الخاص؛ لا ينبغي التعامل مع استجابة HTTP المفقودة تلقائيًا كتعليمات جديدة.
هل يمكن لجلسة OpenAI Agents API تغيير النماذج؟
يدعم نقطة نهاية إعدادات الجلسة تحديث النموذج وجهد الاستدلال وفئة الخدمة. تؤثر التحديثات في الجولات اللاحقة؛ تحتفظ الجولة النشطة بإعداداتها القائمة. أكّد أن التشكيلة الناتجة مدعومة من النموذج المحدد، وأنشئ جلسة جديدة عندما تحتاج إلى تغيير إعدادات لا تقبلها هذه النقطة.
كيف تقيد OpenAI Agents API وصول الشبكة في الصندوق المعزول؟
تدعم البيئات المستضافة من OpenAI وصولًا خارجيًا ممكّنًا أو معطّلاً أو مقيّدًا. يستخدم النمط المقيّد قوائم سماح صريحة للمضيفين، وقد تحتاج عمليات إعادة التوجيه أو النطاقات الفرعية إلى إدخالاتها الخاصة. اضبط سياسة شبكة الصندوق المعزول للخدمات التي تحتاجها المهمة؛ وصول الشبكة وبيانات اعتماد التطبيق عنصران تحكميان منفصلان.
الخلاصة
قيّم Agents API على مهمة تمثيلية تتطلب عدة استدعاءات أدوات وعلى الأقل جولة متابعة واحدة. قِس معدل الإكمال، وسلوك التعافي، والكمون، والتكلفة لكل مهمة ناجحة. ستُظهر هذه النتائج ما إذا كان التنفيذ المُدار يلبّي متطلبات تطبيقك.