كيفية استخدام OpenAI Agents API

يقوم OpenAI Agents API بتشغيل برنامج Codex مفتوح المصدر الخاص بـ OpenAI بالنيابة عنك. يمكنك إرسال طلب POST https://api.openai.com/v1/agents/sessions مع الهيدر OpenAI-Beta: agents=v1، تعريف وكيل ومهمة؛ يقوم OpenAI بتشغيل النموذج وحلقة الأدوات، ويحتفظ بالجلسة، ويمكنه توفير بيئة اختبار معزولة (sandbox). لا توجد رسوم على Agents API: أنت تدفع مقابل الرموز المميزة (tokens) والأدوات ووقت الحاوية المستضافة (0.03 دولار إلى 0.48 دولار لكل جلسة مدتها 20 دقيقة لأحجام البيئة المعزولة من 1 جيجابايت إلى 16 جيجابايت). دخل هذا الإصدار مرحلة البيتا العامة في 10 سبتمبر 2026، وأضافت OpenAI استخدام الكمبيوتر في DevDay في 29 سبتمبر.

زر

أدناه: جلسة REST أولى، أحداث التقدم، أدوات MCP، الوكلاء الفرعيون (subagents)، وسير عمل الموافقة على استخدام الكمبيوتر. للمقارنة مع أسطح وكلاء OpenAI الأخرى، اقرأ Agents API مقابل Responses API مقابل Agents SDK؛ لبقية الحدث، راجع ملخص DevDay 2026. كل استدعاء هو HTTP عادي، لذا يمكنك إرساله من Apidog قبل كتابة رمز التطبيق.

نظرة سريعة على OpenAI Agents API

البند	القيمة
الحالة	بيتا عامة منذ 10 سبتمبر 2026؛ أُضيف استخدام الكمبيوتر في 29 سبتمبر
إنشاء جلسة	`POST /v1/agents/sessions`
هيدر البيتا	`OpenAI-Beta: agents=v1` (تضيفها حزم OpenAI SDKs)
الأذونات الأساسية	`api.agents.read`, `api.agents.write`, `api.responses.write`
التسعير	لا توجد رسوم على Agents API؛ رموز النموذج بأسعار API، والأدوات بأسعار قياسية (بحث الويب 10 دولارات لكل 1000 استدعاء)
الحاويات المستضافة	0.03 دولار (`small`، 1 جيجابايت)، 0.12 دولار (`medium`، 4 جيجابايت)، 0.48 دولار (`large`، 16 جيجابايت) لكل جلسة مدتها 20 دقيقة
البيئات	`none`, `openai_hosted`, `self_hosted`
النموذج في أمثلة الوثائق	`gpt-6-astra`
ضوابط البيانات	إقامة البيانات في الولايات المتحدة فقط؛ لا يوجد احتفاظ بالبيانات صفر (ZDR)
الحد الأقصى لحجم الطلب	4 ميجابايت

المصادر: تقديم Agents API، ونظرة عامة على Agents API، وصفحة التسعير.

المفاهيم الأربعة

تبني الوثائق واجهة برمجة التطبيقات (API) حول أربعة أجزاء:

الوكيل (Agent): النموذج، التعليمات، الأدوات، وخوادم MCP. مرره مضمنًا، أو احفظه وأعد استخدام agent_id الخاص به.
البيئة (Environment): بيئة اختبار معزولة اختيارية أو جهاز كمبيوتر حيث يقرأ الوكيل الملفات ويشغل الأوامر.
الجلسة (Session): نسخة دائمة من الوكيل تحتفظ بالتكوين والمحادثة والعمل المحفوظ.
الأحداث والعناصر (Events and items): الأحداث تُبلّغ عن التقدم مباشرة؛ والعناصر هي الرسائل واستدعاءات الأدوات المحفوظة.

رسالة تُرسل إلى جلسة خاملة تبدأ دورًا جديدًا؛ رسالة تُرسل في منتصف الدور توجّهه. يتعامل المسرّج (harness) (وفقًا لصفحة البنية، أي نسخة Codex المستضافة التي تشغل حلقة النموذج والأدوات) أيضًا مع ضغط السياق، لذا لا تحتاج إلى تهيئته.

اختر بيئة

يحدد environment.type مكان تشغيل الأوامر:

