الانتقال إلى المحتوى الرئيسي
POST
تسجيل أداة

تسجيل أداة

POST /v1/tools يسجل أداة جديدة في سجل أدوات MAIP الخاص بالمستأجر. تمثل الأدوات قدرات خارجية (واجهات برمجة التطبيقات، الوظائف، الخدمات) يمكن لوكلاء الآلة استدعاؤها. ترتبط كل أداة بنطاق مطلوب ومستوى مخاطر وبوابة موافقة اختيارية. ترفع المنصة تلقائيًا مستوى المخاطر إلى "high" إذا كان اسم الأداة أو النطاق المطلوب يحتوي على أفعال خطيرة (كتابة، حذف، إرسال، تنفيذ، نشر، تدمير، إسقاط، اقتطاع).
يجب أن تكون أسماء الأدوات فريدة لكل مستأجر. محاولة تسجيل أداة باسم اسم موجود بالفعل يُرجع 409 Conflict.

المصادقة

يتطلب رأس X-API-Key أو رمز Bearer JWT. يتم اشتقاق مساحة العمل من بيانات الاعتماد الموثقة؛ لا ترسل X-Tenant-ID.

الاستجابة

string
معرف UUID للأداة المسجلة حديثًا.
string
معرف UUID للمستأجر المالك.
string
اسم الأداة القابل للقراءة آليًا.
string
اسم الأداة المقروء بشريًا.
string
وصف الأداة.
string
النطاق المطلوب للاستدعاء.
string
تصنيف المخاطر الفعال (قد يتم رفعه تلقائيًا).
boolean
ما إذا كانت الموافقة البشرية مطلوبة.
integer
حد المعدل لكل وكيل.
string
فئة الأداة.
string
حالة الأداة. دائمًا "active" عند الإنشاء.
object
بيانات تعريف الأداة.
string
طابع زمني لإنشاء ISO 8601.
string
طابع زمني لآخر تحديث ISO 8601.

مثال


الرفع التلقائي لمستوى المخاطر

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

التفويضات

X-API-Key
string
header
مطلوب

مفتاح API للمصادقة من جهاز إلى جهاز

الجسم

application/json
display_name
string
مطلوب
name
string
مطلوب

اسم أداة فريد

scope_required
string
مطلوب
category
string
description
string

وصف أداة مقروء بشريًا

metadata
any
rate_limit_per_minute
integer
requires_approval
boolean
risk_level
string

الاستجابة

الأداة مسجلة

tool_id
string<uuid>
name
string
description
string
schema
object
agent_id
string<uuid>
created_at
string<date-time>