Saltar para o conteúdo principal
POST
Registrar Ferramenta

Registrar Ferramenta

POST /v1/tools Regista uma nova ferramenta no registo de ferramentas MAIP do inquilino. As ferramentas representam capacidades externas (APIs, funções, serviços) que os agentes de máquina podem invocar. Cada ferramenta está associada a um âmbito obrigatório, nível de risco e porta de aprovação opcional. A plataforma eleva automaticamente o nível de risco para "high" se o nome da ferramenta ou o escopo necessário contiver verbos de ação perigosos (write, delete, send, execute, deploy, destroy, drop, truncate).
Os nomes das ferramentas devem ser únicos por locatário. A tentativa de registrar uma ferramenta com um nome que já existe retorna 409 Conflict.

Autenticação

Requer cabeçalho X-API-Key ou token JWT de portador. O espaço de trabalho é derivado da credencial autenticada; não envie X-Tenant-ID.

Resposta

string
UUID da ferramenta recém-registrada.
string
UUID do locatário proprietário.
string
Nome da ferramenta legível por máquina.
string
Nome da ferramenta legível por humanos.
string
Descrição da ferramenta.
string
Escopo necessário para invocação.
string
Classificação de risco efetiva (pode ser elevada automaticamente).
boolean
Se a aprovação humana é necessária.
integer
Limite de taxa por agente.
string
Categoria da ferramenta.
string
Status da ferramenta. Sempre "active" na criação.
object
Metadados da ferramenta.
string
Carimbo de data/hora de criação ISO 8601.
string
Carimbo de data/hora da última atualização ISO 8601.

Exemplo


Elevação Automática do Nível de Risco

A plataforma verifica nomes de ferramentas e requisitos de escopo em busca de verbos de ação perigosos. Se detectado, o nível de risco é automaticamente elevado: Ferramentas com nível de risco "critical" sempre exigem aprovação humana, independentemente da configuração requires_approval.

Autorizações

X-API-Key
string
header
obrigatório

Chave de API para autenticação máquina a máquina

Corpo

application/json
display_name
string
obrigatório
name
string
obrigatório

Nome da ferramenta exclusivo

scope_required
string
obrigatório
category
string
description
string

Descrição da ferramenta legível por humanos

metadata
any
rate_limit_per_minute
integer
requires_approval
boolean
risk_level
string

Resposta

Ferramenta registrada

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