none: لا توجد حوسبة. لا تزال خوادم MCP البعيدة وأدوات الوظائف الخاصة بك تعمل؛ بينما Bash المدمج، وapply-patch، وملفات مساحة العمل، وMCPs المنفذين لا تعمل.
openai_hosted: يدير OpenAI بيئة Linux معزولة (sandbox) تحتوي على Python وNode.js في /workspace. قم بتعيين container_size إلى small (1 جيجابايت)، medium (افتراضي، 4 جيجابايت)، أو large (16 جيجابايت)، وnetwork.access إلى enabled، disabled، أو restricted مع allowed_domains. تصبح الملفات في /workspace/outputs آثارًا عند اكتمال الدور. يمكن حذف بيئة اختبار معزولة خاملة بدون "keep-alives" بعد ساعة.
self_hosted: بنيتك التحتية الخاصة. يمكنك تشغيل codex exec-server على جهاز كمبيوتر محمول، أو حاوية، أو بيئة اختبار معزولة بعيدة، ويتصل بالخارج باستخدام مفتاح بيئة منفصل.

تدرج مشاركة الإطلاق الشركاء في البيئة المعزولة مثل Blaxel، Cloudflare، Daytona، DigitalOcean، E2B، Modal، Oracle، Runloop، وVercel؛ يضيف دليل الاستضافة الذاتية AWS Lambda MicroVMs.

جلستك الأولى عبر REST

صدر مفتاحًا بالأذونات المذكورة أعلاه باسم OPENAI_API_KEY، ثم أرسل مهمة البدء السريع بحاوية صغيرة:

curl --no-buffer https://api.openai.com/v1/agents/sessions \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": {
      "model": "gpt-6-astra",
      "instructions": "Write clean code, run it, and report the actual output."
    },
    "environment": { "type": "openai_hosted", "container_size": "small" },
    "input": "Create tree.py, a script that prints a tree of the files in the current directory. Run it and show the output.",
    "stream": true
  }'

مع stream: true، يكون الاستجابة عبارة عن تدفق أحداث الدور الأول. احفظ معرف الجلسة منه؛ تستخدم بقية دورة الحياة نفس المورد:

الإجراء	الطلب
المتابعة أو التوجيه	`POST /v1/agents/sessions/{id}/events` مع حدث `agent.session.input.message`
إلغاء الدور النشط	نفس نقطة النهاية، نوع الحدث `agent.session.input.cancel`
قراءة العمل المحفوظ	`GET /v1/agents/sessions/{id}/items?order=asc&limit=100`
التنظيف	`DELETE /v1/agents/sessions/{id}`

يتخذ JavaScript SDK نفس الشكل. هذه النسخة، المقتبسة من مشاركة الإطلاق، تضيف أداة ووكلاء فرعيين (subagents) وخزانة (vault):

import OpenAI from "openai";

const client = new OpenAI();
const session = await client.beta.agents.sessions.create({
  agent: {
    model: "gpt-6-astra",
    tools: [{ type: "web_search" }],
    multi_agent: { enabled: true, max_concurrent_subagents: 3 },
  },
  vault_ids: [process.env.VAULT_ID],
  environment: { type: "openai_hosted" },
  input: "Summarize breaking changes in the latest release notes.",
});
console.log(session.id);

تابع التقدم: تدفق أو Webhooks

التدفق (Streaming). افتح GET /v1/agents/sessions/{id}/events?stream=true مع Accept: text/event-stream قبل إرسال المدخلات، حتى لا تفوت الأحداث المبكرة. راقب ما يلي:

agent.session.turn.output_text.delta و agent.session.turn.output_text.done للنص
agent.session.turn.completed، agent.session.turn.failed، أو agent.session.turn.cancelled للنتيجة
agent.session.requires_action عندما يحتاج الوكيل إلى نتيجة وظيفة، اتصال بيئة، أو موافقة على استخدام الكمبيوتر

ثلاثة محاذير: agent.session.idle لا يعني نجاح الدور، وقد يحتوي الدور المكتمل على استدعاءات أدوات فاشلة، وإغلاق التدفق لا يوقف المهمة. التدفقات لا تعيد تشغيل الأحداث المفقودة، لذا بعد انقطاع الاتصال، افتح تدفقًا جديدًا واسترجع الجلسة وعناصرها.

Webhooks. اشترك في agent.session.created، agent.session.action_required، agent.session.in_progress، agent.session.idle، و agent.session.failed. لاحظ التسمية: التدفق يقول requires_action، بينما الويب هوك يقول action_required. تتجاهل الحمولة تفاصيل الاستدعاء، لذا يقوم المعالج الخاص بك باسترداد الجلسة وقراءة required_actions. تحقق من كل توقيع (التحقق من توقيع الويب هوك)؛ يوضح عمليات API طويلة الأمد للوكيل الذكي لماذا تتناسب الويب هوكس مع المهام التي تستغرق عدة دقائق.

