واجهة برمجة تطبيقات Pokee للمؤسسات: وكلاء البيئة المعزولة الدائمة، التسعير وأول استدعاء لك

واجهة Pokee Enterprise API هي واجهة REST تشغّل وكيل ذكاء اصطناعي طويل المدى داخل بيئة معزولة (sandbox) مخصّصة ودائمة لكل عميل. تُنشئ جلسة، وترسل رسالة، ثم تقرأ إجابة الوكيل كتدفق Server-Sent Events (SSE). يمكن للجلسات أن تحتوي على ملفات ومهارات مخصّصة وأدواتك الخاصة وذاكرة تنتقل بين الجلسات. الوصول يكون عبر طلب عرض توضيحي من Pokee، وليس عبر تسجيل ذاتي.

في ما يلي: كيف تعمل الجلسات والتدفقات، وأول استدعاء لك، وتسعير Pokee Isaac، والحدود، وكيف تتيح لوكيل برمجي اختبار نقاط النهاية باستخدام Apidog CLI. كل رقم مأخوذ من وثائق Pokee، مقروءة في 28 أكتوبر 2026.

ما هي Pokee Enterprise API؟

تتيح لك Pokee Enterprise API (وتسميها Pokee واجهة Enterprise Responses API) تشغيل سير عمل يقوده وكيل ويستغرق دقائق لا ثوانٍ. يحصل كل مستأجر على مساحة عمل خاصة، ورمز حامل ثابت (bearer token)، ونطاق فرعي خاص به، https://your-tenant.enterprise.pokee.ai. وداخل مساحة العمل تلك، تكون كل جلسة عملية وكيل واحدة داخل بيئتها المعزولة.

استدعاء الدردشة يجيب عن مطالبة واحدة ثم ينسى. أما جلسة Pokee فتحتفظ بمحادثتها وملفاتها وحالة انشغالها، فيمكن للوكيل أن يبحث ويكتب ملفات ويستدعي أدوات عبر جولات عديدة. وإذا كنت قد قرأت دليلنا حول Claude Managed Agents، فسيكون الشكل مألوفًا: المزوّد يستضيف حلقة الوكيل والبيئة المعزولة، وأنت تديرها عبر HTTP.

وهي مصمّمة للفرق التي تريد وكيلًا مستضافًا مع عزل المستأجرين وضوابط شبكة على مستوى المؤسسات (قوائم IP المسموح بها، mTLS، AWS PrivateLink، تثبيت المنطقة)، وهي أمور تذكر Pokee أنها متاحة عند الطلب.

المفاهيم الأساسية: الجلسات والملفات والمهارات والذاكرة

تحتوي الواجهة على أربع لبنات بناء.

هناك بعض تفاصيل الجلسة المهمة مبكرًا:

• الاستمرارية. افتراضيًا تكون قيمة persistent هي false، وتدمّر الجلسة نفسها بعد 5 دقائق من آخر استجابة. اضبطها على true للإبقاء على الجلسة حتى تنتهي مدة ttl الخاصة بها (الافتراضية 14,400 ثانية، أي 4 ساعات) أو حتى تحذفها.
• قفل النموذج. النموذج model الذي تمرّره وقت الإنشاء يُطبَّق على كل جولة في تلك الجلسة.
• نطاق الملفات. مرّر file_access مع قوائم مسارات read و write لتقييد ما يراه الوكيل؛ وتعيد واجهة ملفات HTTP رمز 403 خارج ذلك النطاق.
• جولة واحدة في كل مرة. إرسال رسالة ثانية أثناء تشغيل جولة يعيد 409 Conflict.

كيف تجري أول استدعاء لواجهة Pokee API

تسلّمك Pokee قيمتين خارج القناة المعتادة: رابط المستأجر الخاص بك، ومفتاحًا بالشكل pk_<tenant>_<token>. بعد ذلك يتطلب الاستدعاء الأول ثلاث خطوات.

1. تحقّق من أن البوابة تعمل (لا حاجة للمصادقة).
2. أنشئ جلسة واحفظ قيمة id الخاصة بها.
3. أرسل رسالة واقرأ تدفق SSE.

export POKEE_API="https://your-tenant.enterprise.pokee.ai"
export POKEE_KEY="pk_<tenant>_<token>"

curl "$POKEE_API/health"

SID=$(curl -s -X POST "$POKEE_API/v1/sessions" \
  -H "Authorization: Bearer $POKEE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"persistent": true}' | jq -r '.id')

curl -N -i -X POST "$POKEE_API/v1/sessions/$SID/messages" \
  -H "Authorization: Bearer $POKEE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Summarize the files in my workspace in three bullets."}'

