https://api.echonova.aiالمطورون
واجهة الأدوات البرمجية
إنشاء أدوات Webhook وOpenAPI، وعرض الأسرار واتصالات المصادقة التي تستخدمها عبر واجهة v1 البرمجية، مع صلاحيات المفتاح، وقواعد بيانات الاعتماد والعناوين وإعادة المحاولة وحدود المعدل، ورابط لكل نقطة نهاية.
تتيح واجهة الأدوات البرمجية لخادمك إنشاء الأدوات التي يستدعيها وكلاؤك. الأداة إما Webhook يستدعي عنوان URL واحدًا، أو استيراد لمستند OpenAPI بعملية واحدة لكل نقطة نهاية. ويمكنك أيضًا عرض أدوات مساحة العمل، وعرض الأسرار واتصالات المصادقة التي تشير إليها الأداة. هي الأدوات نفسها التي تراها تحت الأدوات في البوابة. لإعطاء أداة لوكيل، استخدم إرفاق أدوات بالوكيل.
ما تحتاج إليه
- مفتاح API له الأدوات على وصول. راجع امنح المفتاح وصولًا إلى الأدوات.
- عنوان الواجهة الأساسي والـ header
Authorization: Bearer ek_...من المصادقة. - عضو في مساحة العمل أنشأ المفتاح، وما زال يملك الصلاحيات المذكورة أدناه.
امنح المفتاح وصولًا إلى الأدوات
لا يصل المفتاح إلى أي مسار للأدوات حتى تضبط صف الأدوات على وصول:
| الصف | النطاق | ما يحق للمفتاح فعله |
|---|---|---|
| الأدوات | tools:write |
عرض الأدوات والأسرار واتصالات المصادقة وقراءتها، وإنشاء أدوات Webhook وOpenAPI ومعاينتها. |
هذا النطاق مستقل بذاته. agents:write لا يمنحه، ولا يمنح أي وصول إلى الوكلاء. صفوف الكلام في المفتاح لا تمنحه أيضًا. المفتاح الذي لا يملك النطاق يتلقى 403 مع الرسالة This API key cannot manage tools..
يتصرف المفتاح باسم العضو الذي أنشأه، ويُجرى الفحص مع كل طلب. يحتاج ذلك العضو إلى صلاحية إدارة واجهة المطورين البرمجية، وأن يكون مالك مساحة العمل أو أن يملك صلاحية إدارة الأدوات. العضو الذي يغادر مساحة العمل، أو يفقد أيًا من هذين، يأخذ معه وصول المفتاح إلى الأدوات. عندها تقرأ الرسالة The member who created this API key cannot manage tools.. نصوص الأخطاء كلها في الأخطاء.
الأسرار بالمعرّف فقط
لا تقبل الأداة قيمة سر عبر الواجهة أبدًا. احفظ القيمة في الخزنة من البوابة، ثم أشِر إليها بمعرّفها:
- عرض الأسرار يعيد معرّف كل سر واسمه ووقت إنشائه، ولا يعيد قيمته أبدًا. أرسل المعرّف باسم
secretId. - عرض اتصالات المصادقة يعيد معرّف كل اتصال واسمه ونوعه ووقت إنشائه، ولا يعيد بيانات اعتماده أبدًا. أرسل المعرّف باسم
connectionIdأوauthConnectionId. - يوضع السر في معاملات header فقط.
معرّف غير موجود، أو يخص مساحة عمل أخرى، يُرفض بالرسالة Referenced secret not found أو Referenced credential not found.
ترفض الواجهة بيانات الاعتماد المكتوبة مباشرة
ترفض الواجهة القيمة الصريحة التي تبدو كبيانات اعتماد. يذكر الرفض الحقل، ولا يكرر قيمته أبدًا:
Parameter "Authorization" looks like a credential. Save it in the vault and send it as a secret header, or use an auth connection.معامل ثابت باسم يشبه بيانات الاعتماد، مثل Authorization أو token أو api key أو cookie.Parameter "X-Trace" has a value that looks like a credential. Save it in the vault and send it as a secret header, or use an auth connection.قيمة ثابتة تبدأ بـ Bearer أو Basic أو Token أو Digest، أو لها شكل JWT.URL query parameter "api_key" looks like a credential. Save it in the vault and send it as a secret header, or use an auth connection.مفتاح استعلام يشبه بيانات الاعتماد في عنوان Webhook أوbaseUrlOverride.baseUrlOverride has a query or fragment part that looks like a credential. Save it in the vault and send it as a secret header, or use an auth connection.مفتاح يشبه بيانات الاعتماد مخفي في الاستعلام أو الجزء الختامي (fragment) من العنوان.
اسم الحقل في كل نص هو الاسم الذي أرسلته. أصلحه بحفظ القيمة سرًا، ثم إرسال header سري بمعرّفه secretId، أو باستخدام اتصال مصادقة.
قواعد الروابط
يجب أن يحقق عنوان Webhook وbaseUrlOverride ورابط المستند ما يلي:
- يستخدم
https؛ - يشير إلى مضيف عام: تُرفض عناوين loopback والعناوين الخاصة وlink-local؛
- لا يحمل اسم مستخدم أو كلمة مرور.
يذكر الفشل الحقل، مثل webhook.target.url must be a public HTTPS URL (no loopback, private, or link-local addresses).
عند قراءة أداة، تُخفى من روابطها أي أسماء مستخدمين أو كلمات مرور، ويظهر [redacted] بدل قيمة أي معامل استعلام يشبه بيانات الاعتماد.
أعد محاولة الإنشاء بأمان
يقبل POST /v1/tools/webhook وPOST /v1/tools/openapi header اختياريًا باسم Idempotency-Key، فلا تنشئ إعادة المحاولة بعد ضياع الرد أداة ثانية. القواعد موضحة في أعد إرسال الطلبات بأمان. المعاينة لا تحتاج إليه، لأنها لا تحفظ شيئًا.
حدود المعدل والحجم
المفتاح محدود لكل نقطة نهاية، إضافةً إلى الحدود الواردة في حدود معدل الطلبات:
| نقطة النهاية | استدعاءات في الدقيقة لكل مفتاح |
|---|---|
POST /v1/tools/webhook |
20 |
POST /v1/tools/openapi |
5 |
POST /v1/tools/openapi/preview |
5 |
عند تجاوز الحد يفشل الاستدعاء بالرمز 429 وheader باسم Retry-After يحمل عدد الثواني للانتظار.
يمكن أن يصل جسم OpenAPI إلى 6 MB، ويصل المستند المضمّن إلى 5 MB. الجسم الأكبر يفشل بالرمز 413 والرسالة Request body is larger than 6 MB، قبل فحص المفتاح. أرسل المستند كـ url عام بدلًا من تضمينه. يستورد الاستيراد 2000 عملية كحد أقصى؛ أرسل includeOperations بالعمليات التي تحتاجها.
انتبه
المفتاح الذي يملك tools:write يستطيع إنشاء أداة ترسل سرًا محفوظًا إلى أي عنوان https عام. امنح الأدوات على وصول فقط للمفاتيح التي تثق بها في كل سر في خزنة مساحة العمل، وعطّل المفتاح أو احذفه عندما تتوقف عن استخدامه.
نقاط النهاية
كلها تحتاج إلى الأدوات على وصول.
- عرض الأدوات
- الحصول على أداة
- إنشاء أداة Webhook
- معاينة استيراد OpenAPI
- إنشاء أداة OpenAPI
- عرض الأسرار
- عرض اتصالات المصادقة
الأسئلة الشائعة
هل تستطيع الواجهة تعديل الأداة أو حذفها؟
لا. تنشئ الواجهة الأدوات وتقرؤها فقط. عدّل الأداة أو احذفها من البوابة.
هل تستطيع الواجهة حفظ سر؟
لا. تُدخَل قيم الأسرار وبيانات الاعتماد في خزنة البوابة فقط.
هل يرى المفتاح أدوات مساحات عمل أخرى؟
لا. يعمل المفتاح لمساحة العمل التي تملكه. معرّف أداة من مساحة عمل أخرى يعيد 404 مع Tool not found، تمامًا كما يفعل أي معرّف غير معروف.