هذه ترجمة آلية للمستند الأصلي باللغة الإنجليزية. في حال وجود أي تعارض بين هذه الترجمة والنسخة الإنجليزية الأصلية، تُعتمد النسخة الإنجليزية. اقرأ النسخة الإنجليزية الأصلية

API العام

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

URL الأساسي: http://localhost:3847/v1

المصادقة: طريقتان للمصادقة، كلاهما محكوم بمفتاح تبديل API في الإعدادات:

للمستهلكين الخارجيين (السكربتات، التكاملات، curl): قم بتعيين توكن وصول API في الإعدادات > الوصول إلى API، ثم استخدمه كتوكن حامل (Bearer token):

curl -H \"Authorization: Bearer YOUR_API_TOKEN\" http://localhost:3847/v1/providers

للتطبيق المحلي (تلقائي): تتم مصادقة تطبيق سطح المكتب وإضافات المتصفح وتطبيقات الهاتف في Caiioo تلقائياً عبر ترويسة مصادقة الترحيل الموجودة (x-relay-auth؛ ترويسات HTTP غير حساسة لحالة الأحرف). لا حاجة للإعداد اليدوي — يتولى التطبيق ذلك خلف الكواليس. تتجاوز طلبات relay-auth مفتاح تبديل "تمكين API العام" لأنها موثوقة بالفعل؛ فقط طلبات توكن الحامل هي التي تخضع لمفتاح التبديل.

الإعداد:

افتح إعدادات Caiioo > الوصول إلى API
قم بتفعيل تمكين API العام
قم بتعيين توكن وصول API (أي سلسلة تختارها — تعامل معها ككلمة مرور)
استخدم هذا التوكن في جميع طلبات API

يتوفر API على localhost ومن خلال الترحيل الخاص. تحقق من GET /v1/auth/info (لا يتطلب مصادقة) للحصول على الحالة الحالية وتعليمات الإعداد.

