الرابط الأساسي https://api.echonova.ai

المطورون

واجهة الوكلاء البرمجية

إنشاء الوكلاء وقراءتهم وتعديلهم ونسخهم وأرشفتهم عبر واجهة v1 البرمجية، مع صلاحيات المفتاح، وقواعد الترقيم وإعادة المحاولة والأرشفة، ورابط لكل نقطة نهاية.

تتيح واجهة الوكلاء البرمجية لخادمك إدارة وكلاء الصوت في مساحة عمل واحدة: عرضهم وقراءتهم، وإنشاءهم وتعديلهم ونسخهم وأرشفتهم واستعادتهم، وإضافة المعرفة والأدوات، وقراءة محادثاتهم. هي المجموعة نفسها من الوكلاء التي تراها تحت الوكلاء في البوابة، فيظهر التغيير الذي تجريه هنا هناك، والعكس صحيح.

ما تحتاج إليه

امنح المفتاح وصولًا إلى الوكلاء

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

المستوى النطاق ما يحق للمفتاح فعله
قراءة agents:read عرض الوكلاء والمعرفة والأدوات والمحادثات والنصوص المفرّغة والتسجيلات وجولات الاختبار، وقراءتها.
كتابة agents:write كل ما تتيحه قراءة، بالإضافة إلى إنشاء الوكلاء وتعديلهم ونسخهم وأرشفتهم واستعادتهم، وإضافة المعرفة والأدوات إليهم. كتابة تشمل قراءة.

يستطيع المفتاح أن يملك صفوف الوكلاء دون وصول إلى الكلام. صفوف الكلام في المفتاح لا تمنح وصولًا إلى الوكلاء، حتى لو كان المفتاح يسمح بكل واجهات الكلام. المفتاح الذي لا يملك النطاق يتلقى 403 مع الرسالة This API key cannot read agents. أو This API key cannot change agents..

يتصرف المفتاح باسم العضو الذي أنشأه، ويُجرى الفحص مع كل طلب:

  • القراءة تحتاج إلى أن يحتفظ العضو بصلاحية عرض الوكلاء وصلاحية إدارة واجهة المطورين البرمجية.
  • الكتابة تحتاج إلى صلاحية إدارة الوكلاء وصلاحية إدارة واجهة المطورين البرمجية.
  • إرفاق الأدوات وفصلها يحتاج أيضًا إلى صلاحية إدارة الأدوات.

العضو الذي يغادر مساحة العمل، أو يفقد إحدى هذه الصلاحيات، يأخذ معه وصول المفتاح إلى الوكلاء. عندها تقرأ الرسالة The member who created this API key cannot view agents. أو ... cannot manage agents. أو ... cannot manage tools.. نصوص الأخطاء كلها في الأخطاء.

الترقيم بالصفحات

القوائم التي تُرقَّم تأخذ offset وlimit. قيمة limit من 1 إلى 50، والافتراضي 20. قيمة offset من 0 إلى 10000، والافتراضي 0. تعود الصفحة ككائن يحمل الصفحة والعدد الكامل:

{
  "data": { "items": [], "total": 0 },
  "success": true,
  "statusCode": 200,
  "errorMessage": null
}

ترقّم نصوص المحادثة حسب الوقت: تعيد أحدث الرسائل أولًا، 20 رسالة افتراضيًا و50 رسالة كحد أقصى، والحقل before يأخذ createdAt لأقدم رسالة تحتاجها، فتعود الصفحة التي قبلها. قائمة جولات الاختبار تأخذ limit من 1 إلى 10، والافتراضي 2.

الوكلاء المؤرشفون

الأرشفة تُخرج الوكيل من القائمة الافتراضية، وهي تعرض كل وكيل غير مؤرشف. الوكيل المؤرشف يرفض كل تغيير بالرمز 409 والرسالة This agent is archived. Restore it before changing it.. الاستدعاءات الوحيدة التي تعمل عليه هي النسخ والأرشفة والاستعادة. استعده أولًا، أو انسخه وعدّل النسخة.

الإنشاء والنسخ والاستعادة تُحتسب ضمن الوكلاء النشطين الذين تسمح بهم خطتك، وتفشل بالرسالة Workspace has reached the maximum number of agents allowed by the current plan عندما تكون مساحة العمل ممتلئة.

أعد محاولة الإنشاء بأمان

يقبل POST /v1/agents وPOST /v1/agents/{agentId}/duplicate header اختياريًا باسم Idempotency-Key، فلا تنشئ إعادة المحاولة بعد ضياع الرد وكيلًا ثانيًا. القواعد موضحة في أعد إرسال الطلبات بأمان. أي عملية كتابة أخرى ليست idempotent: تكرارها يطبقها من جديد.

المعرفة والأرصدة

إضافة المعرفة تفهرسها، والفهرسة تستهلك أرصدة مساحة العمل. هذا الاستهلاك لا يُحتسب ضمن حد الرصيد الخاص بالمفتاح. لذلك يستطيع مفتاح له كتابة للوكلاء أن ينفق أرصدة مساحة العمل على الفهرسة، حتى يغطي رصيد مساحة العمل ذلك، إلى أن تعطّل المفتاح أو تحذفه. يقبل كل من مساري إضافة المعرفة حتى 20 استدعاءً في الدقيقة لكل مفتاح. امنح الوكلاء على كتابة فقط للمفاتيح التي تثق بها في ذلك.

Webhooks

إنشاء الوكيل وتعديله وأرشفته واستعادته، وانتهاء بناء وكيل بنجاح، ترسل أحداث Webhook. راجع أحداث Webhook.

MCP يستخدم تسجيل الدخول لا المفاتيح

تصل تطبيقات الذكاء الاصطناعي مثل Claude إلى الإجراءات نفسها للوكلاء عبر MCP. تسجّل الدخول بحساب إيكونوڤا عبر OAuth، ولا تأخذ مفتاح API أبدًا. راجع ربط إيكونوڤا بـ Claude.

نقاط النهاية

القراءات تحتاج إلى الوكلاء على قراءة أو كتابة.

يمكن قراءة جولات الاختبار التي تبدأ من البوابة بهاتين النقطتين. بدء جولة اختبار عبر الواجهة البرمجية غير متاح بعد.

الكتابات تحتاج إلى الوكلاء على كتابة.

الأرشفة والاستعادة تحتاجان إلى الوكلاء على كتابة، وتعملان على الوكلاء المؤرشفين أيضًا.

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

هل يستطيع المفتاح إنشاء وكيل يستقبل المكالمات؟

الوكيل الجديد ليس له قناة، لذلك لا يستقبل مكالمات حتى تربط قناة به من البوابة. الواجهة البرمجية لا تربط القنوات.

هل يرى المفتاح وكلاء مساحات العمل الأخرى؟

لا. المفتاح يعمل لمساحة العمل التي تملكه. معرّف وكيل من مساحة عمل أخرى يعيد 404 مع Agent not found، تمامًا كما يفعل أي معرّف غير معروف.