Invocar herramienta
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
}Sesiones y Herramientas de Agente
Invocar herramienta
Solicitar invocación de herramienta con validación de alcance, limitación de velocidad y generación de recibo de auditoría
POST
/
v1
/
tools
/
{toolName}
/
invoke
Invocar herramienta
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 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:
- Estado del agente: el agente debe estar
"active" - Verificación de alcance: el agente debe tener el alcance requerido por la herramienta.
- Límite de velocidad — el agente no debe exceder el límite de velocidad por minuto de la herramienta
- 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
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 encabezadoX-API-Key o el token Bearer JWT. El espacio de trabajo se deriva de la credencial autenticada; no envíe X-Tenant-ID.
Respuesta
Si la invocación fue autorizada.
true si todas las comprobaciones de control de acceso
aprobado.Explicación legible por humanos cuando la invocación es denegada o está pendiente. No
presente cuando se permite.
Identificador de recibo único para la invocación, que enlaza con la pista de auditoría. Solo
presente cuando
status es "allowed".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
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"
}'
Flujo de control de acceso
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: "..." }
Patrón de integración
Después de recibir una respuesta"allowed", ejecute la herramienta y, opcionalmente, registre el 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

