Saltar al contenido principal
POST
Registrar herramienta

Registrar Herramienta

POST /v1/tools Registra una nueva herramienta en el registro de herramientas MAIP del inquilino. Las herramientas representan capacidades externas (APIs, funciones, servicios) que los agentes de máquina pueden invocar. Cada herramienta está asociada con un alcance requerido, nivel de riesgo y una puerta de aprobación opcional. La plataforma eleva automáticamente el nivel de riesgo a "high" si el nombre de la herramienta o el alcance requerido contiene verbos de acción peligrosos (escribir, eliminar, enviar, ejecutar, desplegar, destruir, soltar, truncar).
Los nombres de las herramientas deben ser únicos por inquilino. Intentar registrar una herramienta con un que ya existe devuelve 409 Conflict.

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

string
UUID de la herramienta recién registrada.
string
UUID del inquilino propietario.
string
Nombre de la herramienta legible por máquina.
string
Nombre de la herramienta legible por humanos.
string
Descripción de la herramienta.
string
Alcance requerido para la invocación.
string
Clasificación de riesgo efectiva (puede ser elevada automáticamente).
boolean
Si se requiere aprobación humana.
integer
Límite de tasa por agente.
string
Categoría de herramienta.
string
Estado de la herramienta. Siempre "active" en la creación.
object
Metadatos de la herramienta.
string
Marca de tiempo de creación ISO 8601.
string
Marca de tiempo de última actualización ISO 8601.

Ejemplo


Elevación automática del nivel de riesgo

La plataforma escanea los nombres de las herramientas y los requisitos de alcance en busca de verbos de acción peligrosos. Si se detectan, el nivel de riesgo se eleva automáticamente: Las herramientas con nivel de riesgo "critical" siempre requieren aprobación humana, independientemente de la configuración de requires_approval.

Autorizaciones

X-API-Key
string
header
requerido

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

Cuerpo

application/json
display_name
string
requerido
name
string
requerido

Nombre de herramienta único

scope_required
string
requerido
category
string
description
string

Descripción de la herramienta legible por humanos

metadata
any
rate_limit_per_minute
integer
requires_approval
boolean
risk_level
string

Respuesta

Herramienta registrada

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