Invoquer l'outil
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
}Sessions et outils d'agent
Invoquer l'outil
Demander l’invocation d’un outil avec validation de portée, limitation de débit et génération de reçu d’audit
POST
/
v1
/
tools
/
{toolName}
/
invoke
Invoquer l'outil
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
}Invoquer l’outil
POST /v1/tools/{toolName}/invoke
Demande l’invocation d’un outil enregistré au nom d’un agent machine. La plateforme effectue un contrôle d’accès multicouche avant d’accorder l’accès :
- Statut de l’agent — l’agent doit être
"active" - Vérification de la portée — l’agent doit détenir la portée requise par l’outil
- Limite de débit — l’agent ne doit pas dépasser la limite de débit par minute de l’outil
- Porte d’approbation — si l’outil nécessite une approbation, la réponse est
pending_approval; le gestionnaire actuel ne crée pas de demande d’approbation
Ce point de terminaison effectue la décision de contrôle d’accès et enregistre la décision. Il ne proxy pas l’exécution réelle de l’outil. Votre application est
responsable d’appeler le point de terminaison sous-jacent de l’outil après avoir reçu un
"allowed" réponse.Authentification
Nécessite l’en-têteX-API-Key ou un jeton JWT Bearer. L’espace de travail est dérivé de l’identifiant authentifié ; n’envoyez pas X-Tenant-ID.
Réponse
Explication lisible par l’homme lorsque l’invocation est refusée ou en attente. Non
présent lorsque autorisé.
Identifiant de reçu unique pour l’invocation, lié à la piste d’audit. Uniquement
présent lorsque
status est "allowed".true lorsque l’outil nécessite une approbation humaine. L’invocation n’est pas automatiquement mise en file d’attente pour approbation.
Présent uniquement lorsque status est "pending_approval".Exemple : Invocation autorisée
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"
}'
Flux de contrôle d’accès
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: "..." }
Modèle d’intégration
Après avoir reçu une réponse"allowed", exécutez l’outil et enregistrez éventuellement le résultat :
# 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