أدوات MCP، البحث عن الأدوات، استدعاء الأدوات البرمجي، والوكلاء الفرعيون

MCP. أضف خادمًا إلى agent.tools:

{
  "type": "mcp",
  "server_label": "openai_docs",
  "transport": { "type": "http", "server_url": "https://developers.openai.com/mcp" },
  "required": true
}

بشكل افتراضي، يقوم OpenAI بإنشاء الاتصال (connection_origin: "service")، لذا يجب أن يكون الخادم قابلاً للوصول من OpenAI. استخدم connection_origin: "environment" لخادم شبكة خاصة، أو stdio لبدء واحد في البيئة المعزولة (sandbox). للوصول إلى بيانات الاعتماد، مرر transport.authorization لجلسة واحدة، أو قم بإرفاق بيانات اعتماد من خزانة (static_bearer أو mcp_oauth) باستخدام vault_ids.

البحث عن الأدوات. يتم اكتشاف أدوات MCP تلقائيًا عندما يدعم النموذج البحث عن الأدوات. للعديد من أدوات الوظائف، أضف {"type": "tool_search"} وضع علامة على الوظائف defer_loading: true.

استدعاء الأدوات البرمجي. مفعل بشكل افتراضي: يحصل الوكيل على أداة exec تشغل JavaScript في بيئة تشغيل V8 معزولة، بحيث يمكنه التكرار على استدعاءات الأدوات وتقليم النتائج الكبيرة قبل أن تصل إلى السياق. قم بتعطيله باستخدام {"type": "programmatic_tool_calling", "enabled": false}.

الوكلاء الفرعيون (Subagents). عيّن multi_agent: {"enabled": true, "max_concurrent_subagents": 3} (الحد الافتراضي هو 6). يتشارك الوكلاء الفرعيون نظام ملفات البيئة ويرثون أدوات MCP وبحث الويب، لكن لا يمكنهم استخدام أدوات الوظائف. يكون subagent_id الخاص بالدور null للوكيل الرئيسي.

استخدام الكمبيوتر: إضافة DevDay

يوفر استخدام الكمبيوتر للوكيل متصفحًا مستضافًا. أضف الأداة وسطح مكتب إلى بيئة مستضافة:

{
  "agent": {
    "model": "gpt-6-astra",
    "tools": [{ "type": "computer_use", "include_screenshots": true }]
  },
  "environment": {
    "type": "openai_hosted",
    "desktop": { "enabled": true },
    "network": { "access": "enabled" }
  }
}

يحتاج المتصفح إلى موافقة المستخدم قبل زيارة كل مصدر موقع ويب جديد، بما في ذلك المواقع العامة. عند agent.session.requires_action، استرجع الجلسة وابحث عن إدخالات computer_use_approval_request. نوع request.type المتداخل هو أحد نوعين:

browser_origin_access: أظهر origin و reason، ثم أرسل approve، deny، أو cancel.
browser_authentication: نموذج تسجيل دخول مع fields، options تسجيل دخول اختيارية، و credential_origin. أرسل action: "submit" مع قيم المستخدم، أو action: "cancel".

كلا الإجابتين تعودان عبر نقطة نهاية الأحداث:

curl "https://api.openai.com/v1/agents/sessions/$SESSION_ID/events" \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"events": [{
    "type": "agent.session.input.computer_use_approval_request_result",
    "request_id": "REQUEST_ID",
    "response": { "type": "browser_origin_access", "decision": "approve" }
  }]}'

يظهر عمل المتصفح كعناصر computer_use_call مع id، turn_id، title، status، و output، التي تحمل لقطة شاشة JPEG بترميز base64 عندما يكون include_screenshots مفعّلاً وتكون متاحة. ابقِ لقطات الشاشة بعيدًا عن السجلات؛ فقد تعرض بيانات الحساب.

يشير دليل استخدام الكمبيوتر إلى هذه المحاذير:

