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

استدعاء الأداة

POST /v1/tools/{toolName}/invoke يطلب استدعاء أداة مسجلة نيابة عن وكيل آلي. تقوم المنصة بإجراء فحص متعدد الطبقات للتحكم في الوصول قبل منح الوصول:
  1. حالة الوكيل — يجب أن يكون الوكيل "active"
  2. فحص النطاق — يجب أن يمتلك الوكيل النطاق المطلوب للأداة
  3. حد المعدل — يجب ألا يتجاوز الوكيل حد المعدل لكل دقيقة للأداة
  4. بوابة الموافقة — إذا كانت الأداة تتطلب موافقة، فإن الاستجابة هي pending_approval؛ المعالج الحالي لا ينشئ طلب موافقة
إذا اجتازت جميع الفحوصات، يتم تسجيل الاستدعاء. تستخدم إيصالات الأدوات الحالية علامة نظام بدلاً من التوقيع المشفر. وهي سجلات تدقيق، وليست أدلة موقعة يمكن التحقق منها بشكل مستقل.
تنفذ نقطة النهاية هذه قرار التحكم في الوصول وتسجل القرار. لا تقوم بتوكيل التنفيذ الفعلي للأداة. تطبيقك هو مسؤول عن استدعاء نقطة نهاية الأداة الأساسية بعد تلقي "allowed" الاستجابة.

المصادقة

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

الاستجابة

boolean
ما إذا كان الاستدعاء مصرحًا به. true إذا كانت جميع فحوصات التحكم في الوصول تم تمريره.
string
حالة الاستدعاء. أحد الخيارات التالية: "allowed"، "denied"، "pending_approval".
string
شرح مقروء بشريًا عندما يتم رفض الاستدعاء أو يكون معلقًا. ليس موجود عند السماح بذلك.
string
معرف إيصال فريد للاستدعاء، يربط بمسار التدقيق. فقط موجود عندما يكون status هو "allowed".
boolean
true عندما تتطلب الأداة موافقة بشرية. لا يتم وضع الاستدعاء تلقائيًا في قائمة الانتظار للموافقة. موجود فقط عندما يكون status هو "pending_approval".

مثال: استدعاء مسموح به


تدفق التحكم في الوصول

نمط التكامل

بعد تلقي استجابة "allowed"، قم بتنفيذ الأداة وسجل النتيجة اختياريًا:

التفويضات

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

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

معلمات المسار

toolName
string
مطلوب

اسم الأداة المسجل.

الجسم

application/json
agent_id
string
مطلوب
session_id
string<uuid>

جلسة نشطة للاستدعاء تحتها

الاستجابة

نتيجة استدعاء الأداة

result
object
receipt_id
string<uuid>
execution_ms
integer