Saltar para o conteúdo principal
POST
Invocar Ferramenta

Invocar Ferramenta

POST /v1/tools/{toolName}/invoke Solicita a invocação de uma ferramenta registada em nome de um agente de máquina. A plataforma realiza uma verificação de controlo de acesso de várias camadas antes de conceder o acesso:
  1. Status do agente — o agente deve estar "active"
  2. Verificação de escopo — o agente deve possuir o escopo exigido pela ferramenta
  3. Limite de taxa — o agente não deve exceder o limite de taxa por minuto da ferramenta
  4. Porta de aprovação — se a ferramenta exigir aprovação, a resposta é pending_approval; o manipulador atual não cria uma solicitação de aprovação
Se todas as verificações forem aprovadas, a invocação é registrada. Os recibos de ferramentas atuais usam um marcador de sistema em vez de uma assinatura criptográfica. São registros de auditoria, não provas assinadas verificáveis independentemente.
Este endpoint executa a decisão de controle de acesso e registra a decisão. Ele não faz proxy da execução real da ferramenta. Sua aplicação é responsável por chamar o endpoint subjacente da ferramenta após receber um "allowed" resposta.

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

boolean
Se a invocação foi autorizada. true se todas as verificações de controle de acesso aprovado.
string
Status da invocação. Um de: "allowed", "denied", "pending_approval".
string
Explicação legível por humanos quando a invocação é negada ou pendente. Não presente quando permitido.
string
Identificador de recibo único para a invocação, vinculando à trilha de auditoria. Apenas presente quando status é "allowed".
boolean
true quando a ferramenta requer aprovação humana. A invocação não é automaticamente enfileirada para aprovação. Presente apenas quando status é "pending_approval".

Exemplo: Invocação Permitida


Fluxo de Controle de Acesso

Padrão de integração

Após receber uma resposta "allowed", execute a ferramenta e, opcionalmente, registre o resultado:

Autorizações

X-API-Key
string
header
obrigatório

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

Parâmetros de caminho

toolName
string
obrigatório

Nome da ferramenta registado.

Corpo

application/json
agent_id
string
obrigatório
session_id
string<uuid>

Sessão ativa para invocar sob

Resposta

Resultado da invocação da ferramenta

result
object
receipt_id
string<uuid>
execution_ms
integer