الموافقة على المصدر ليست تأكيدًا للإجراء. الموافقة على موقع لا تجعل الوكيل يطلب الإذن قبل كل عملية شراء أو حذف. إذا كنت بحاجة إلى ذلك، قم بتقييد المتصفح على الموارد التي لا يمكنها اتخاذ هذه الإجراءات، أو استخدم بيئة تشغيل متصفح تتحكم فيها.
تسجيل الدخول يغطي البريد الإلكتروني، كلمات المرور، ورموز التحقق. لا يتم دعم مفاتيح المرور (Passkeys) وتسجيل الدخول عبر رمز الاستجابة السريعة (QR-code).
الوكيل الرئيسي فقط يمكنه طلب المصادقة. لا يمكن للوكلاء الفرعيين (subagents) ذلك.
عطّل عمليات إعادة المحاولة التلقائية على تقديم بيانات الاعتماد (maxRetries: 0 في SDK، --retry 0 في curl).
يشير 202 إلى القبول، وليس إلى نجاح التنقل أو تسجيل الدخول. تنتهي صلاحية طلبات المصادقة بعد خمس دقائق.
الموافقة على المصدر لا تلغي سياسة الشبكة. اسمح للموقع ونطاقات إعادة التوجيه الخاصة به في network أيضًا.

يلخص الملخص أن استخدام الكمبيوتر متاح "عبر API وفي Codex وChatGPT Work على Pro 500 و Enterprise". للاختبار القائم على واجهة المستخدم (UI) باستخدام نفس النموذج، راجع استخدام الكمبيوتر GPT-6 Astra لاختبار API.

امنح الوكيل واجهة برمجة التطبيقات (API) الخاصة بك، وليس واجهة المستخدم (UI)

المتصفح هو الحل البديل للبرامج التي لا تحتوي على واجهة برمجة تطبيقات (API). إذا كان النظام ملكك، قم بتغليفه في خادم MCP: أدوات مكتوبة، لا توجد مطالبات بالمصدر، نتائج قابلة للتحقق. يغطي استخدام الكمبيوتر مقابل واجهات برمجة التطبيقات المهيكلة المقايضة، ويقوم خادم Apidog MCP بتغذية مواصفات API الخاصة بك لمساعد البرمجة الذي يكتب الغلاف (wrapper).

اختبر Agents API في Apidog قبل كتابة الكود

الـ API في مرحلة البيتا، لذا تأكد من شكل كل استدعاء يدويًا في Apidog أولاً:

أنشئ بيئة Apidog باستخدام OPENAI_API_KEY، VAULT_ID، و SESSION_ID. أرسل Bearer {{OPENAI_API_KEY}} و OpenAI-Beta: agents=v1 في كل طلب.
أرسل طلب إنشاء الجلسة بدون stream، تأكد من حالة 2xx و id غير فارغ، واستخرج id إلى SESSION_ID.
افتح تدفق الأحداث كطلب SSE، أرسل المدخلات من طلب ثانٍ، وشاهد الأحداث تصل.
احفظ حمولات الموافقة والإلغاء كطلبات لإعادة تشغيل كل حالة required_actions.
اربطها بسيناريو اختبار وقم بتشغيله في CI باستخدام Apidog CLI.

يحتوي دليل اختبار Agents API للذكاء الاصطناعي على أنماط تأكيد للمخرجات غير الحتمية. قم بتنزيل Apidog للمتابعة.

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

هل OpenAI Agents API مجاني؟ لا توجد رسوم على المنصة، لكنك تدفع مقابل الرموز المميزة للنموذج، واستدعاءات الأدوات، ووقت الحاوية المستضافة.

ما هي النماذج التي تعمل مع Agents API؟ تستخدم الأمثلة في الوثائق، بما في ذلك كل مثال على استخدام الكمبيوتر، نموذج gpt-6-astra. لا تسرد الصفحات نماذج أخرى مدعومة، لذا اختبر نموذجك أولاً.

هل يدعم Agents API خاصية Zero Data Retention (احتفاظ البيانات صفر)؟ لا. يدعم فقط إقامة البيانات في الولايات المتحدة وليس مؤهلاً لـ ZDR، حتى مع بيئة اختبار معزولة مستضافة ذاتيًا.

بماذا يختلف عن Agents SDK أو Responses API؟ يقوم SDK بتشغيل الحلقة داخل تطبيقك؛ Responses API هو استدعاء النموذج الذي تبني حلقة حوله. انظر المقارنة الكاملة.

ابدأ بجلسة واحدة للقراءة فقط

ابدأ بجلسة تقرأ فقط، أضف خادم MCP واحد، ثم أضف استخدام الكمبيوتر خلف معالج موافقة يرفض بشكل افتراضي. عندما يجب أن يتفاعل ChatGPT مع أحداث من خادمك الخاص بدلاً من ذلك، فإن MCP Events هي القطعة المطابقة.