المطورون / الوكلاء
فصل أدوات عن وكيل
https://api.echonova.ai/v1/agents/{agentId}/tools/detachتفصل أدوات مساحة العمل عن الوكيل. المعرّفات غير المرفقة تُتجاهل. تبقى الأدوات في مساحة العمل. مجانًا. يحتاج المفتاح إلى النطاق `agents:write`، ويحتاج منشئ المفتاح أيضًا إلى صلاحية إدارة الأدوات.
Headers
كلمة Bearer ثم مسافة ثم مفتاح API الذي يبدأ بـ ek_. أنشئ المفاتيح في البوابة من المطورون، ثم مفاتيح واجهة برمجة التطبيقات.
معاملات المسار
معرّف الوكيل كما أعادته `GET /v1/agents`.
متن الطلب
application/json
معرّفات أدوات مساحة العمل، من 1 إلى 20، كما تعرضها `GET /v1/agents/{agentId}/tools`.
الاستجابة
200 application/json كل استجابة تستخدم هذا الغلاف.
النتيجة.
الأدوات المدمجة، وحالة تشغيل كل منها.
مفتاح الأداة المدمجة.
اسم الأداة.
هل يستطيع الوكيل استخدامها.
أدوات مساحة العمل المرفقة بالوكيل. لا تُعرض روابطها وبيانات اعتمادها أبدًا.
معرّف أداة مساحة العمل.
اسم الأداة.
نوع الأداة.
وظيفة الأداة، أو `null`.
قيمته true عند نجاح الطلب.
يكرر رمز حالة HTTP.
قيمته null عند النجاح.
الأخطاء
الغلاف نفسه، مع success بقيمة false و data بقيمة null. كل الأخطاء
متى يحدث. قيمة `agentId` أو `sessionId` ليست معرّفًا سداسي عشريًا من 24 حرفًا.
الحل. استخدم المعرّف كما أعادته `GET /v1/agents` أو قائمة المحادثات تمامًا.
متى يحدث. قيمة `toolIds` قائمة فارغة.
الحل. أرسل من 1 إلى 20 معرّف أداة.
متى يحدث. قائمة `toolIds` تحتوي على أكثر من 20 معرّفًا.
الحل. أرسل من 1 إلى 20 معرّف أداة في كل طلب.
متى يحدث. قيمة `toolId` ليست معرّفًا سداسي عشريًا من 24 حرفًا.
الحل. استخدم معرّفات أدوات مساحة العمل كما تعرضها البوابة أو `GET /v1/agents/{agentId}/tools` تمامًا.
متى يحدث. الجسم أو معلمات الاستعلام تحتوي على حقل لا تعرّفه نقطة النهاية.
الحل. احذف الحقل.
متى يحدث. 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`.
متى يحدث. أرسل المفتاح أكثر من 100 طلب إلى نقطة نهاية واحدة خلال 60 ثانية، أو أرسل عنوان IP واحد أكثر من 100 طلب إلى نقطة نهاية واحدة خلال 60 ثانية (يُحسب حد عنوان IP قبل فحص المفتاح، لذلك قد يردّ بلا مفتاح أصلًا)؛ وترويسة `Retry-After` تحمل عدد الثواني للانتظار.
الحل. انتظر عدد ثواني `Retry-After`، ثم أعد المحاولة.
متى يحدث. خطأ لم تصنّفه الواجهة.
الحل. راجع الطلب، ثم أعد المحاولة بعد انتظار قصير، وتواصل مع الدعم إن استمر الخطأ.
متى يحدث. انقطاع مؤقت داخل الواجهة.
الحل. أعد المحاولة بعد انتظار قصير.
متى يحدث. انتهاء مهلة مؤقت داخل الواجهة.
الحل. أعد المحاولة بعد انتظار قصير.
curl -X POST "https://api.echonova.ai/v1/agents/{agentId}/tools/detach" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"toolIds":["6654a1b2c3d4e5f6a7b8c9d0"]}'{
"data": {
"system": [
{
"key": "web_search",
"name": "Web search",
"enabled": true
}
],
"attached": [
{
"id": "6654a1b2c3d4e5f6a7b8c9d0",
"name": "CRM lookup",
"type": "webhook",
"description": "Looks up a customer by phone number."
}
]
},
"success": true,
"statusCode": 200,
"errorMessage": null
}