Tool aufrufen
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
}Agentensitzungen & Tools
Tool aufrufen
Tool-Aufruf mit Bereichsvalidierung, Ratenbegrenzung und Generierung von Audit-Belegen anfordern
POST
/
v1
/
tools
/
{toolName}
/
invoke
Tool aufrufen
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
}Tool aufrufen
POST /v1/tools/{toolName}/invoke
Fordert den Aufruf eines registrierten Tools im Namen eines Maschinenagenten an. Die Plattform führt eine mehrschichtige Zugriffskontrollprüfung durch, bevor der Zugriff gewährt wird:
- Agentenstatus – Agent muss
"active"sein - Bereichsprüfung – Agent muss den erforderlichen Bereich des Tools besitzen
- Ratenbegrenzung – der Agent darf die Pro-Minute-Ratenbegrenzung des Tools nicht überschreiten
- Genehmigungsgate – wenn das Tool eine Genehmigung erfordert, lautet die Antwort
pending_approval; der aktuelle Handler erstellt keine Genehmigungsanfrage
Dieser Endpunkt führt die Zugriffskontrollentscheidung durch und zeichnet die Entscheidung auf. Er leitet die eigentliche Werkzeugausführung nicht weiter. Ihre Anwendung ist
verantwortlich für den Aufruf des zugrunde liegenden Endpunkts des Tools nach Erhalt einer
"allowed" Antwort.Authentifizierung
ErfordertX-API-Key Header oder Bearer JWT Token. Der Arbeitsbereich wird aus den authentifizierten Anmeldeinformationen abgeleitet; senden Sie X-Tenant-ID nicht.
Antwort
Menschenlesbare Erklärung, wenn der Aufruf abgelehnt oder ausstehend ist. Nicht
vorhanden, wenn erlaubt.
Eindeutiger Belegidentifikator für den Aufruf, der auf den Audit-Trail verweist. Nur
vorhanden, wenn
status "allowed" ist.true, wenn das Tool eine menschliche Genehmigung erfordert. Der Aufruf wird nicht automatisch zur Genehmigung in die Warteschlange gestellt.
Nur vorhanden, wenn status "pending_approval" ist.Beispiel: Erlaubter Aufruf
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"
}'
Zugriffssteuerungsfluss
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: "..." }
Integrationsmuster
Nach Erhalt einer"allowed"-Antwort führen Sie das Tool aus und zeichnen optional das Ergebnis auf:
# 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
Autorisierungen
Body
application/json

