كيفية استخدام 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 سبتمبر.

جرّب Apidog اليوم

ستتعلم أدناه كيفية إنشاء جلسة 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)، وفقًا لصفحة البنية، تشغيل حلقة النموذج والأدوات وضغط السياق، لذلك لا تحتاج إلى إعداد ضغط السياق بنفسك.

اختر بيئة

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

• none: لا توجد حوسبة. تستمر خوادم MCP البعيدة وأدوات الوظائف الخاصة بك في العمل، لكن Bash المدمج وapply-patch وملفات مساحة العمل وMCPs المنفذة لا تعمل.
• openai_hosted: يدير OpenAI بيئة Linux معزولة تحتوي على Python وNode.js في /workspace.
  • عيّن container_size إلى small (1 جيجابايت)، أو medium (الافتراضي، 4 جيجابايت)، أو large (16 جيجابايت).
  • عيّن network.access إلى enabled أو disabled أو restricted مع allowed_domains.
  • تصبح الملفات الموجودة في /workspace/outputs آثارًا (artifacts) عند اكتمال الدور.
  • قد تُحذف البيئة الخاملة دون 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 البنية نفسها. يضيف المثال التالي أداة، ووكلاء فرعيين، وخزانة (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 عندما يحتاج الوكيل إلى نتيجة وظيفة أو اتصال بيئة أو موافقة على استخدام الكمبيوتر.

ضع هذه النقاط في معالجة الأخطاء:

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

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"
}

لذلك يجب أن يكون خادم MCP قابلًا للوصول من OpenAI. استخدم:

• connection_origin: "environment" لخادم داخل شبكة خاصة.
• stdio لبدء الخادم داخل البيئة المعزولة.
• transport.authorization لبيانات اعتماد جلسة واحدة.
• vault_ids لإرفاق بيانات اعتماد من الخزانة، مثل static_bearer أو mcp_oauth.

فعّل البحث عن الأدوات

تُكتشف أدوات 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:

1. استرجع الجلسة.
2. ابحث عن إدخالات computer_use_approval_request.
3. افحص request.type.
4. أرسل الاستجابة المناسبة عبر نقطة نهاية الأحداث.

يوجد نوعان من الطلبات:

• 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. عندما يكون include_screenshots مفعّلًا، قد يتضمن output لقطة شاشة JPEG بترميز base64.

لا تضع لقطات الشاشة في السجلات؛ فقد تعرض بيانات الحساب.

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

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

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

امنح الوكيل API الخاصة بك، وليس واجهة المستخدم

المتصفح حل بديل للأنظمة التي لا توفر API. إذا كان النظام ملكك، فحوّله إلى خادم MCP:

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

راجع استخدام الكمبيوتر مقابل واجهات برمجة التطبيقات المهيكلة لفهم المقايضة. ويمكن لـخادم Apidog MCP توفير مواصفات API الخاصة بك لمساعد البرمجة الذي يكتب الغلاف (wrapper).

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

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

1. أنشئ بيئة Apidog تتضمن OPENAI_API_KEY وVAULT_ID وSESSION_ID.
2. أرسل الهيدرين التاليين في كل طلب:

   Authorization: Bearer {{OPENAI_API_KEY}}
   OpenAI-Beta: agents=v1

1. أرسل طلب إنشاء الجلسة بدون stream، ثم تحقق من حالة 2xx ومن أن الحقل id غير فارغ.
2. استخرج id إلى المتغير SESSION_ID.
3. افتح تدفق الأحداث كطلب SSE، ثم أرسل الإدخال من طلب ثانٍ وتحقق من وصول الأحداث.
4. احفظ حمولات الموافقة والإلغاء كطلبات مستقلة لتتمكن من إعادة تشغيل كل حالة من required_actions.
5. اربط الطلبات بسيناريو اختبار وشغّله في 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 هو استدعاء النموذج الذي تبني حلقة حوله. راجع المقارنة الكاملة.

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

ابدأ بتطبيق محدود النطاق:

1. أنشئ جلسة للقراءة فقط.
2. أضف خادم MCP واحدًا فقط.
3. اختبر الاستدعاءات والأحداث والمخرجات.
4. أضف استخدام الكمبيوتر فقط خلف معالج موافقة يرفض الطلبات افتراضيًا.
5. وسّع الأذونات والأدوات تدريجيًا بعد التحقق من السلوك.

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