Zum Hauptinhalt springen
POST
Tool aufrufen

Tool aufrufen

POST /v1/tools/{toolName}/invoke Fordert den Aufruf eines registrierten Tools im Namen eines Maschinenagenten an. Die Plattform führt eine mehrschichtige Zugriffskontrollprüfung durch, bevor der Zugriff gewährt wird:
  1. Agentenstatus – Agent muss "active" sein
  2. Bereichsprüfung – Agent muss den erforderlichen Bereich des Tools besitzen
  3. Ratenbegrenzung – der Agent darf die Pro-Minute-Ratenbegrenzung des Tools nicht überschreiten
  4. Genehmigungsgate – wenn das Tool eine Genehmigung erfordert, lautet die Antwort pending_approval; der aktuelle Handler erstellt keine Genehmigungsanfrage
Wenn alle Prüfungen bestanden sind, wird der Aufruf aufgezeichnet. Aktuelle Tool-Belege verwenden einen Systemmarker anstelle einer kryptografischen Signatur. Es handelt sich um Audit-Datensätze, nicht um unabhängig verifizierbare signierte Nachweise.
Dieser Endpunkt führt die Zugriffskontrollentscheidung durch und zeichnet die Entscheidung auf. Er leitet die eigentliche Werkzeugausführung nicht weiter. Ihre Anwendung ist verantwortlich für den Aufruf des zugrunde liegenden Endpunkts des Tools nach Erhalt einer "allowed" Antwort.

Authentifizierung

Erfordert X-API-Key Header oder Bearer JWT Token. Der Arbeitsbereich wird aus den authentifizierten Anmeldeinformationen abgeleitet; senden Sie X-Tenant-ID nicht.

Antwort

boolean
Ob der Aufruf autorisiert wurde. true, wenn alle Zugriffskontrollprüfungen bestanden.
string
Aufrufstatus. Einer von: "allowed", "denied", "pending_approval".
string
Menschenlesbare Erklärung, wenn der Aufruf abgelehnt oder ausstehend ist. Nicht vorhanden, wenn erlaubt.
string
Eindeutiger Belegidentifikator für den Aufruf, der auf den Audit-Trail verweist. Nur vorhanden, wenn status "allowed" ist.
boolean
true, wenn das Tool eine menschliche Genehmigung erfordert. Der Aufruf wird nicht automatisch zur Genehmigung in die Warteschlange gestellt. Nur vorhanden, wenn status "pending_approval" ist.

Beispiel: Erlaubter Aufruf


Zugriffssteuerungsfluss

Integrationsmuster

Nach Erhalt einer "allowed"-Antwort führen Sie das Tool aus und zeichnen optional das Ergebnis auf:

Autorisierungen

X-API-Key
string
header
erforderlich

API-Schlüssel für die Maschine-zu-Maschine-Authentifizierung

Pfadparameter

toolName
string
erforderlich

Registrierter Tool-Name.

Body

application/json
agent_id
string
erforderlich
session_id
string<uuid>

Aktive Sitzung, unter der aufgerufen werden soll

Antwort

Ergebnis des Tool-Aufrufs

result
object
receipt_id
string<uuid>
execution_ms
integer