- Agents API و Agents SDK و Responses API
- ما هي بيئة الوكيل (Agent Harness)؟
- لماذا لا يزال الوكيل بحاجة إلى Sandbox
- Novita Sandbox في هذه البنية
- دورة الحياة، الاستمرارية، والعمل الطويل الأمد
- ربط Novita بالمسار المستضاف ذاتيًا
- الأمان وبيانات الاعتماد
- التكاليف والحدود
- أين تناسب هذه البنية
- الأسئلة الشائعة
- مقالات موصى بها
يمنحك OpenAI Agents API القدرة على بدء وكيل سحابي دائم من خلال استدعاء واحد لإنشاء جلسة، بينما يدير OpenAI بيئة الوكيل (harness) في السحابة. لا يحل Novita Sandbox محل Agents API أو بيئة الوكيل المدارة من OpenAI. بل يمنحك وقت تشغيل معزولًا وحافظًا للحالة لمسار التنفيذ المستضاف ذاتيًا الموثق من OpenAI: حيث يربط تطبيقك الـ sandbox بالجلسة، وينفذ الوكيل الأوامر ويحرر الملفات داخل ذلك الوقت التشغيلي، ويمتلك تطبيقك دورة حياة الـ sandbox. هذا التقسيم مهم عندما تريد سير عمل وكيل مستضاف من OpenAI، ولكنك تحتاج إلى بيئة منفصلة وقابلة لإعادة الاستخدام للكود والملفات والمتصفحات واستخدام الكمبيوتر والأعمال طويلة الأمد.
يشرح هذا الدليل المفاهيم الرئيسية للـ API، وكيفية تقسيم المسؤوليات بين بيئة الوكيل والبيئة، وكيفية ربط Novita Sandbox بالمسار المستضاف ذاتيًا، وما يجب التحقق منه قبل الانتقال من النموذج الأولي إلى الإنتاج. إذا كنت تحتاج فقط إلى صفحة المنتج، فإن Novita Sandbox هي أفضل نقطة بداية.
Agents API و Agents SDK و Responses API
يفصل مقارنة وقت تشغيل الوكيل من OpenAI بين ثلاثة نماذج تكامل:
| ما تريد فعله | استخدم | ما يدير الحالة |
|---|---|---|
| تشغيل مهمة طويلة الأمد من خلال بيئة Codex المدارة من OpenAI | Agents API | تكوين الجلسة المحفوظ، الأدوار، والعناصر |
| الاحتفاظ بحلقة الوكيل في تطبيقك | Agents SDK | حالة تطبيقك، جلسات SDK، أو محادثات Responses |
| استدعاء النماذج مباشرة وتنظيم كل شيء بنفسك | Responses API | سجل تطبيقك أو محادثات Responses |
Agents API هو الخيار الأعلى مستوى. يصفه OpenAI بأنه الوصول إلى بيئة Codex من خلال API مُدار من OpenAI. يتعامل مع الجلسات والتنسيق وضغط السياق والاسترداد. يعمل Agents SDK داخل تطبيقك ويمنحك تحكمًا أكبر في النشر والتخزين والموافقات وتكامل وقت التشغيل. Responses API هو الأقرب إلى طبقة النموذج. هذا التقسيم مفيد لأن “وكيل” يمكن أن يعني إما تكوين نموذج/أداة قابل لإعادة الاستخدام أو وكيلًا قيد التشغيل؛ وتستخدم وثائق API هذه المصطلحات بشكل مختلف في كل وقت تشغيل.
ما هي بيئة الوكيل (Agent Harness)؟
بيئة الوكيل هي الخدمة السحابية المحيطة بجولة الوكيل. فهي ترسل التعليمات والسياق إلى النموذج، وتستدعي الأدوات، وتتتبع التقدم، وتتعامل مع المقاطعة والاستئناف، وتنظم العمل في تدفق قابل للفحص. في Agents API، تلك البيئة هي بيئة Codex المُدارة.
تدعم البيئة المُدارة:
- تشغيل الأوامر والكود عند إرفاق بيئة.
- تطبيق المهارات والتعليمات ذات الصلة.
- الاتصال بالبيانات الخارجية من خلال الأدوات أو MCP.
- توجيه الوكيل أثناء عمله.
- تلخيص العمل السابق لإدارة نافذة السياق.
- تقسيم العمل إلى مهام فرعية وتفويضها لوكلاء فرعيين.
- استئناف الجلسة من حيث توقفت.
هذا لا يعني اختفاء تطبيقك. تطبيقك لا يزال ينشئ الجلسة، ويقدم المدخلات، ويستقبل الأحداث، ويتعامل مع الموافقات أو استدعاءات الوظائف، ويقرر كيفية تخزين المعرفات والقطع الأثرية. تقلل بيئة الوكيل من عمل التنسيق؛ فهي لا تزيل سياسة المنتج.
لماذا لا يزال الوكيل بحاجة إلى Sandbox
بعض الوكلاء يجيبون على الأسئلة أو يستدعون واجهات برمجة تطبيقات عن بُعد دون لمس نظام ملفات. آخرون يحتاجون إلى إنشاء ملفات، تثبيت تبعيات، تنفيذ سكربتات، فحص متصفح، التحكم في سطح مكتب، أو الحفاظ على مهمة متعددة الخطوات حية أثناء غياب المستخدم. يمنح الـ sandbox تلك الإجراءات بيئة تنفيذ قابلة للاستبدال بدلاً من تركها تلمس خادم منتجك أو جهازك المحلي.
يتعامل Agents API مع البيئة كخيار اختياري. تدعم وثائق هندسة OpenAI ثلاثة خيارات للتنفيذ:
none— لا تحتوي بيئة الوكيل على شل أو نظام ملفات. ترجع أدوات الوظائف النتائج إلى بيئة الوكيل.openai_hosted— يقوم OpenAI بتوفير وإدارة الـ sandbox.self_hosted— يبدأ تطبيقك البيئة ويوصلها، بحيث يمكنك استخدام الحوسبة الخاصة بك، أو شبكتك الخاصة، أو البرامج المخصصة.
هنا تكون الحدود بين النظامين أوضح. يمكن لـ Agents API و OpenAI استضافة بيئة الوكيل، ولكن البيئة المستضافة ذاتيًا تسمح لفريقك باختيار منصة التنفيذ. يؤثر هذا الاختيار على العزل، شكل نظام الملفات، الشبكات، حزم SDK، سلوك الإيقاف/الاستئناف، الفوترة، وكمية البنية التحتية التي تحتفظ بها.
Novita Sandbox في هذه البنية
Novita Sandbox هي بيئة تنفيذ مُدارة للوكلاء الذكاء الاصطناعي. تصف النظرة العامة الرسمية أوقات تشغيل معزولة وحافظة للحالة لتشغيل الكود، تثبيت التبعيات، الوصول إلى الملفات، استخدام المتصفحات، والحفاظ على الحالة عبر الجلسات دون إدارة البنية التحتية. في كومة وكيل Novita المباشرة، ينشئ تطبيقك الـ sandbox، ويختار النموذج أو إطار الوكيل استدعاءات الأدوات، وينفذها الـ sandbox، ويحتفظ تطبيقك بالسياسة والموافقات والتخزين خارج وقت التشغيل.
مع Agents API، فإن الإطار الدقيق الموصى به هو التكامل التكميلي وليس الأصلي: أدلة الـ sandbox المستضافة ذاتيًا الحالية من OpenAI تذكر Cloudflare و Daytona و DigitalOcean و E2B و Blaxel و Modal و Runloop و OCI و Vercel كمزودين موثقين. Novita Sandbox ليس حاليًا في قائمة المزودين تلك. لذلك فإن المسار العملي هو استخدام Novita كبيئة تنفيذ مُدارة من تطبيقك وربطها بجلسة Agents API من خلال عقد البيئة المستضافة ذاتيًا من OpenAI. هذا يحافظ على الفصل المفيد—يدير OpenAI بيئة الوكيل الدائمة، ويوفر Novita Sandbox وقت التشغيل—بدون ادعاء تكامل مزود رسمي لا تدعمه الوثائق الحالية.
تم بناء Novita Sandbox حول خمسة مفاهيم:
| المفهوم | ما يمنحه للوكيل |
|---|---|
| Sandbox | وقت تشغيل معزول مع نظام ملفات ومساحة عمليات خاصة به |
| Template | صورة بداية قابلة للتكرار، تبعيات، تكوين، وإعداد |
| Snapshot | حالة sandbox محفوظة يمكن إعادة استخدامها لتجنب الإعداد المتكرر |
| Secret | قيم مشفرة على نطاق الفريق تتجنب تضمين بيانات الاعتماد في الكود |
| Region | موقع نقاط النهاية الحالية US v1/v2 |
يدعم وقت التشغيل أعباء عمل وكيل الترميز، وكيل المتصفح، تحليل البيانات، البحث، و RL. نظرة عامة على Novita Sandbox هي المصدر للمناطق الحالية وسلوك دورة الحياة.
دورة الحياة، الاستمرارية، والعمل الطويل الأمد
لدى Novita Sandbox ثلاث حالات دورة حياة: قيد التشغيل، متوقف مؤقتًا، ومُنهى. يمكن لـ sandbox قيد التشغيل تنفيذ الأوامر وخدمة الاتصالات. يحافظ sandbox المتوقف مؤقتًا على نظام الملفات وحالة الذاكرة، بما في ذلك العمليات قيد التشغيل والمتغيرات، بينما تتوقف فوترة وحدة المعالجة المركزية والذاكرة العشوائية. تنقطع اتصالات الشبكة حتى الاستئناف. sandbox المُنهى يتم إنهاؤه ولا يمكن استعادته.
يتحكم ضابطان للوقت في عمليات الانتقال: مهلة sandbox تعد تنازليًا من الإنشاء، ومهلة الخمول تُطلق عندما لا يكون هناك عميل متصل للمدة المكونة. عند أي من الحدثين، يمكنك اختيار الإيقاف المؤقت بدلاً من الإنهاء، وتمكين الاستئناف التلقائي اختياريًا. هذا مفيد لمهمة تحرير كود تنتظر المراجعة، جلسة متصفح تتوقف بين الخطوات، أو دفتر تحليل بيانات يستأنف لاحقًا مع التبعيات والمتغيرات سليمة.
اللقطات (Snapshots) تختلف عن الإيقاف المؤقت. الإيقاف المؤقت يحتفظ بحالة sandbox الحالية لتلك النسخة. اللقطة تلتقط الحالة كبيئة قابلة لإعادة الاستخدام، بحيث يمكن لـ sandbox جديد البدء مع تبعيات وتكوين وملفات مثبتة بالفعل. في الإنتاج، استخدم القوالب للصور الأساسية القابلة للتكرار، واللقطات للحالات العاملة القابلة لإعادة الاستخدام، والأسرار لبيانات الاعتبار بدلاً من دمجها في قالب أو لقطة.
ربط Novita بالمسار المستضاف ذاتيًا
يحدد دليل الـ sandbox المستضاف ذاتيًا من OpenAI شكل الاتصال. ينشئ تطبيقك جلسة مع environment.type: "self_hosted"، ويستقبل معرف البيئة وعنوان URL البعيد، ويبدأ منفذًا داخل وقت التشغيل الخاص بك، ثم يبلغ بأن الجلسة متصلة. أمر المنفذ الرسمي هو:
codex exec-server \
--remote "<session.environment.remote_url>" \
--environment-id "<session.environment.id>"
يبلغ تدفق أحداث الجلسة عن agent.session.environment.pending أو connected أو failed. يجب أن تترك المنفذ قيد التشغيل بينما يعمل الوكيل وتنسق الإيقاف قبل إيقاف الحوسبة.
الرسم التخطيطي التالي يوضح جانب Novita من هذا التدفق باستخدام Novita SDK الرسمي. ينشئ sandbox، ويحضر المصادقة دون وضع سر في كود المصدر، ويمنحك المكان لبدء منفذ OpenAI. الطريقة الدقيقة لحقن مفتاح المنفذ وانتظار تدفق الأحداث تعتمد على تطبيقك وإصدار OpenAI SDK.
import os
from novita_sandbox import Novita
def create_agent_runtime() -> str:
novita = Novita(api_key=os.environ["NOVITA_API_KEY"])
sandbox = novita.sandbox.create(
"codex",
timeout=3600,
envs={"CODEX_API_KEY": os.environ["CODEX_EXECUTOR_KEY"]},
)
try:
sandbox.git.clone(
"https://github.com/your-org/your-repo.git",
path="/home/user/repo",
username="x-access-token",
password=os.environ["GITHUB_TOKEN"],
depth=1,
)
print(
"Create the Agents API session with environment.type=self_hosted, "
"then start codex exec-server here."
)
except Exception:
sandbox.kill()
raise
return sandbox.sandbox_id
قبل استخدام هذا المسار في الإنتاج، تحقق من كائنات OpenAI SDK الحالية، اسم مفتاح البيئة، سلوك عنوان URL البعيد، ومتطلبات دورة الحياة مقابل دليل sandbox المستضاف ذاتيًا من OpenAI. لا تفترض أن واجهة برمجة التطبيقات للجلسة ستدير الـ sandbox نيابة عنك؛ مع self_hosted، تلك المسؤولية تقع عليك صراحة.
بالنسبة لسير العمل الأبسط غير المتعلق بـ Agents API، يوضح دليل وكيل Codex من Novita كيفية تشغيل Codex CLI مباشرة على قالب codex، وبث مخرجاته، وإنهاء الـ sandbox عند الانتهاء.
الأمان وبيانات الاعتماد
تعامل مع بيئة الوكيل، الـ sandbox، وخادم التطبيق كمجالات ثقة منفصلة.
- احتفظ بمفاتيح OpenAI API، ومفاتيح Novita API، ورموز Git، وبيانات اعتماد قاعدة البيانات خارج الاستفسارات وملفات المصدر.
- استخدم أسرار Novita Sandbox للقيم الحساسة على نطاق الفريق المستخدمة داخل الـ sandbox.
- استخدم خزائن OpenAI لبيانات الاعتماد التي تقول إرشادات OpenAI إنها تنتمي خارج الـ sandbox.
- فضل الوصول الآمن إلى الـ sandbox. تقول وثائق Novita إن الوصول الآمن يتم تمكينه تلقائيًا للـ sandbox التي تم إنشاؤها بإصدار SDK 2.0.0 أو أحدث؛ قد تحتاج القوالب المخصصة القديمة إلى إعادة بناء.
- حدد سياسة شبكة صريحة ولا توسعها إلا عندما تحتاج المهمة إلى ذلك.
- راجع الكود والقطع الأثرية المولدة قبل أن تحصل على أذونات أوسع أو تصل إلى أنظمة الإنتاج.
تعمل هذه الضوابط معًا. يقلل الـ sandbox من نصف قطر انفجار الكود المولد، لكنه لا يأذن للوكيل، أو يتحقق من النية، أو يقرر أي القطع الأثرية يمكن أن تخرج من وقت التشغيل.
التكاليف والحدود
يقوم OpenAI بفوترة استخدام نموذج Agents API بأسعار النموذج المحددة وأدوات OpenAI بأسعارها القياسية. بالنسبة لبيئة مستضافة من OpenAI، ينطبق معدل الحاوية. بالنسبة للمسار المستضاف ذاتيًا، تكون موارد التنفيذ من تكلفة مزودك.
فوترة Novita Sandbox هي بالثانية لوحدة المعالجة المركزية والذاكرة العشوائية أثناء تشغيل الـ sandbox. إيقاف التشغيل يوقف فوترة وحدة المعالجة المركزية والذاكرة العشوائية. يتم الاحتفاظ بالبيانات المتوقفة كتخزين دائم؛ يشمل كل حساب 60 جيجابايت من التخزين الدائم المجاني، مع فوترة التخزين الإضافي بالساعة. يشمل كل sandbox قيد التشغيل 20 جيجابايت من التخزين المؤقت. تتغير أرصدة وأسعار Sandbox الرسمية، لذا تأكد من القيم الحالية على صفحة تسعير Novita Sandbox.
حدود حصة Novita مهمة أيضًا لأعباء العمل المتوازية. وقت كتابة هذا التقرير، الحسابات المجانية افتراضية بـ 5 sandbox متزامنة والحسابات المدفوعة بـ 100؛ تختلف الحدود القصوى لوحدة المعالجة المركزية الافتراضية والذاكرة لـ sandbox واحد حسب المستوى. يمكن تعديل حدود المؤسسة. تحقق من دليل حدود الحصة و Sandbox.get_quota() بدلاً من الاعتماد على الأمثلة في صفحات التسويق.
أين تناسب هذه البنية
وقت تشغيل Novita المستضاف ذاتيًا مناسب عندما:
- يجب على الوكيل تنفيذ كود، تعديل ملفات، تثبيت تبعيات، تشغيل اختبارات، تصفح الويب، أو التفاعل مع سطح مكتب.
- يحتاج التطبيق إلى جلسات حافظة للحالة عبر تأخير بشري، إعادة محاولة، أو مراجعات متعددة الخطوات.
- تريد تنفيذًا معزولاً منفصلاً عن خادم منتجك.
- يستفيد عبء عملك من القوالب، اللقطات، الإيقاف المؤقت/الاستئناف، أو البيئات القابلة للتكرار.
إنه ليس مناسبًا عندما:
- المهمة تحتاج فقط إلى استدعاءات وظائف عن بُعد ولا تحتاج إلى نظام ملفات أو شل.
- تحتاج إلى بيئة مُدارة من OpenAI ولا تريد امتلاك دورة حياة البيئة.
- تحتاج إلى مزود مدرج في أدلة مزودي sandbox المباشرين الحالية من OpenAI.
- يتطلب نموذج الامتثال الخاص بك ضوابط عزل مُدارة من المزود لم توثقها Novita لنشرك.
أفضل تقييم هو إثبات مفهوم صغير مع مستودعك الحقيقي، أوامرك، سياسة الشبكة، معالجة الأسرار، ومسارات الفشل. ثم قم بقياس بدء التشغيل، الإيقاف المؤقت/الاستئناف، إكمال المهمة، والتكلفة الإجمالية لتشغيل ممثل.
الأسئلة الشائعة
هل يتكامل Novita Sandbox أصلاً مع OpenAI Agents API؟
ليس وفقًا لأدلة مزودي البيئة الحالية من OpenAI. البنية الدقيقة هي استخدام مسار البيئة المستضافة ذاتيًا من Agents API، بدء Novita Sandbox كوقت تشغيل مُدار من تطبيقك، وتشغيل المنفذ الموثق داخله. تحقق من الأدلة الحالية قبل الإصدار لأن تكاملات المزود يمكن أن تتغير.
هل ما زلت بحاجة إلى Novita إذا كان OpenAI يقدم sandbox مستضافًا؟
يعتمد على متطلباتك. sandbox المستضاف من OpenAI هو مسار التشغيل المنخفض. Novita Sandbox مفيد عندما تريد خيار وقت تشغيل منفصل للصور المخصصة، القوالب، اللقطات، سير عمل المتصفح أو استخدام الكمبيوتر، الإيقاف المؤقت/الاستئناف الحافظ للحالة، أو التحكم على مستوى المزود في الموارد.
هل يمكن للوكيل الاحتفاظ بالعمليات والملفات عبر الإيقاف المؤقت؟
نعم. وثائق الإيقاف المؤقت/الاستئناف من Novita تقول إن نظام الملفات وحالة الذاكرة، بما في ذلك العمليات قيد التشغيل والمتغيرات، يتم الحفاظ عليها. تنقطع اتصالات الشبكة حتى يستأنف الـ sandbox.
هل هذا هو نفس OpenAI Agents SDK؟
لا. يعمل Agents SDK في تطبيقك ويمنحك تحكمًا أكبر في حلقة الوكيل. يستخدم Agents API بيئة Codex المُدارة من OpenAI. يمكن لـ Novita Sandbox استضافة التنفيذ لأي من النمطين، لكن سلوك الجلسة والتنسيق يختلف.
من أين يجب أن أبدأ؟
جرب البدء السريع لـ OpenAI Agents API لفهم جلسات وأحداث بيئة الوكيل. ثم أنشئ Novita Sandbox وقرر ما إذا كان وقت تشغيله، ودورة حياته، وأمانه، ونموذج التكلفة يتطابق مع احتياجاتك الإنتاجية.
