AI Agents API

تدير AI Agents API وكلاء AI للتوليد فقط: كائنات قابلة لإعادة الاستخدام تقرأ سياقاً محدوداً وتنتج مخرجات منظمة ومتحققاً منها كي تستخدمها الرحلات ووظائف الكتالوج. لا يملك الوكيل أدوات أو إجراءات؛ فلا يرسل ولا ينشئ تفرعات ولا يكتب من تلقاء نفسه. راجع دليل لوحة AI Agents للمفاهيم.

تعكس هذه API واجهة الإعدادات ← AI Agents. استخدمها لإنشاء الوكلاء برمجياً، وتسجيل مفاتيح موفري BYO، وتشغيل اختبار على سياق نموذجي، وقراءة آثار التشغيل.

كل النقاط نسبية إلى عنوان الأساس https://api-eu1.joryio.com. راجع نظرة عامة على API.

المصادقة

تتم مصادقة كل طلب بمفتاح API يملك النطاق المناسب أو بجلسة لوحة تحكم JWT. الوكلاء محددون بمساحة العمل؛ فلا يرى المفتاح ولا يعدل إلا وكلاء مساحته.

Authorization: Bearer your_api_key_or_jwt
Content-Type: application/json

النطاقات لكل نقطة نهاية

تحتاج نقاط القراءة ai_agents:read، ونقاط الكتابة ai_agents:write. ويمكن لجلسات لوحة التحكم استخدام settings:read أو settings:write بدلاً منها.

نقطة النهاية	النطاق
POST /ai-agents	ai_agents:write أو settings:write
GET /ai-agents وGET /ai-agents/{id}	ai_agents:read أو settings:read
PUT وPOST /ai-agents/{id}/archive وDELETE /ai-agents/{id}	ai_agents:write أو settings:write
POST /ai-agents/{id}/test	ai_agents:write أو settings:write
GET /ai-agents/{id}/runs	ai_agents:read أو settings:read
GET /ai-agents/provider-keys	ai_agents:read أو settings:read
PUT / DELETE /ai-agents/provider-keys/{provider}	ai_agents:write أو settings:write
POST /ai-agents/enrichment/run	ai_agents:write أو settings:write
GET /ai-agents/enrichment/jobs و/{jobId}	ai_agents:read أو settings:read

المفاهيم الأساسية

وضع النموذج والموفر

تكون modelMode إما managed أو byo:

• managed: نموذج Claude المستضاف من Joryio. يكون provider هو joryio، وتُحاسب عملية تشغيل واحدة برصيد واحد.
• byo: مفتاحك الخاص، والموفر أحد anthropic أو openai أو google أو azure أو bedrock. سجّل المفتاح أولاً، وتُحاسب العملية برسوم منصة ثابتة صغيرة.

مخطط المخرجات

يمكن أن تكون outputSchema.type من string أو number أو boolean أو json. في json قدّم مصفوفة fields من { name, type, description? } بحيث يكون type أولياً. اضبط includeExplanation: true لالتقاط تفسير النموذج في حقل explanation.

محددات السياق

contextSelectors قائمة اشتراك صريحة: لا يقرأ الوكيل شيئاً إلا ما تدرجه. وتشمل attributeKeys وsegmentIds وcatalogFields وrequiredCatalogFields، وهي حقول كتالوج يجب وجودها وإلا تتجاوز عملية الإثراء الصف بلا محاسبة، وincludeBrandVoice وincludeRecentEngagement وmaskPiiKeys. كما تُحجب دائماً البيانات المعلمة عالمياً كـ PII.

نتائج التشغيل

تنتهي كل عملية تشغيل بإحدى النتائج: success أو fallback أو timeout أو rate_limited أو invalid_config أو budget_exceeded. راجع عقد الأخطاء.

إنشاء وكيل

POST /ai-agents