حدود المعدل: يتم تحديد معدل كل طلب /v1/* لكل عنوان IP للعميل — 100 طلب GET في الدقيقة للقراءة و 30 طلب كتابة في الدقيقة (POST / PATCH / DELETE) مجتمعة. الطلبات التي تتجاوز الحد تحصل على 429. تسليمات الويب هوك (POST /v1/webhooks/:id) لا تخضع لمصادقة التوكن الحامل ولا تخضع لهذه الحدود.

الملفات الشخصية

يمكن لجهاز واحد أن يحتوي على ملفات شخصية متعددة للمستخدمين (مثل شخصي + عمل). تتيح واجهة برمجة التطبيقات للسكربتات الخارجية فحص الملفات الشخصية المتاحة وتبديل الملف النشط قبل القيام بأعمال أخرى. لا يتم عرض عمليات إنشاء الملفات الشخصية وتحديثها وحذفها عبر واجهة برمجة التطبيقات العامة عن قصد — فهذه التدفقات تنتمي إلى واجهة إعداد التطبيق.

قائمة الملفات الشخصية:

GET /v1/profiles

تعيد { profiles: [...] } مع إدخال واحد لكل ملف شخصي غير محذوف. يتضمن كل إدخال id و name و email و avatarUrl و tier و accessibleModes و license و organization و preferences و onboardingComplete و createdAt و lastAccessedAt. يتم تجريد الحقول التي تحتوي على رموز (serviceCredentials و oauthConnections) والبيانات الداخلية للمزامنة (vectorClock و lastModifiedBy). استخدم /v1/connectors لفحص اتصالات OAuth.

الحصول على الملف الشخصي النشط:

GET /v1/profiles/active

تعيد { profile } للملف الشخصي المستخدم حالياً بواسطة هذا الخادم. جميع موارد /v1/* المرتبطة بملف شخصي (المحادثات، المرفقات، الإعدادات، المهارات) تعمل بناءً على هذا الملف.

تبديل الملف الشخصي النشط:

PUT /v1/profiles/active
Content-Type: application/json

{ "profileId": "user-uuid-from-list" }

تعيد { profile } للملف الشخصي النشط الجديد. تعيد 404 إذا كان المعرف غير معروف.

المزودون والنماذج

اكتشف مزودي نماذج اللغة الكبيرة (LLM) الذين تم تكوينهم والنماذج المتاحة.

قائمة المزودين:

GET /v1/providers

تُرجع جميع أنواع المزودين المدعومين. حالياً: anthropic و openai و google و openrouter و ollama و poe و mlx و perplexity و baseten و cloudflare. يتضمن كل إدخال type و displayName و icon و requiresApiKey و hasApiKey وكائن capabilities مع الأعلام الموضحة أدناه.

علم القدرة (Capability flag)	المعنى
`supportsVision`	يمكن للمزود قبول مدخلات الصور
`supportsPdfFile`	يمكن للمزود قبول كتل محتوى ملفات PDF الخام بشكل أصلي
`supportsToolCalling`	يدعم المزود استدعاء الوظائف/الأدوات
`supportsStreaming`	يقوم المزود ببث الرموز (tokens) بشكل تدريجي
`supportsExtendedThinking`	يوفر المزود ميزانية للاستنتاج/التفكير
`supportsPromptCaching`	يدعم المزود توجيهات تخزين الذاكرة المؤقتة للمطالبات (prompt-cache)
`nativeReasoningBlocks`	يصدر المزود التفكير ككتل رسائل أصلية (بدلاً من نص)
`requiresThoughtSignature`	يتطلب المزود إعادة إرسال رموز التفكير الموقعة

تعكس أعلام القدرات حقل readonly capabilities الخاص بكل فئة مزود (انظر src/shared/providers/*-provider.ts) ويتم التحقق منها بواسطة اختبار sentinel للانحراف — قم باستدعاء هذه النهاية الطرفية في وقت التشغيل بدلاً من كتابة المصفوفة بشكل ثابت.

ملاحظات لمزودي BYOK:

يعرض perplexity قائمة منسقة من نماذج Sonar (ليس لدى Perplexity نهاية طرفية عامة لـ /models).
مزود cloudflare (AI Gateway) هو BYOK + متعدد الموردين؛ يتم تحديد قائمة النماذج من خلال تكوين البوابة الخاصة بك ويتم إرجاعها كمصفوفة فارغة بواسطة /v1/providers/cloudflare/models. استخدم كتالوج البوابة الخاص بك.

قائمة النماذج لمزود معين:

GET /v1/providers/openrouter/models

تُرجع كتالوج النماذج لهذا المزود. يتضمن كل نموذج id و displayName و contextLength حيثما توفر ذلك. تُرجع الخطأ 503 عندما يفتقر المزود إلى مفتاح API أو عندما يتعذر الوصول إلى الكتالوج الرئيسي الخاص به.

الكتالوج الشامل لجميع المزودين:

GET /v1/models

تدمج النماذج من كل مزود تم تكوينه في قائمة واحدة. يتم تخطي المزودين الذين ليس لديهم مفاتيح API وإدراجهم في warnings.

الوكلاء

الوكلاء هم جوهر caiioo. كل وكيل هو وضع (Mode) — شخصية مكونة مع مطالبة النظام الخاصة بها، وأدواتها، ومتغيراتها، ومهاراتها.

قائمة بجميع الوكلاء:

GET /v1/agents

يعيد الوكلاء المدمجين (التسوق، مكان العمل، عام) وأي وكلاء مخصصين أنشأتهم. يتم تمييز كل منهم بـ source: \"builtin\" أو source: \"custom\".

إنشاء وكيل مخصص:

POST /v1/agents
Content-Type: application/json

{
  \"id\": \"my-research-agent\",
  \"branding\": {
    \"name\": \"Research Agent\",
    \"description\": \"يبحث في الويب ويلخص النتائج\"
  },
  \"defaultSettings\": {
    \"systemPrompt\": \"أنت مساعد بحث. استشهد دائماً بالمصادر.\",
    \"enabledTools\": { \"web_browsing\": true, \"search_tools\": true }
  },
  \"settingLevels\": {}
}

يعيد 201 مع الوكيل الذي تم إنشاؤه. يتم إرفاق ساعة متجهة تلقائيًا للمزامنة.

تحديث وكيل:

PATCH /v1/agents/my-research-agent
Content-Type: application/json

{ \"branding\": { \"name\": \"Research Agent\", \"description\": \"وصف محدث\" } }

يدمج التعديل في الوكيل الحالي ويرفع الساعة المتجهة. يعيد الوكلاء المدمجون 403 — فهم للقراءة فقط.

حذف وكيل:

DELETE /v1/agents/my-research-agent

حذف ناعم عبر شاهد القبر (يتزامن عبر الأجهزة). يعيد 204.

تشغيل الوكلاء (Agents)

هذا هو الحدث الرئيسي — استدعاء وكيل لمعالجة رسالة.

جسم الطلب (Request body) — الحقول المدعومة

الحقل	مطلوب	الوصف
`agentId`	نعم	معرف الوضع المدمج (مثل `general`) أو معرف وكيل مخصص
`input.message`	نعم	نص رسالة المستخدم
`input.attachments`	لا	مصفوفة من معرفات المرفقات (التي تم رفعها مسبقاً عبر `/v1/attachments`) لإرفاقها بهذا الدور
`input.variables`	لا	تجاوزات المتغيرات لكل تشغيل والتي يتم دمجها في محلل متغيرات الوكيل
`input.tabContext`	لا	سلسلة نصية حرة يتم حقنها كسياق صفحة (تستخدم بواسطة جسر المتصفح)
`input.messageId`	لا	معرف رسالة مقدم من العميل — مفيد لإلغاء التكرار في حال إعادة المحاولة
`threadId`	لا	سلسلة محادثات موجودة للاستمرار فيها. في حال حذفه، يتم إنشاء سلسلة جديدة وإرجاعها
`mode`	لا	`"sync"` أو `"async"`. الافتراضي هو `"async"`

الوضع المتزامن (Synchronous Mode)

انتظر الاستجابة الكاملة:

POST /v1/runs
Content-Type: application/json

{
  "agentId": "general",
  "input": { "message": "What's the weather in Paris today?" },
  "mode": "sync"
}

يُرجع 200 مع { content, usage, status: "completed" } بعد انتهاء الوكيل. إذا حدث خطأ في الوكيل، يُرجع 500 مع { error, status: "error" }. تنتهي مهلة التشغيل المتزامن بعد 5 دقائق مع status: "error" إذا لم يتم استلام حدث نهائي — استخدم الوضع غير المتزامن + SSE لأي شيء قد يستغرق وقتاً أطول.

الوضع غير المتزامن (Asynchronous Mode)

أرسل وانسَ — مفيد للمهام التي تستغرق وقتاً طويلاً:

POST /v1/runs
Content-Type: application/json

{
  "agentId": "my-research-agent",
  "input": { "message": "Write a 2000-word analysis of renewable energy trends" },
  "mode": "async"
}

يُرجع 202 فوراً مع { runId, threadId, status: "running" }.

الاستعلام عن الحالة (Poll):

GET /v1/runs/{runId}

يُرجع { run: { runId, threadId, agentId, status, createdAt, content?, usage?, error? } }. الحالة تكون واحدة من running أو completed أو error أو cancelled.

بث الأحداث في الوقت الفعلي (SSE):

GET /v1/runs/{runId}/events

يُرجع text/event-stream مع كل حدث للوكيل فور حدوثه: GENERATION_STARTED و STREAMING_CONTENT واستدعاءات الأدوات ونشاط الوكيل الفرعي والحدث النهائي (GENERATION_COMPLETE أو GENERATION_ERROR أو GENERATION_CANCELLED).

بعد الحدث النهائي، يرسل الخادم إطار SSE أخير مع event: terminal وحمولة بيانات فارغة كإشارة صريحة لنهاية البث، ثم يغلق الاتصال. يجب على العملاء اعتبار استلام هذا الإطار (أو إغلاق الاتصال) كإشارة للتوقف عن القراءة.

إذا قمت بالاشتراك بعد انتهاء التشغيل بالفعل، يقوم الخادم بإعادة تشغيل إطار واحد من نوع RUN_SNAPSHOT يحتوي على السجل النهائي الكامل record متبوعاً بإشارة event: terminal ثم يغلق الاتصال.

إلغاء التشغيل:

POST /v1/runs/{runId}/cancel

يُرجع { run: { ..., status: "cancelled" } }.

Threads

تُعد الـ Threads بمثابة محادثات. يتم تنفيذ كل تشغيل للوكيل (agent run) داخل thread، وتظل الـ threads مستمرة عبر الجلسات. تتيح لك الـ API إدراج، وقراءة، وإنشاء، وإدارة الـ threads برمجياً.

إدراج كافة الـ threads (البيانات الوصفية فقط):

GET /v1/threads

تُرجع { threads: [...] } للملف الشخصي الحالي مع تجريد الـ messages (استخدم نقطة نهاية التفاصيل عندما تحتاج إليها). يتم الاحتفاظ بكل حقل آخر — id و title و createdAt و updatedAt و modeId و archived وإحصائيات الاستخدام، بالإضافة إلى subAgentHistories و anonymizerSnapshot و threadToolApprovals و threadVariables و threadToolOverrides و messagingBinding و scheduledTaskId عند ضبطها. (تعتبر الحمولة الأكثر ثراءً حصرية لـ API — حيث يستخدم بث الشريط الجانبي عبر WebSocket تجريداً أكثر صرامة للبقاء ضمن حدود النقل.)

الحصول على thread مع الرسائل الكاملة:

GET /v1/threads/{id}

تُرجع الـ thread كاملاً بما في ذلك مصفوفة الـ messages الخاصة به — كل رسالة مستخدم، واستجابة مساعد، واستدعاء أداة، ونتيجة أداة.

الحصول على الرسائل فقط:

GET /v1/threads/{id}/messages

تُرجع مصفوفة الـ messages فقط — وهي أخف من كائن الـ thread الكامل عندما تحتاج فقط إلى المحادثة.

إنشاء thread:

POST /v1/threads
Content-Type: application/json

{ "title": "Research project", "modeId": "general" }

تُرجع 201 مع { thread }. يظهر الـ thread الجديد في الشريط الجانبي فوراً (عبر بث WebSocket). لا تقوم الـ API أبداً بتبديل الـ thread النشط في التطبيق عند الإنشاء — قم باستدعاء PUT /v1/threads/active بشكل منفصل إذا كنت ترغب في ذلك.

تحديث thread:

PATCH /v1/threads/{id}
Content-Type: application/json

{ "title": "Renamed project", "archived": true }

الحقول القابلة للتحديث: title و modeId و archived و lastUsedModel. يتم بث التغييرات إلى الشريط الجانبي في الوقت الفعلي.

حذف thread:

DELETE /v1/threads/{id}

تقوم بحذف الـ thread حذفاً ناعماً (علامة للحذف من أجل المزامنة). تُرجع 204. تنتقل الـ threads المحذوفة إلى سلة المهملات ويمكن استعادتها حتى يتم إفراغ السلة.

الـ thread النشط:

GET /v1/threads/active            # تُرجع { threadId }
PUT /v1/threads/active            # Body: { "threadId": "..." }

إدارة سلة المهملات:

GET /v1/threads/trash/count       # تُرجع { count }
POST /v1/threads/trash/empty      # تُرجع { deletedCount, protectedCount }

يتم استبعاد الـ threads المحمية (التي يتم الاحتفاظ بها عبر مفتاح تبديل استبقاء البيانات) من عملية إفراغ سلة المهملات.

متابعة محادثة عبر الـ API: لإرسال رسالة متابعة إلى thread موجود، استخدم POST /v1/runs مع معرف الـ thread:

POST /v1/runs
Content-Type: application/json

{
  "agentId": "general",
  "threadId": "existing-thread-id",
  "input": { "message": "Follow up on that last point" },
  "mode": "sync"
}

يرى الوكيل سجل المحادثة الكامل من الـ thread.

المرفقات

المرفقات هي ملفات مرتبطة بسلاسل الرسائل — لقطات شاشة، ملفات PDF، مستندات، صور مرفوعة، قطع أثرية مولدة. تتيح لك واجهة برمجة التطبيقات سردها، رفعها، تحميلها، وإدارتها.

قائمة بجميع المرفقات (البيانات الوصفية فقط):

GET /v1/attachments

تعيد البيانات الوصفية للمرفقات للملف الشخصي الحالي. يتم تجريد الحقول الثقيلة (dataUrl ،extractedContent ،extractedImages) — استخدم نقاط نهاية التفاصيل أو المحتوى لتلك الحقول.

قائمة المرفقات لسلسلة رسائل محددة:

GET /v1/threads/{threadId}/attachments

الحصول على البيانات الوصفية للمرفق:

GET /v1/attachments/{id}

تعيد البيانات الوصفية الكاملة بما في ذلك extractedContent (نص OCR، ماركداون محلل)، contentType ،fileName ،size وعلامة hasContent. الملف الثنائي الخام غير مدرج — استخدم نقطة نهاية /content لذلك.

تحميل الملف الثنائي للمرفق:

GET /v1/attachments/{id}/content

تعيد الملف الخام مع ترويسات Content-Type و Content-Disposition الصحيحة. قم بتوجيه هذا إلى ملف:

curl -o output.pdf \
  -H "Authorization: Bearer $API_TOKEN" \
  http://localhost:3847/v1/attachments/{id}/content

رفع مرفق:

POST /v1/attachments
Content-Type: application/json

{
  "threadId": "thread-id",
  "type": "user_upload",
  "contentType": "application/pdf",
  "fileName": "report.pdf",
  "description": "تقرير ربع سنوي",
  "dataUrl": "data:application/pdf;base64,JVBERi0xLjQ..."
}

الـ dataUrl هو رابط بيانات مرمّز بـ base64. تعيد 201 مع معرف المرفق الجديد. يتم ربط المرفق بسلسلة الرسائل المحددة.

تحديث البيانات الوصفية للمرفق:

PATCH /v1/attachments/{id}
Content-Type: application/json

{ "description": "وصف محدث", "fileName": "new-name.pdf" }

حذف مرفق:

DELETE /v1/attachments/{id}

حذف ناعم عبر علامة القبر. تعيد 204.

خوادم MCP

إدارة اتصالات خادم MCP (Model Context Protocol) الخاصة بك — وهي الخوادم التي تمنح الوكلاء (agents) إمكانية الوصول إلى الأدوات الخارجية ومصادر البيانات.

قائمة الخوادم المهيأة:

GET /v1/mcp-servers

تُرجع جميع تكوينات خادم MCP للملف الشخصي الحالي. يتم تجريد الحقول الحساسة (authToken و env و credentialId) من الاستجابة.

الحصول على تكوين خادم محدد:

GET /v1/mcp-servers/{id}

إضافة خادم MCP جديد:

POST /v1/mcp-servers
Content-Type: application/json

{
  "id": "my-server",
  "name": "My MCP Server",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/files"],
  "serverType": "local"
}

بالنسبة لخوادم HTTP البعيدة، استخدم "url" بدلاً من "command":

{
  "id": "remote-server",
  "name": "Remote API",
  "url": "https://my-mcp-server.example.com/sse",
  "serverType": "remote"
}

الحقول الاختيارية المقبولة في طلب POST هي: command و args و env و url و description و transportType و authType و authToken و authHeader و headers و specType و specPath و timeoutMs و credentialId و oauthConnectionId و approval. لا يمكن تعيين الحقول التي يديرها الخادم (customOAuth و hubPackageId و profileId و connectorId و teamPublished و teamOrgId و vectorClock و ...) عبر الـ API.

تحديث خادم:

PATCH /v1/mcp-servers/{id}
Content-Type: application/json

{ "name": "Renamed Server", "args": ["-y", "@mcp/server-v2"] }

تتطابق الحقول القابلة للتعديل (Patchable) مع القائمة المسموح بها في طلب POST (بما في ذلك credentialId و oauthConnectionId — وهو أمر مفيد لتدوير اتصال OAuth دون الحاجة للحذف وإعادة الإنشاء). تظل الحقول التي يديرها الخادم للقراءة فقط.

تفعيل/تعطيل خادم:

POST /v1/mcp-servers/{id}/toggle
Content-Type: application/json

{ "enabled": false }

حذف خادم:

DELETE /v1/mcp-servers/{id}

إدارة العمليات (Process Management)

بالنسبة لخوادم MCP المحلية (stdio)، يمكنك إدارة عملية الخادم مباشرة.

قائمة العمليات الجارية:

GET /v1/mcp-servers/processes

تُرجع عمليات الخادم الجارية مع حالة pid و startedAt و running.

بدء تشغيل خادم:

POST /v1/mcp-servers/{id}/start

يقرأ الـ command/args/env من تكوين الخادم وينشئ العملية. يُرجع حالة العملية.

إيقاف خادم:

POST /v1/mcp-servers/{id}/stop

يوقف عملية الخادم بشكل آمن (SIGTERM مع الرجوع إلى SIGKILL عند الضرورة).

استدعاء طريقة JSON-RPC مباشرة:

POST /v1/mcp-servers/{id}/call
Content-Type: application/json

{ "method": "tools/list", "params": {} }

يرسل طلب JSON-RPC 2.0 خام إلى الخادم ويُرجع النتيجة. مفيد لاستكشاف الأخطاء وإصلاحها أو استدعاء الطرق غير المعروضة من خلال واجهة برمجة تطبيقات الأدوات (tools API).

الأدوات ومجموعات الأدوات (Tools & Toolkits)

تصفح واستدعِ الأدوات التي تستخدمها الوكلاء — تصفح الويب، البحث، التقويم، Gmail، Slate، والمزيد.

قائمة مجموعات الأدوات (مجمعة):

GET /v1/toolkits

تُرجع الأدوات المدمجة مجمعة حسب الفئة (Productivity، Search، Utilities، إلخ) وأي خوادم MCP متصلة كمجموعات أدوات منفصلة، مع إدراج إجراءات كل منها.

قائمة بجميع الأدوات (مسطحة):

GET /v1/tools
GET /v1/tools?source=embedded   # الأدوات المدمجة فقط
GET /v1/tools?source=mcp        # أدوات خادم MCP فقط

الحصول على تفاصيل الأداة مع مخطط الإدخال (input schema):

GET /v1/tools/calculator

تُرجع { tool: { name, displayName, description, source, category, inputSchema, actions?, requiredTier?, requiredRuntimes?, riskTier?, riskExplanation?, requiresApproval? } }.

الحقل	المعنى
`inputSchema`	JSON Schema لمدخلات الأداة — تحقق من صحتها قبل الاستدعاء
`actions`	إجراءات فرعية اختيارية (مثل `read`/`write` في Slate)؛ كل منها يحتوي على `id` و `displayName` و `description` و `requiredTier` اختياري
`requiredTier`	الحد الأدنى لفئة المستخدم (`free` إذا تم حذفه). استدعاء API العام يرفض أي شيء أعلى من `free`
`requiredRuntimes`	المنصات التي تتوفر فيها هذه الأداة (`macos` و `ios` وغيرها)؛ الحذف يعني ⇒ في كل مكان
`riskTier`	مخاطر الموافقة: `low` (افتراضي)، `medium` ، `high`
`riskExplanation`	سبب مقروء بشرياً لارتفاع `riskTier`
`requiresApproval`	تكون `true` عندما تحتاج الأداة إلى موافقة المستخدم لكل مكالمة — استدعاء API العام يرفض هذه الأدوات

استدعاء أداة مباشرة:

POST /v1/tools/calculator/invoke
Content-Type: application/json

{ "input": { "expression": "sqrt(144) + 3^2" }, "threadId": "optional-thread-id" }

تُرجع { result }. يتم التحقق من صحة المدخلات مقابل مخطط الأداة — المدخلات غير الصالحة تُرجع 422 مع التفاصيل. قم بتمرير threadId اختياري إذا كانت الأداة تحتاج إلى سياق محدد للنطاق (مثل البحث عن المرفقات).

القيود — ما يرفضه API العام:

الأدوات المقيدة بالفئة (metadata.requiredTier !== 'free') ← 403. تتحقق حلقة الوكيل من الفئة مقابل جلسة المستخدم؛ لا يحتوي API العام على سياق فئة محمول، لذا فإن السياسة المتحفظة هي الرفض. استخدم POST /v1/runs مع وكيل لديه الفئة المناسبة بدلاً من ذلك.
الأدوات التي تتطلب موافقة (metadata.approval.requiresApproval === true) ← 403. لا يوجد إنسان في الحلقة لسؤاله. قم بالاستدعاء عبر POST /v1/runs (الذي يظهر المطالبة للمستخدم) أو اضبط وضع موافقة الأداة على approve_all في التطبيق للتجاوز.
أدوات MCP عن بعد ← 501 مع توجيه لاستخدام /v1/runs (تتطلب وسيلة نقل العمليات الفرعية للوكيل).

أدوات الرؤية واستخدام الصور: قم بالرفع عبر POST /v1/attachments أولاً، ثم قم بتمرير معرف المرفق (attachment ID) المُرجع داخل input (على سبيل المثال: { "input": { "attachment_id": "att_abc", "prompt": "What is in this image?" } }). تقرأ الأداة الملف الثنائي من التخزين عبر threadId؛ لا تقوم بتمرير البايتات بشكل مباشر.

الموصلات

إدارة تكاملات OAuth — Google و Microsoft و GitHub و Notion و Slack والمزيد.

تصفح التكاملات المتاحة:

GET /v1/connectors/catalog

يعيد جميع مزودي OAuth المسجلين مع أسمائهم وفئاتهم والنطاقات الافتراضية.

قائمة حساباتك المتصلة:

GET /v1/connectors

يعيد الاتصالات النشطة للملف الشخصي الحالي. لا يتم الكشف عن التوكنز أبداً — فقط البيانات الوصفية (المزود، البريد الإلكتروني، الحالة، النطاقات، الطوابع الزمنية).

الحصول على اتصال واحد:

GET /v1/connectors/{id}

يعيد البيانات الوصفية لاتصال واحد (المزود، البريد الإلكتروني، الحالة، النطاقات، الطوابع الزمنية). لا يتم الكشف عن التوكنز أبداً.

التحقق من صحة الاتصال:

POST /v1/connectors/{id}/test

يعيد { health: { status, isTokenExpired, canRefresh } }.

إزالة اتصال:

DELETE /v1/connectors/{id}

يتطلب إنشاء اتصالات جديدة مسار OAuth التفاعلي عبر واجهة مستخدم التطبيق أو مسارات /auth/*.

المشغلات

جدولة الوكلاء للعمل تلقائياً — ملخصات يومية، تقارير أسبوعية، مراقبة قائمة على فترات زمنية.

كل مشغل لديه مميز kind: schedule (افتراضي — يعمل حسب الساعة)، webhook (يعمل عندما تقوم خدمة خارجية بإرسال POST إلى مسار الويب هوك)، أو messaging (يعمل من محول رسائل متصل — مثل رسائل Slack/Discord الواردة التي تطابق فلتر القناة).

قائمة المشغلات:

GET /v1/triggers

يعيد { triggers: [...] }. يتضمن كل إدخال نوعه (kind) وجدوله والحقول الخاصة بنوعه (مثل webhookSecret/webhookPath لمشغلات الويب هوك، messagingAdapterId/messagingChannelFilter لمشغلات الرسائل).

الحصول على مشغل واحد:

GET /v1/triggers/{id}

إنشاء مشغل مجدول:

POST /v1/triggers
Content-Type: application/json

{
  \"name\": \"Morning Briefing\",
  \"prompt\": \"Summarize my unread emails and today's calendar\",
  \"modeId\": \"general\",
  \"schedule\": { \"type\": \"daily\", \"time\": \"08:00\" }
}

أنواع الجدولة المدعومة:

{ \"type\": \"interval\", \"minutes\": 60 } — كل N دقيقة (الحد الأدنى 15، الأقصى 1440)
{ \"type\": \"daily\", \"time\": \"09:00\" } — يومياً في وقت محدد
{ \"type\": \"weekly\", \"day\": \"mon\", \"time\": \"09:00\" } — أسبوعياً
{ \"type\": \"weekdays\", \"time\": \"08:30\" } — من الاثنين إلى الجمعة
{ \"type\": \"daysOfWeek\", \"days\": [\"mon\", \"wed\", \"fri\"], \"time\": \"10:00\" } — أيام محددة
{ \"type\": \"monthly\", \"dayOfMonth\": 1, \"time\": \"09:00\" } — شهرياً
{ \"type\": \"manual\" } — فقط عند التشغيل عبر API

تشغيل مشغل يدوياً:

POST /v1/triggers/{id}/fire

يعيد 202 مع threadId للتشغيل الناتج.

تحديث أو حذف:

PATCH /v1/triggers/{id}
DELETE /v1/triggers/{id}

الويب هوك (Webhooks)

تسمح مشغلات الويب هوك للخدمات الخارجية (مثل CI/CD، والمراقبة، ومنشئي النماذج) بتشغيل عميل ذكاء اصطناعي عبر بروتوكول HTTP.

إنشاء مشغل ويب هوك:

POST /v1/triggers
Content-Type: application/json

{
  "name": "Deploy hook",
  "prompt": "A deploy happened: {{webhook.body}}",
  "modeId": "general",
  "kind": "webhook"
}

يعيد الكود 201 مع webhookSecret و webhookPath. قم بتخزين السر — ستحتاجه لتوقيع حمولات البيانات.

إرسال ويب هوك:

# حساب HMAC-SHA256 لجسم الطلب الخام
SIGNATURE=$(echo -n '{"repo":"my-app","branch":"main"}' | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" | awk '{print $2}')

POST /v1/webhooks/{triggerId}
Content-Type: application/json
X-Webhook-Signature: $SIGNATURE

{"repo": "my-app", "branch": "main"}

نقطة نهاية الويب هوك لا تتطلب مصادقة حامل الرمز (bearer auth) — بل تستخدم تحقق HMAC بدلاً من ذلك. تعيد الكود 202 مع threadId للتشغيل المرسل. يتم استبدال العنصر النائب {{webhook.body}} في موجه المشغل بجسم الطلب الخام.

مشغلات المراسلة

تعمل مشغلات المراسلة عندما يتلقى محول مراسلة متصل (مثل تكامل Slack أو Discord المثبت عبر مركز المجتمع) رسالة واردة تطابق مرشح المشغل. يتم الإنشاء باستخدام kind: "messaging":

POST /v1/triggers
Content-Type: application/json

{
  "name": "Mention responder",
  "prompt": "Reply helpfully to: {{message.text}}",
  "modeId": "general",
  "kind": "messaging",
  "messagingAdapterId": "slack-team-acme",
  "messagingChannelFilter": "#support"
}

المحول مسؤول عن إرسال الأحداث المطابقة إلى المشغل؛ ويكون messagingChannelFilter خاصاً بالمحول المستخدم.

الوظائف المخصصة

أنشئ أدواتك الخاصة التي يمكن للوكلاء استدعاؤها. تُكتب الوظائف بلغة JavaScript أو Python وتُنفذ في بيئة معزولة (sandbox).

قائمة الوظائف:

GET /v1/functions

إنشاء وظيفة:

POST /v1/functions
Content-Type: application/json

{
  "name": "calculate_bmi",
  "description": "حساب مؤشر كتلة الجسم من الطول والوزن",
  "language": "javascript",
  "source": "return { bmi: (input.weightKg / (input.heightM * input.heightM)).toFixed(1) };",
  "inputSchema": {
    "type": "object",
    "properties": {
      "weightKg": { "type": "number" },
      "heightM": { "type": "number" }
    },
    "required": ["weightKg", "heightM"]
  }
}

تستقبل وظائف JavaScript الـ input ويجب أن تعيد نتيجة. وظائف Python تعين متغير result:

# مثال Python
result = {"bmi": round(input["weightKg"] / (input["heightM"] ** 2), 1)}

تنفيذ وظيفة مباشرة:

POST /v1/functions/{id}/execute
Content-Type: application/json

{ "input": { "weightKg": 75, "heightM": 1.80 } }

الأمان: تعمل JavaScript في بيئة vm الخاصة بـ Node (لا يوجد وصول لملفات النظام أو الشبكة، مهلة 10 ثوانٍ). تعمل Python كعملية فرعية بمهلة 30 ثانية. كلاهما يتحقق من صحة الإدخال قبل التنفيذ.

تحديث أو حذف:

PATCH /v1/functions/{id}
DELETE /v1/functions/{id}

المهارات

المهارات هي موجهات (prompts) محفوظة يمكن للعملاء الرجوع إليها وتشغيلها سريعاً من عرض المحادثة الفارغة. المهارات المثبتة عبر المركز (التي تدار عبر تثبيت الحزم) لا يتم تضمينها هنا — يتم فقط إدراج وتحرير المهارات التي كتبها المستخدم.

قائمة المهارات:

GET /v1/skills

تعيد { skills: [...] } للمهارات التي كتبها المستخدم للملف الشخصي النشط. يتم استبعاد المهارات المحذوفة مؤقتاً، ومهارات المركز، وظلال المزامنة.

الحصول على مهارة واحدة:

GET /v1/skills/{id}

إنشاء مهارة:

POST /v1/skills
Content-Type: application/json

{
  "prompt": "Summarize the page in 3 bullet points.",
  "tags": ["utility", "summarize"],
  "isFavorite": true,
  "modes": ["general"],
  "displayName": "Quick Summary",
  "description": "Three-bullet TL;DR of the active page"
}

حقل prompt فقط هو المطلوب. حقل modes (اختياري) يحدد المهارة لمعرفات عملاء محددة؛ اتركه فارغاً لجميع الأوضاع. يعيد 201 مع المهارة الجديدة (بما في ذلك id و createdAt و updatedAt المعينة من الخادم).

تحديث مهارة:

PATCH /v1/skills/{id}
Content-Type: application/json

{ "prompt": "Updated prompt", "isFavorite": false }

الحقول القابلة للتحديث: prompt و tags و modes و displayName و description و isFavorite. محاولات تحديث مهارة من المركز تعيد 404.

حذف مهارة:

DELETE /v1/skills/{id}

حذف ناعم عبر وضع علامة حذف. يعيد 204. مهارات المركز تعيد 404 — قم بإلغاء تثبيت حزمة المصدر بدلاً من ذلك.

سير العمل (Workflows)

تنسيق وكلاء متعددين في رسم بياني موجه غير حلقي (DAG) — تشغيل الخطوات بالتوازي حيثما أمكن، وتغذية مخرجات الخطوات السابقة في الخطوات اللاحقة.

التحقق من صحة رسم سير العمل:

POST /v1/workflows/validate
Content-Type: application/json

{
  "graph": {
    "nodes": [
      { "id": "research", "agentId": "general", "prompt": "ابحث في اتجاهات الطاقة المتجددة" },
      { "id": "analyze", "agentId": "general", "prompt": "ابحث في أسعار المنافسين" },
      { "id": "report", "agentId": "general", "prompt": "اكتب تقريراً يجمع بين: {{outputs.research}} و {{outputs.analyze}}", "dependsOn": ["research", "analyze"] }
    ]
  }
}

تعيد { valid: true/false, errors: [...] }. تتحقق من وجود دورات، معرفات مكررة، ومراجع تبعية مفقودة.

تنفيذ سير عمل:

POST /v1/workflows/execute
Content-Type: application/json

{
  "graph": {
    "nodes": [
      { "id": "research", "agentId": "general", "prompt": "ابحث في اتجاهات الطاقة المتجددة" },
      { "id": "summarize", "agentId": "general", "prompt": "لخص: {{outputs.research}}", "dependsOn": ["research"] }
    ]
  }
}

تعيد { status: "completed", outputs: { research: "...", summarize: "..." }, nodeResults: {...} }.

العقد المستقلة (التي لا تشترك في تبعيات) تعمل بالتوازي. يتم استبدال العنصر النائب {{outputs.nodeId}} في موجه العقدة بمحتوى مخرجات العقدة المصدر المحددة. كل عقدة هي تشغيل كامل للوكيل، لذا يمكنها استخدام الأدوات وتصفح الويب والوصول إلى جميع قدرات الوكيل المستهدف.

قواعد المعرفة

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

قائمة قواعد المعرفة:

GET /v1/knowledge/bases

إنشاء قاعدة معرفة:

POST /v1/knowledge/bases
Content-Type: application/json

{ "name": "أوراق بحثية" }

تعيد 201 مع معرف القاعدة الجديد.

رفع مستند إلى قاعدة معرفة:

POST /v1/knowledge/bases/{id}/documents
Content-Type: application/json

{
  "fileName": "research-paper.pdf",
  "contentType": "application/pdf",
  "dataUrl": "data:application/pdf;base64,JVBERi0xLjQ...",
  "description": "اتجاهات الطاقة المتجددة 2026"
}

حقل dataUrl هو رابط بيانات مرمّز بـ base64. تعيد 201 مع البيانات الوصفية للمستند.

قائمة المستندات في قاعدة معرفة:

GET /v1/knowledge/bases/{id}/documents

البحث داخل قاعدة معرفة:

POST /v1/knowledge/bases/{id}/search
Content-Type: application/json

{ "query": "الطاقة المتجددة" }

تعيد المستندات المطابقة بناءً على اسم الملف والوصف. البحث الدلالي (المتجهي) سيتوفر في إصدار مستقبلي.

حذف مستند أو قاعدة معرفة:

DELETE /v1/knowledge/bases/{id}/documents/{docId}
DELETE /v1/knowledge/bases/{id}

تصدير واستيراد الوكلاء

شارك الوكلاء كحزم محمولة — عبر الأجهزة، أو الفرق، أو مركز المجتمع.

تصدير وكيل:

POST /v1/agents/{id}/export

يعيد حزمة JSON تحتوي على تعريف الوكيل، ومتطلبات الأدوات (المشتقة من الأدوات الممكّنة)، ومتطلبات الموصلات (أي مزودي OAuth مطلوبين)، وقوالب المشغلات. يتم تجريد البيانات الوصفية للمزامنة — الحزمة عبارة عن مخطط نظيف ومستقل بذاته.

استيراد وكيل:

POST /v1/agents/import
Content-Type: application/json

{
  \"package\": {
    \"$schema\": \"caiioo.agent.package/v1\",
    \"agent\": {
      \"id\": \"shared-research-agent\",
      \"branding\": { \"name\": \"Research Agent\", \"description\": \"من الفريق\" },
      \"defaultSettings\": { \"systemPrompt\": \"أنت تبحث في الأشياء.\" },
      \"settingLevels\": {}
    },
    \"toolRequirements\": [
      { \"toolId\": \"web_browsing\", \"enabled\": true },
      { \"toolId\": \"search_tools\", \"enabled\": true }
    ]
  }
}

يعيد 201 مع الوكيل المثبت. تعيد تضاربات المعرفات (ID) مع الوكلاء المدمجين أو الحاليين 409.

معالجة الأخطاء

تستخدم واجهة برمجة التطبيقات (API) أكواد حالة HTTP القياسية:

الكود	المعنى
`200`	نجاح
`201`	تم الإنشاء
`202`	تم القبول (بدأت عملية غير متزامنة)
`204`	تم الحذف (لا يوجد محتوى)
`400`	طلب سيئ — تحقق من حقل `error` للتفاصيل
`401`	غير مصرح به — سر الجلسة مفقود أو غير صالح
`403`	محظور — مثلاً محاولة تعديل عميل مدمج
`404`	غير موجود
`409`	تعارض — مثلاً معرف العميل موجود بالفعل
`422`	خطأ في التحقق — الإدخال لا يطابق مخطط الأداة
`429`	تجاوز حد المعدل — راجع ميزانيات حدود المعدل في قسم المصادقة
`500`	خطأ في الخادم — تحقق من حقل `error`
`501`	غير منفذ — الميزة موجودة ولكنها غير متاحة بهذه الطريقة
`503`	الخدمة غير متوفرة — التخزين أو المزود غير جاهز

تتضمن جميع استجابات الخطأ { "error": "رسالة مقروءة للبشر" }.

مثال للبدء السريع

إليك سير عمل كامل: إنشاء وكيل، تشغيله، وبث النتائج.

# 1. إنشاء وكيل مخصص
curl -X POST http://localhost:3847/v1/agents \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "quick-summarizer",
    "branding": { "name": "Quick Summarizer" },
    "defaultSettings": {
      "systemPrompt": "لخص أي إدخال بإيجاز في 3 نقاط.",
      "enabledTools": { "web_browsing": true }
    },
    "settingLevels": {}
  }'

# 2. تشغيله بشكل غير متزامن
RUN=$(curl -s -X POST http://localhost:3847/v1/runs \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "agentId": "quick-summarizer", "input": { "message": "لخص https://en.wikipedia.org/wiki/Artificial_intelligence" }, "mode": "async" }')

RUN_ID=$(echo $RUN | jq -r '.runId')

# 3. بث الأحداث
curl -N http://localhost:3847/v1/runs/$RUN_ID/events \
  -H "Authorization: Bearer $API_TOKEN"

# 4. تصدير الوكيل للمشاركة
curl -X POST http://localhost:3847/v1/agents/quick-summarizer/export \
  -H "Authorization: Bearer $API_TOKEN"

This guide is maintained by the Caiioo team using Slate, our built-in editor.