Saltar al contenido principal
POST
Invocar herramienta

Invocar Herramienta

POST /v1/tools/{toolName}/invoke Solicita la invocación de una herramienta registrada en nombre de un agente de máquina. La plataforma realiza una verificación de control de acceso de múltiples capas antes de otorgar el acceso:
  1. Estado del agente: el agente debe estar "active"
  2. Verificación de alcance: el agente debe tener el alcance requerido por la herramienta.
  3. Límite de velocidad — el agente no debe exceder el límite de velocidad por minuto de la herramienta
  4. Puerta de aprobación — si la herramienta requiere aprobación, la respuesta es pending_approval; el controlador actual no crea una solicitud de aprobación
Si todas las comprobaciones pasan, la invocación se registra. Los recibos de herramientas actuales utilizan un marcador de sistema en lugar de una firma criptográfica. Son registros de auditoría, no pruebas firmadas verificables de forma independiente.
Este punto de conexión realiza la decisión de control de acceso y registra la decisión. No actúa como proxy de la ejecución real de la herramienta. Su aplicación es responsable de llamar al punto final subyacente de la herramienta después de recibir una respuesta "allowed".

Autenticación

Requiere el encabezado X-API-Key o el token Bearer JWT. El espacio de trabajo se deriva de la credencial autenticada; no envíe X-Tenant-ID.

Respuesta

boolean
Si la invocación fue autorizada. true si todas las comprobaciones de control de acceso aprobado.
string
Estado de invocación. Uno de: "allowed", "denied", "pending_approval".
string
Explicación legible por humanos cuando la invocación es denegada o está pendiente. No presente cuando se permite.
string
Identificador de recibo único para la invocación, que enlaza con la pista de auditoría. Solo presente cuando status es "allowed".
boolean
true cuando la herramienta requiere aprobación humana. La invocación no se pone automáticamente en cola para aprobación. Solo presente cuando status es "pending_approval".

Ejemplo: Invocación permitida


Flujo de control de acceso

Patrón de integración

Después de recibir una respuesta "allowed", ejecute la herramienta y, opcionalmente, registre el resultado:

Autorizaciones

X-API-Key
string
header
requerido

Clave API para autenticación máquina a máquina

Parámetros de ruta

toolName
string
requerido

Nombre de la herramienta registrada.

Cuerpo

application/json
agent_id
string
requerido
session_id
string<uuid>

Sesión activa para invocar bajo

Respuesta

Resultado de la invocación de la herramienta

result
object
receipt_id
string<uuid>
execution_ms
integer