الحقل	النوع	مطلوب	الوصف
name	string	نعم	اسم مقروء، حتى 200 حرف.
description	string	لا	وصف اختياري، حتى 1000.
tags	string[]	لا	وسوم مساحة العمل؛ كل منها حتى 60 وبحد 50.
instructions	string	نعم	تعليمات الهدف أو النظام مع Liquid، حتى 20000.
modelMode	string	لا	managed الافتراضي أو byo.
provider	string	لا	joryio أو anthropic أو openai أو google أو azure أو bedrock.
model	string	لا	معرّف نموذج محدد، مثل claude-opus-4-8.
thinkingLevel	string	لا	minimal أو low أو medium أو high.
contextSelectors	object	لا	ما يستطيع الوكيل قراءته.
outputSchema	object	لا	شكل المخرج المقيد به النموذج؛ الافتراضي { "type": "string" }.
fallbackValue	any	لا	قيمة تعاد عند فشل التشغيل.
dailyCap	integer	لا	حد الاستدعاء اليومي؛ الافتراضي 250000 والحد الأدنى 0.
guardrails	object	لا	maxOutputTokens وtimeoutMs وretryOnTransient.

curl -X POST https://api-eu1.joryio.com/ai-agents \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Cart subject-line writer",
    "instructions": "Write a short, upbeat email subject line for the abandoned cart. Max 60 characters.",
    "modelMode": "managed",
    "contextSelectors": { "attributeKeys": ["first_name", "cart_total"], "includeBrandVoice": true },
    "outputSchema": { "type": "json", "fields": [{ "name": "subject", "type": "string" }], "includeExplanation": true },
    "fallbackValue": { "subject": "You left something behind" },
    "dailyCap": 50000,
    "guardrails": { "timeoutMs": 20000, "retryOnTransient": true }
  }'

تعيد الاستجابة كائن الوكيل، شاملاً id وorganizationId وworkspaceId وstatus وinstructions وتهيئة النموذج والسياق والمخرجات وقيمة الاحتياط والحدود وبيانات الإنشاء والتحديث.

عرض الوكلاء والحصول على وكيل

GET /ai-agents
GET /ai-agents/{id}

يقبل العرض status=active أو status=archived ويعيد الوكلاء مع الأحدث تحديثاً أولاً. معامل {id} هو UUID الوكيل. يعيد الحصول على وكيل كائن الوكيل كاملاً أو 404 إن لم يوجد في مساحة العمل.

تحديث وكيل أو أرشفته أو حذفه

PUT /ai-agents/{id}
POST /ai-agents/{id}/archive
DELETE /ai-agents/{id}

أرسل في PUT الحقول التي تريد تغييرها فقط؛ تُقبل كل حقول الإنشاء إضافة إلى status، active أو archived. تؤدي الأرشفة الناعمة إلى status: archived، فتوقف الاستخدام مع الاحتفاظ بسجل التشغيل. ويعيد الحذف:

{ "success": true }

اختبار وكيل

شغّل الوكيل تجريبياً مقابل سياق نموذجي. تستخدم العملية سطح test ومفتاح تشغيل جديداً، فلا تُحسب ضمن رحلة حقيقية ولا تعيد حقول القياس.

POST /ai-agents/{id}/test

الحقل	النوع	الوصف
attributes	object	سمات جهة اتصال نموذجية مفاتيحها أسماء.
segmentMemberships	string[]	عضويات شريحة نموذجية.
catalogRecord	object	سجل كتالوج أو كيان نموذجي لإثرائه.
engagement	object	ملخص تفاعل حديث نموذجي.

{
  "outcome": "success",
  "output": { "subject": "Dana, your cart misses you" },
  "explanation": "Used the first name and an upbeat tone from the brand voice."
}

تكون outcome إحدى success أو fallback أو timeout أو rate_limited أو invalid_config أو budget_exceeded. وتكون explanation هي null إن لم يضمها المخطط.

عرض عمليات الوكيل

GET /ai-agents/{id}/runs?limit=25

