Invocar Ferramenta
curl --request POST \
--url https://api.truthlocks.com/v1/tools/{toolName}/invoke \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"agent_id": "<string>"
}
'const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({agent_id: '<string>'})
};
fetch('https://api.truthlocks.com/v1/tools/{toolName}/invoke', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.truthlocks.com/v1/tools/{toolName}/invoke"
payload = { "agent_id": "<string>" }
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.truthlocks.com/v1/tools/{toolName}/invoke"
payload := strings.NewReader("{\n \"agent_id\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}{
"result": {},
"receipt_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"execution_ms": 123
}{
"code": "AUTH_REQUIRED",
"message": "Authentication required",
"http_status": 401
}{
"code": "AUTH_REQUIRED",
"message": "Authentication required",
"http_status": 401
}{
"code": "AUTH_REQUIRED",
"message": "Authentication required",
"http_status": 401
}{
"code": "AUTH_REQUIRED",
"message": "Authentication required",
"http_status": 401
}Sessões e Ferramentas do Agente
Invocar Ferramenta
Solicitar invocação de ferramenta com validação de âmbito, limitação de taxa e geração de recibo de auditoria
POST
/
v1
/
tools
/
{toolName}
/
invoke
Invocar Ferramenta
curl --request POST \
--url https://api.truthlocks.com/v1/tools/{toolName}/invoke \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"agent_id": "<string>"
}
'const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({agent_id: '<string>'})
};
fetch('https://api.truthlocks.com/v1/tools/{toolName}/invoke', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.truthlocks.com/v1/tools/{toolName}/invoke"
payload = { "agent_id": "<string>" }
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.truthlocks.com/v1/tools/{toolName}/invoke"
payload := strings.NewReader("{\n \"agent_id\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}{
"result": {},
"receipt_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"execution_ms": 123
}{
"code": "AUTH_REQUIRED",
"message": "Authentication required",
"http_status": 401
}{
"code": "AUTH_REQUIRED",
"message": "Authentication required",
"http_status": 401
}{
"code": "AUTH_REQUIRED",
"message": "Authentication required",
"http_status": 401
}{
"code": "AUTH_REQUIRED",
"message": "Authentication required",
"http_status": 401
}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:
- Status do agente — o agente deve estar
"active" - Verificação de escopo — o agente deve possuir o escopo exigido pela ferramenta
- Limite de taxa — o agente não deve exceder o limite de taxa por minuto da ferramenta
- 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
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çalhoX-API-Key ou token JWT de portador. O espaço de trabalho é derivado da credencial autenticada; não envie X-Tenant-ID.
Resposta
Explicação legível por humanos quando a invocação é negada ou pendente. Não
presente quando permitido.
Identificador de recibo único para a invocação, vinculando à trilha de auditoria. Apenas
presente quando
status é "allowed".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
curl -X POST https://api.truthlocks.com/v1/tools/search.web/invoke \
-H "X-API-Key: tl_live_..." \
-H "Content-Type: application/json" \
-d '{
"agent_id": "maip:t1234567:01HYX3KPZQ7RJGBN0WFMV8SDEH",
"session_id": "maip-sess:a1b2c3d4:9f8e7d6c5b4a3210"
}'
Fluxo de Controle de Acesso
POST /v1/tools/{name}/invoke
|
+-- Is agent active?
| No --> { allowed: false, status: "denied", reason: "agent is not active" }
|
+-- Does agent have required scope?
| No --> { allowed: false, status: "denied", reason: "agent lacks required scope: ..." }
|
+-- Is rate limit exceeded?
| Yes --> { allowed: false, status: "denied", reason: "rate limit exceeded" }
|
+-- Does tool require approval?
| Yes --> { allowed: false, status: "pending_approval", requires_approval: true }
|
+-- Create receipt + record invocation
--> { allowed: true, status: "allowed", receipt_id: "..." }
Padrão de integração
Após receber uma resposta"allowed", execute a ferramenta e, opcionalmente, registre o resultado:
# 1. Request invocation authorization
RESPONSE=$(curl -s -X POST https://api.truthlocks.com/v1/tools/search.web/invoke \
-H "X-API-Key: tl_live_..." \
-H "Content-Type: application/json" \
-d '{"agent_id": "maip:t1234567:01HYX3KPZQ7RJGBN0WFMV8SDEH"}')
ALLOWED=$(echo "$RESPONSE" | jq -r '.allowed')
RECEIPT_ID=$(echo "$RESPONSE" | jq -r '.receipt_id')
# 2. Execute the tool only if explicitly authorized
if [ "$ALLOWED" = "true" ]; then
RESULT=$(curl -s "https://serpapi.com/search?q=example&api_key=...")
echo "Tool executed. Receipt: $RECEIPT_ID"
fi