العلامة -i تطبع الترويسات. احفظ X-Response-Id (msg_ متبوعة بـ 24 حرفًا سادس عشريًا): فأنت تحتاجها لاستئناف الجولة أو إلغائها.

كل حدث يتكوّن من ثلاثة أسطر: id: و event: و data:. سترى message.created، ثم أجزاء text.delta (إضافة إلى أحداث thinking.* أو tool_use.*)، وينتهي التدفق بـ message.completed أو message.cancelled أو message.error. وإذا كان SSE جديدًا عليك، فإن دليل MDN لـ Server-Sent Events يشرح التنسيق، كما يوضح منشورنا حول اختبار واجهات LLM التي تبث عبر SSE كيفية قراءة الأجزاء.

استدعاء الأدوات: سطحان

تمنح Pokee الوكيل طريقتين لاستدعاء دوالك، وكلتاهما تستخدمان تعريفات دوال بأسلوب OpenAI.

المسار بلا حالة هو الخيار المناسب عندما تُدخل Pokee خلف كود مكتوب من أجل OpenAI Responses API، لأن شكل البيانات على السلك مطابق. ويقبل حتى 128 أداة في الطلب، وأسماء أدوات حتى 64 حرفًا، وأوصافًا حتى 16 كيلوبايت. كما يستقبل reasoning.effort (القيمة minimal، وهي الافتراضية، تُبقي التفكير الموسّع معطّلًا؛ بينما low و medium و high تشغّله). والمخرجات افتراضيًا 4,096 رمزًا، بحد أقصى 32,000.

أما أدوات الجلسة فتناسب الحالة التي ينبغي فيها للوكيل أن يفكّر ويشغّل المهارات ويستدعي أنظمتك أحيانًا في الجولة نفسها. وتسجّلها وقت إنشاء الجلسة.

الاستئناف والإلغاء ومفاتيح الـ idempotency

الجولات الطويلة تنكسر بطرق لا تنكسر بها الاستدعاءات القصيرة. وقد أضافت Pokee ثلاثة حلول في 4 مايو 2026، وفقًا لـ سجل التغييرات الخاص بها.

• الاستئناف. إذا انقطع اتصال عميلك في منتصف التدفق، يستمر الوكيل في العمل. أعد الاتصال بـ GET /v1/sessions/{id}/responses/{rid}/events مع ترويسة Last-Event-ID وسيعيد الخادم تشغيل الأحداث من الحدث التالي. تبقى الجولات المغلقة متاحة لمدة 120 ثانية، والاستئناف لا يعيد احتساب الرموز.
• الإلغاء. تعيد POST /v1/sessions/{id}/responses/{rid}/cancel رمز 202 وينتهي التدفق بـ message.cancelled. ولا يُحتسب الاستخدام الجزئي في جولة ملغاة. وتبقى الجلسة وملفاتها حيّة.
• مفاتيح الـ idempotency. أرسل Idempotency-Key: <uuid> مع طلب POST للرسالة. وإعادة المحاولة بالمفتاح والجسم نفسيهما تعيد معرّف الاستجابة الأصلي بدلًا من بدء جولة ثانية. تعيش المفاتيح 24 ساعة، ويعيد المفتاح نفسه مع جسم مختلف رمز 422.

والمسار بلا حالة /v1/responses يدعم الثلاثة جميعًا عندما تكون قيمة stream هي true.

نماذج Pokee Isaac والتسعير

تنشر Pokee فئتين من Isaac على صفحة النماذج والتسعير الخاصة بها. والأسعار لكل مليون رمز.

يستخدم المستأجرون الجدد pokee-isaac-high-reasoning افتراضيًا عندما تحذف model. وتتوفر خلفيات Kimi و GPT-5.5 و Gemini لكل مستأجر حسب العقد. ولا تذكر الوثائق فئة مجانية ولا حدًا أدنى للعقد؛ اسأل Pokee عن تلك الشروط.

وهناك أيضًا Direct Isaac API، أُضيفت في 7 أغسطس 2026: مسار POST /v1/chat/completions متوافق مع OpenAI، بلا حلقة وكيل أو أدوات. ويُفعَّل لكل مستأجر، ولا يقبل سوى pokee-isaac، ويوجّه الطلبات الطويلة (200,000 و 2,000,000 رمز فأكثر) تلقائيًا إلى مجموعات سياق أكبر. ويعرض GET /v1/usage رصيد أرصدتك.

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

