نظرة عامة

تتوفر واجهة Agents API بإصدار تجريبي. تتيح للمطورين إنشاء تطبيقات تضم وكيل Codex تديره OpenAI، ويمكنه تنفيذ العمل عبر خطوات متعددة ومواصلته في الجلسة نفسها.

يوفّر تطبيقك المهمة والأدوات والإعدادات. تتولى OpenAI إدارة جلسة الوكيل والتنسيق بين نموذجه وأدواته.

ما الذي يمكن للوكيل فعله؟

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

راجع نظرة عامة على واجهة Agents API للاطلاع على الإمكانات المدعومة والأمثلة.

كيف أبدأ؟

1. أنشئ مفتاح API للتطبيق في مشروعك على منصة OpenAI. امنح صلاحيتي api.agents.read وapi.agents.write للجلسات، إضافةً إلى صلاحية api.responses.write لطلبات النموذج.

2. اتبع دليل البدء السريع لإعداد وكيل وإنشاء جلسة وإرسال مهمة.

3. تابع أحداث الجلسة لمراجعة تقدم العمل والنتائج. احفظ معرّف الجلسة إذا أردت مواصلة العمل.

احتفظ بمفتاح API خارج بيئة التشغيل المعزولة للوكيل. تتطلب الطلبات الترويسة OpenAI-Beta: agents=v1. تضيف حزم SDK من OpenAI هذه الترويسة تلقائيًا.

هل يحتاج وكيلي إلى بيئة تشغيل معزولة؟

اختر البيئة المناسبة للمهمة:

• بدون بيئة: يجيب الوكيل عن الأسئلة أو يستخدم أدوات خارجية دون الحاجة إلى أوامر الصدفة المدمجة أو ملفات مساحة العمل.

• بيئة تشغيل معزولة تستضيفها OpenAI: يحتاج الوكيل إلى تشغيل نصوص برمجية أو العمل على ملفات، وتريد أن تتولى OpenAI إدارة بيئته المعزولة.

• بيئة تشغيل معزولة تستضيفها بنفسك: تحتاج إلى استخدام بنيتك التحتية أو برامجك أو شبكتك الخاصة. يتولى تطبيقك إدارة دورة حياة البيئة.

راجع بنية واجهة Agents API لمعرفة تفاصيل الإعداد.

أين يمكنني مراجعة جلسة؟

افتح السجلات في لوحة تحكم المنصة، واختر الوكلاء، ثم ابحث عن معرّف الجلسة. يمكنك فحص الجولات واستدعاءات الأدوات ونشاط الوكلاء الفرعيين.

يوضّح دليل الرصد أيضًا كيفية مراجعة استخدام الرموز المسجّل.

ماذا لو انقطع تدفق الأحداث؟

استرجع الجلسة الحالية وعناصرها المحفوظة قبل إعادة المحاولة. يساعدك ذلك على التحقق مما حدث قبل إرسال مزيد من المهام.

اكتمال الجولة لا يعني نجاح كل أداة. راجع النتيجة المُبلّغ عنها. وجود الجلسة في حالة خمول لا يكفي وحده لإثبات اكتمال المهمة بنجاح.

كيف تُحتسب رسوم الاستخدام؟

تُحتسب رسوم طلبات النموذج وفق أسعار واجهة API للنموذج المحدد. تُحتسب رسوم أدوات OpenAI وبيئات التشغيل المعزولة التي تستضيفها OpenAI وفق أسعار الأدوات والحاويات المطبّقة عليها.

راجع أسعار واجهة API للاطلاع على الأسعار الحالية.

كيف يجري التعامل مع بيانات الجلسات وملفاتها؟

تحتفظ واجهة Agents API بحالة الجلسة ليتمكن الوكيل من مواصلة العمل عبر الجولات. يمكنك حذف الجلسات والمخرجات المنشورة عندما تنتفي الحاجة إليها. احفظ أي ملفات تحتاج إليها قبل حذف الجلسة.

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