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

API العام

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

الإعداد:

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

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

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

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

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

GET /v1/providers

تعيد جميع أنواع المزودين المهيئين (Anthropic و OpenAI و Google و OpenRouter و Ollama و Poe و MLX و Baseten وغيرها عند إضافتها) مع علامات القدرات (supportsVision و supportsToolCalling و supportsStreaming وما إلى ذلك) وما إذا كان مفتاح API مهيأً.

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

GET /v1/providers/anthropic/models

تعيد دليل النماذج الخاص بذلك المزود. يتضمن كل نموذج المعرف id و displayName و contextLength حيثما توفرت.

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

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.

تشغيل الوكلاء

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

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

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

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

{
  "agentId": "general",
  "input": { "message": "ما هي حالة الطقس في باريس اليوم؟" },
  "mode": "sync"
}

تعيد الاستجابة 200 مع { content, usage, status: "completed" } بعد انتهاء الوكيل. إذا حدث خطأ في الوكيل، تعيد 500 مع { error, status: "error" }.

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

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

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

{
  "agentId": "my-research-agent",
  "input": { "message": "اكتب تحليلاً من 2000 كلمة لاتجاهات الطاقة المتجددة" },
  "mode": "async"
}

تعيد الاستجابة 202 فوراً مع { runId, threadId, status: "running" }.

الاستعلام عن الحالة:

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). ينتهي البث بعد الحدث النهائي.

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

POST /v1/runs/{runId}/cancel

تعيد { run: { ..., status: "cancelled" } }.

Threads

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

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

GET /v1/threads

تعيد الـ threads الخاصة بالملف الشخصي الحالي مع استبعاد الرسائل لتحسين الأداء. يتضمن كل thread كلاً من id و title و createdAt و updatedAt و modeId و archived وإحصائيات الاستخدام.

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

GET /v1/threads/{id}

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

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

GET /v1/threads/{id}/messages

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

إنشاء thread:

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

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

تعيد الاستجابة 201 مع الـ thread الجديد. افتراضياً، لا تقوم الـ API بتبديل الـ thread النشط في التطبيق — قم بتمرير "setActive": true في جسم الطلب إذا كنت ترغب في ذلك. يظهر الـ thread الجديد في الشريط الجانبي فوراً (عبر بث WebSocket).

تحديث 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            # جسم الطلب: { "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"
}

تحديث خادم:

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

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

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

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).

الأدوات ومجموعات الأدوات

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

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

GET /v1/toolkits

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

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

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

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

GET /v1/tools/calculator

تعيد JSON Schema للأداة لمعاملات الإدخال الخاصة بها، لتتمكن من التحقق من الصحة قبل الاستدعاء.

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

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

{ "input": { "expression": "sqrt(144) + 3^2" } }

تعيد { result }. يتم التحقق من الإدخال مقابل مخطط الأداة — الإدخال غير الصالح يعيد 422 مع التفاصيل. أدوات MCP البعيدة تعيد 501 مع توجيه لاستخدام /v1/runs بدلاً من ذلك (تتطلب نقل العملية الفرعية للوكيل).

الموصلات (Connectors)

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

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

GET /v1/connectors/catalog

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

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

GET /v1/connectors

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

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

POST /v1/connectors/{id}/test

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

إزالة اتصال:

DELETE /v1/connectors/{id}

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

المشغلات (Triggers)

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

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

GET /v1/triggers

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

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

{
  "name": "Morning Briefing",
  "prompt": "لخص رسائل البريد الإلكتروني غير المقروءة وتقويم اليوم",
  "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)

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

إنشاء مشغل webhook:

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

{
  "name": "Deploy hook",
  "prompt": "حدث نشر: {{webhook.body}}",
  "modeId": "general",
  "kind": "webhook"
}

تعيد 201 مع webhookSecret و webhookPath. احفظ السر — ستحتاجه لتوقيع الحمولات.

إرسال webhook:

# حساب 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"}

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

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

أنشئ أدواتك الخاصة التي يمكن للوكلاء استدعاؤها. تُكتب الوظائف بلغة 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}

سير العمل (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.

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

تستخدم واجهة برمجة التطبيقات رموز حالة HTTP القياسية:

الرمز المعنى
200 نجاح
201 تم الإنشاء
202 تم القبول (بدأت عملية غير متزامنة)
204 تم الحذف (لا يوجد محتوى)
400 طلب سيئ — تحقق من حقل error للتفاصيل
401 غير مصرح — سر الجلسة مفقود أو غير صالح
403 محظور — مثلاً محاولة تعديل وكيل مدمج
404 غير موجود
409 تعارض — مثلاً معرف الوكيل موجود بالفعل
422 خطأ في التحقق — الإدخال لا يطابق مخطط الأداة
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.