يعيد آثار التشغيل الحديثة، الأحدث أولاً. يكون limit من 1 إلى 200 والافتراضي 50. يتضمن كل صف السطح والموفر والنموذج وعدد الرموز وزمن الاستجابة والنتيجة والمخرج والتفسير والخطأ والوقت. يخزن الأثر مراجع الإدخال فقط، مثل التنفيذ أو العقدة أو السجل أو المستخدم، ولا يخزن نص prompt الخام أبداً.

مفاتيح موفري BYO

عرض المفاتيح

GET /ai-agents/provider-keys

يعيد المفاتيح المسجلة لمساحة العمل. لا تعاد بيانات الاعتماد أبداً؛ يكون credentials دائماً {}.

إنشاء مفتاح أو استبداله

PUT /ai-agents/provider-keys/{provider}

يوجد مفتاح واحد لكل (workspace, provider). يكون {provider} أحد anthropic أو openai أو google أو azure أو bedrock. لا يأخذ موفر joryio المستضاف مفتاحاً ويُرفض.

الحقل	النوع	مطلوب	الوصف
credentials	object	نعم	بيانات اعتماد الموفر، مثل { "apiKey": "..." }؛ تُشفّر أثناء التخزين ولا تعاد.
label	string	لا	تسمية اختيارية حتى 120 حرفاً.

حذف مفتاح

DELETE /ai-agents/provider-keys/{provider}

يعيد { "success": true }.

تشغيل إثراء الكتالوج

شغّل وكيلاً للتوليد فقط على سجلات كيان مخصص واكتب كل مخرج في حقل مستهدف، مثل أوصاف المنتجات والوسوم والفئات الموحدة. المهمة غير متزامنة وفي قائمة انتظار: تنشئ هذه النقطة مهمة queued وتعيد فوراً، فيعالج الكتالوج الكبير، حتى 100 ألف صف، خارج مسار الطلب. المهمة مقاومة للتكرار لكل سجل؛ مفتاح التشغيل هو jobId:recordId، فلا تحاسب محاولة متكررة سجلاً أثري بالفعل.

POST /ai-agents/enrichment/run

الحقل	النوع	مطلوب	الوصف
agentId	string	نعم	وكيل نشط في مساحة العمل.
entityDefinitionId	string	نعم	تعريف الكيان المخصص الذي تثري سجلاته.
targetField	string	نعم	حقل السجل الذي يكتب فيه المخرج؛ يجب أن يكون معلناً في الكيان.
filter	object	لا	فلتر اختياري بأسلوب MongoDB.
limit	integer	لا	أقصى سجلات للمهمة، حتى 100000 وبحد صارم في الخادم.

الاستجابة تحمل jobId وstatus، queued عند التقديم، ومعرّفات الوكيل والكيان والحقل المستهدف وأعداد total وprocessed وsucceeded وfailed وskipped وerror والطوابع الزمنية.

مهام الإثراء

GET /ai-agents/enrichment/jobs/{jobId}
GET /ai-agents/enrichment/jobs?limit=20

استعلم عن مهمة واحدة لتتابع الحالة والأعداد، أو اعرض أحدث المهام لمساحة العمل. تكون الحالة queued أو running أو completed أو failed، ولا يُملأ error إلا إذا فشلت المهمة كاملة. يعيد الطلب 404 عند غياب المهمة ويحتاج إلى ai_agents:read أو settings:read.

استجابات الأخطاء

تشترك كل الأخطاء في الشكل القياسي؛ لا توجد مفردات منفصلة لرمز خطأ آلي. استخدم حالة HTTP وحقل message. راجع استجابة الخطأ.

الحالة	متى تحدث
400	إعداد غير صالح، كغياب instructions أو عدم وجود مفتاح BYO للموفر أو status غير مسموح.
401	مفتاح API مفقود أو غير صالح.
403	لا يملك المفتاح نطاق ai_agents:read أو ai_agents:write المطلوب.
404	الوكيل أو مهمة الإثراء أو مفتاح موفر BYO غير موجود.

الخطوات التالية

• AI Agents، دليل لوحة التحكم
• مفاتيح API والنطاقات
• Canvas API