الحدود ورموز الأخطاء

هذه هي القيم الافتراضية من صفحة الحدود والأخطاء. وتقول Pokee إنها تستطيع رفع أي منها عند الطلب.

رموز الأخطاء التي ستتعامل معها أكثر من غيرها: 401 (مفتاح خاطئ أو مفقود)، 402 (نفاد الأرصدة، في وضع الرصيد الصارم فقط)، 403 (مسار خارج نطاق الجلسة)، 409 (الجلسة مشغولة)، 422 (إعادة استخدام مفتاح idempotency مع جسم مختلف)، 429 (حد الاستخدام) و 500 (أعد المحاولة مع تراجع زمني). وتأتي الأخطاء بالشكل {"error": "<name>", "message": "<detail>"}.

دع وكيلك البرمجي يختبر Pokee API باستخدام Apidog CLI

لواجهة الجلسات عقد كبير يجب تثبيته: 201 عند الإنشاء، ومعرّف sess_، و 409 أثناء الانشغال، و 204 عند الحذف، و 202 عند الإلغاء. ويمكن لوكيلك البرمجي كتابة هذه الفحوصات وتشغيلها بينما تواصل عملك. ويمنح Apidog CLI كلا من Claude Code و Codex و Cursor الأوامر اللازمة لذلك.

أعدّه مرة واحدة:

npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_APIDOG_TOKEN>
apidog skill install

ثم أعطِ وكيلك مطالبة واحدة:

Write an OpenAPI file for the Pokee Enterprise API endpoints /health,
POST/GET/DELETE /v1/sessions, /v1/sessions/{id}/responses/{rid}/cancel and
/v1/usage, import it into Apidog project <projectId>, create an environment
for my tenant URL, then add test cases that assert 201 and an id starting
with "sess_" on create, 204 on delete and a credit balance on /v1/usage.
Run them and summarize failures. Read POKEE_KEY from my shell, never a file.

يستورد الوكيل المواصفة، ويتحقق من كل حمولة مقابل مخطط CLI، ثم ينشئ الحالات ويشغّلها:

apidog import --project <projectId> --format openapi --file ./pokee-openapi.json
apidog environment create pokee-tenant --project <projectId> --base-url https://your-tenant.enterprise.pokee.ai
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file create-session.json
apidog test-case create --project <projectId> --file create-session.json
apidog run --test-case <caseId> --project <projectId> -e <envId> --env-var "POKEE_KEY=$POKEE_KEY" -r cli,junit

تمرير المفتاح عبر --env-var يبقيه بعيدًا عن أي ملف يكتبه الوكيل. وتغطي هذه الحالات نقاط النهاية بصيغة JSON؛ أما تدفق SSE نفسه فمن الأسهل مراقبته في تطبيق Apidog، الذي يعرض الأحداث المدفوعة (انظر اختبار SSE في Apidog). وأمر apidog run نفسه مع -r junit ينضم إلى CI، كما يوضح دليل Apidog CLI لخطوط CI/CD. وإذا كنت جديدًا على CLI داخل وكيل؟ ابدأ بـ Apidog CLI في Claude Code. وتغطي خطة Apidog المجانية حتى 4 مستخدمين.

أين يتناسب Sharkly

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

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

هل توجد فئة مجانية لـ Pokee Enterprise API؟ لا تذكر الوثائق وجود واحدة. يبدأ الوصول بطلب عرض توضيحي، وتزوّدك Pokee برابط المستأجر والمفتاح خارج القناة المعتادة. والتسعير لكل رمز على فئتي Isaac المذكورتين أعلاه.

هل تتوافق Pokee API مع OpenAI؟ جزئيًا. فالمسار بلا حالة /v1/responses يطابق شكل بيانات Responses لدى OpenAI في استدعاء الدوال، ومسار Direct Isaac يقبل شكل طلب Chat Completions. أما نقاط نهاية الجلسات فهي خاصة بـ Pokee.

كم يمكن أن تستمر جولة وكيل Pokee؟ مهلة الجولة الافتراضية 90 دقيقة ومدة صلاحية الجلسة الافتراضية 4 ساعات. ويمكن رفع كلتيهما عند الطلب.

ماذا يحدث إذا انقطع اتصال عميلي في منتصف التدفق؟ يواصل الوكيل عمله. أعد الاتصال بنقطة نهاية الاستئناف مع Last-Event-ID في غضون 120 ثانية من إغلاق الجولة وستحصل على بقية الأحداث دون إعادة احتساب.

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