المطورون / الوكلاء
إضافة صفحة ويب أو موقع إلى وكيل
https://api.echonova.ai/v1/agents/{agentId}/knowledge/webتُضيف صفحة https عامة، أو موقعًا يُزحف منها (حتى 3 روابط في العمق و50 صفحة)، إلى قاعدة معرفة مساحة العمل وإلى هذا الوكيل. تُقرأ في الخلفية ولا تُعاد قراءتها وفق جدول زمني؛ وتعرض `GET /v1/agents/{agentId}/knowledge` حالتها. إذا كان الرصيد فارغًا تردّ الواجهة بالرمز 402. بحد أقصى 20 طلبًا في الدقيقة لكل مفتاح. يحتاج المفتاح إلى النطاق `agents:write`. تستهلك الفهرسة رصيد مساحة العمل، ولا تُحتسب ضمن حد رصيد مفتاح الواجهة.
Headers
كلمة Bearer ثم مسافة ثم مفتاح API الذي يبدأ بـ ek_. أنشئ المفاتيح في البوابة من المطورون، ثم مفاتيح واجهة برمجة التطبيقات.
معاملات المسار
معرّف الوكيل كما أعادته `GET /v1/agents`.
متن الطلب
application/json
رابط https عام. تُرفض العناوين الخاصة وعناوين loopback وlink-local، والروابط التي تحمل اسم مستخدم أو كلمة مرور.
اسم المصدر. اتركه فارغًا لاستخدام الرابط.
`single_url` يقرأ صفحة واحدة؛ و`website` يتبع الروابط منها.
للموقع: كم مستوى من الروابط يُتبع.
للموقع: أكبر عدد من الصفحات تُقرأ.
الاستجابة
200 application/json كل استجابة تستخدم هذا الغلاف.
النتيجة.
معرّف المجلد أو المصدر.
الاسم. المصدر من الويب يعرض المضيف والمسار فقط.
`folder` أو `file` أو `web`.
حالة فهرسة المصدر، و`null` للمجلد.
قيمته true عند نجاح الطلب.
يكرر رمز حالة HTTP.
قيمته null عند النجاح.
الأخطاء
الغلاف نفسه، مع success بقيمة false و data بقيمة null. كل الأخطاء
متى يحدث. قيمة `agentId` أو `sessionId` ليست معرّفًا سداسي عشريًا من 24 حرفًا.
الحل. استخدم المعرّف كما أعادته `GET /v1/agents` أو قائمة المحادثات تمامًا.
متى يحدث. قيمة `url` ليست رابط https، أو تشير إلى عنوان loopback أو خاص أو link-local.
الحل. أرسل رابط https عامًا.
متى يحدث. قيمة `url` أطول من 2000 حرف.
الحل. أرسل رابطًا أقصر.
متى يحدث. الرابط يحمل اسم مستخدم أو كلمة مرور.
الحل. أرسل الرابط بدونهما؛ لا يمكن قراءة الصفحات الخاصة.
متى يحدث. اسم مصدر المعرفة أطول من 200 حرف.
الحل. أرسل اسمًا أقصر.
متى يحدث. قيمة `type` أي قيمة أخرى.
الحل. أرسل `single_url` أو `website`، أو اتركه فارغًا لاستخدام `single_url`.
متى يحدث. قيمة `depth` أكبر من 3، أو أقل من 1 (تذكر الرسالة عندها الحد الأدنى).
الحل. أرسل عمقًا من 1 إلى 3.
متى يحدث. قيمة `maxUrls` أكبر من 50، أو أقل من 1 (تذكر الرسالة عندها الحد الأدنى).
الحل. أرسل `maxUrls` من 1 إلى 50.
متى يحدث. الجسم أو معلمات الاستعلام تحتوي على حقل لا تعرّفه نقطة النهاية.
الحل. احذف الحقل.
متى يحدث. header `Authorization` مفقود، أو قيمته لا تبدأ بـ `Bearer ek_...`، أو أن الرمز لا يطابق أي مفتاح، أو أن المفتاح محذوف أو معطّل أو منتهي الصلاحية، أو أن حسابه مغلق.
الحل. أرسل `Authorization: Bearer ek_...` بمفتاح API مفعّل.
متى يحدث. رصيد مساحة العمل لا يكفي لخصم هذا الطلب؛ لم يُنفَّذ شيء ولم يُخصم شيء.
الحل. أضف رصيدًا إلى مساحة العمل.
متى يحدث. مساحة العمل المالكة للمفتاح ليس لها اشتراك.
الحل. راجع خطة مساحة العمل في البوابة.
متى يحدث. حالة الاشتراك ليست نشطة أو تجريبية.
الحل. جدّد الاشتراك.
متى يحدث. المفتاح لا يملك النطاق `agents:write`.
الحل. عدّل المفتاح وامنحه النطاق `agents:write`، أو استخدم مفتاحًا آخر.
متى يحدث. العضو الذي أنشأ المفتاح غادر مساحة العمل، أو لم يعد يملك صلاحيتي إدارة الوكلاء وإدارة واجهة المطورين معًا. يُفحص ذلك في كل طلب.
الحل. امنح ذلك العضو الصلاحيتين من جديد، أو أنشئ المفتاح بعضو يملكهما.
متى يحدث. مساحة العمل مغلقة، لذلك لا يمكن فهرسة المعرفة.
الحل. تواصل مع الدعم لإعادة فتح مساحة العمل.
متى يحدث. انتهى الاشتراك ولم يبقَ أي رصيد مشترى، لذلك لا يمكن فهرسة المعرفة.
الحل. جدّد الاشتراك أو اشترِ رصيدًا.
متى يحدث. معرّف الوكيل غير معروف، أو الوكيل يتبع مساحة عمل أخرى.
الحل. استخدم معرّفًا من `GET /v1/agents` بمفتاح من مساحة عمل الوكيل.
متى يحدث. الوكيل مؤرشف. النسخ والأرشفة والاستعادة فقط تعمل على الوكيل المؤرشف.
الحل. استعده عبر `POST /v1/agents/{agentId}/restore`، أو انسخه وعدّل النسخة.
متى يحدث. جسم JSON لكتابة الوكيل أكبر من 512 كيلوبايت؛ يُرفض الطلب قبل فحص مفتاح الواجهة، لذلك لا يظهر له سجل في النشاط.
الحل. أرسل جسمًا أصغر، وقسّم النص الطويل في قاعدة المعرفة إلى عدة مصادر.
متى يحدث. للطلب جسم، وقيمة `Content-Type` فيه ليست `application/json`.
الحل. أرسل `Content-Type: application/json`.
متى يحدث. أرسل المفتاح أكثر من 20 طلبًا إلى نقطة النهاية هذه خلال 60 ثانية؛ وترويسة `Retry-After` تحمل عدد الثواني للانتظار.
الحل. انتظر عدد ثواني `Retry-After`، ثم أعد المحاولة.
متى يحدث. خطأ لم تصنّفه الواجهة.
الحل. راجع الطلب، ثم أعد المحاولة بعد انتظار قصير، وتواصل مع الدعم إن استمر الخطأ.
متى يحدث. انقطاع مؤقت داخل الواجهة.
الحل. أعد المحاولة بعد انتظار قصير.
متى يحدث. انتهاء مهلة مؤقت داخل الواجهة.
الحل. أعد المحاولة بعد انتظار قصير.
curl -X POST "https://api.echonova.ai/v1/agents/{agentId}/knowledge/web" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com/faq"}'{
"data": {
"id": "6653a1b2c3d4e5f6a7b8c9d0",
"name": "Price list",
"kind": "file",
"status": "ready"
},
"success": true,
"statusCode": 200,
"errorMessage": null
}