الوكيل: الإعداد والصوت والنشر

دورة حياة الوكيل

1. تنشئ الوكيل في Studio ← الوكلاء، فيبدأ بمراجعة مسودة.
2. تضبط العقل والتعليمات والمعرفة والصوت وشكل الرد، وتجربه داخل Studio.
3. تنشر المراجعة: من هذه اللحظة تعمل بها كل الجلسات الجديدة، في الويدجت والـAPI.
4. أي تعديل بعد التجربة يفتح مراجعة جديدة تلقائياً، وتبقى المنشورة كما هي حتى تنشر الجديدة.
5. إن ظهرت مشكلة، تتراجع إلى المراجعة السابقة بنقرة.

GET/api/v1/workspaces/{workspace_id}/agents/{agent_id}/releases

POST/api/v1/workspaces/{workspace_id}/agents/{agent_id}/releases/publish

POST/api/v1/workspaces/{workspace_id}/agents/{agent_id}/releases/rollback

كل نشر يرفع epoch. ولتجنب نشرين متزامنين أرسل expected_epoch بالقيمة التي قرأتها، فيُرفض الطلب إن سبقك نشر آخر.

POST /api/v1/workspaces/{workspace_id}/agents/{agent_id}/releases/publish
{ "agent_version_id": "01a14abf-977a-78c8-…" }

200
{
  "release": {
    "agent_id": "01a14abf-9774-7a0a-…",
    "published_version_id": "01a14abf-977a-78c8-…",
    "previous_version_id": null,
    "epoch": 1,
    "published_at": "2026-10-17T16:43:53.166019Z"
  }
}

من يكتب الردود

في صفحة الوكيل ← «شكل الرد» ← «من يكتب الردود؟» تختار أحد النمطين، وكلاهما مدعوم بالكامل:

• عقل صُرَد (SURAD_MANAGED): يكتب الوكيل ردوده بنموذجه وتعليماته ومعرفته. النموذج الافتراضي Gemini 2.5 Flash تشغّله المنصة بلا مفاتيح منك، أو نقطة نهاية متوافقة مع OpenAI تربطها مساحتك.
• عقلك الخاص (EXTERNAL_AGENT): نظامك يكتب الرد ويرسله جاهزاً، وصُرَد يتولى الصوت والاستماع والجلسات. منطق أعمالك وذاكرتك وأدواتك تبقى عندك كما هي (انظر الصوت لعقلك الخاص).

GET/api/v1/workspaces/{workspace_id}/agents/{agent_id}/orchestration

PUT/api/v1/workspaces/{workspace_id}/agents/{agent_id}/orchestration

GET/api/v1/workspaces/{workspace_id}/agents/{agent_id}/orchestration/default/{mode}

عند التبديل عبر API ابدأ من إعداد النمط الافتراضي (المسار الأخير)، ثم أضف إليه الصوت والقنوات. فقواعد الصلاحيات تختلف بين النمطين، والإعداد الخليط يُرفض.

العقل والتعليمات (العقل المُدار)

PATCH/api/v1/workspaces/{workspace_id}/agents/{agent_id}/versions/{agent_version_id}/runtime-profile

ويستند الوكيل إلى قواعد المعرفة المربوطة بمراجعته ولا يتجاوزها: إن لم يجد الجواب فيها قال إنه لا يعرف بدل أن يختلق. المعرفة تُدار من Studio ← قاعدة المعرفة (نص، أو ملفات .txt و.md وPDF نصي حتى 2MB).

شكل الرد وطوله

كلها حقول في إعداد القناة (orchestration)، وتسري بالنشر.

الصوت وثبات الشخصية

اختيار الصوت

تختار الصوت من الكتالوج في Studio ← الوكيل ← الصوت، مع السرعة والنبرة. الصوت الذي تختاره هو ما يسمعه عملاؤك، في الويدجت والـAPI. وإن تعذّر تحميله لسبب ما، يعود الطلب بخطأ صريح (AUDIO_PRODUCTION_FAILURE) بدل أن ينطق بصوت شخصية أخرى.

GET /api/v1/workspaces/{workspace_id}/speech/experience/catalog
→ "voices": [ … {
  "library_id": "vp-msa-male",
  "label_ar": "فصحى واضحة — ذكر",
  "provider_id": "chirp3_hd",
  "voice_id": "ar-XA-Chirp3-HD-Charon",
  "gender_presentation": "male",
  "selectable": true,
  "experimental": false,
  "lifecycle": "GA",
  "speaking_rate": true,
  "streaming": true,
  "availability": "ready"
} … ]

الأصوات الافتراضية للجميع: vp-msa-female (أنثى، الافتراضي) وvp-msa-male (ذكر)، من Google Chirp3-HD. والأصوات المخصصة بنبرة لهجية (مثل صوت عهود) تُفعَّل لمساحات بعينها بالاتفاق معنا.

قواعد النطق

لأسماء العلامات والمنتجات والمصطلحات: تكتب الكلمة كما تظهر، وكيف تُنطق. القاعدة تسري على الوكيل أو على المساحة كلها.

PUT /api/v1/workspaces/{workspace_id}/agents/{agent_id}/voice-experience
{ "library_id": "vp-msa-male", "speaking_speed_level": 0, "tone": "confident" }

POST /api/v1/workspaces/{workspace_id}/speech/pronunciation-rules
{ "written": "SURAD", "spoken": "صُرَد", "confirm": true }

201
{ "id": "01a14abf-9a2e-…", "written": "SURAD", "spoken": "صُرَد", "enabled": true,
  "review_state": "confirmed", "scope": "workspace_entity", "agent_id": null, "version": 1 }

التحقق من الصوت في كل رد

كل رد منطوق يحمل audio.executed_voice (الصوت الذي نطق فعلاً) في كل المسارات، ومعه ملف الصوت: identity.voice_profile_id في أدوار عقل صُرَد، وidentity.executed_profile_id في النطق للنص الجاهز. سجّلها مع قياساتك لتطمئن أن شخصية الوكيل ثابتة.

قراءة قدرات الوكيل

GET/api/v1/workspaces/{workspace_id}/agents/{agent_id}/capabilities

تصف ما يتاح لهذا الوكيل فعلاً: الصوت المهيأ ومسارات النطق المتاحة. اقرأها بدل افتراض القدرات.