استدعاء أداة
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
}جلسات وأدوات الوكيل
استدعاء أداة
طلب استدعاء الأداة مع التحقق من النطاق، وتحديد المعدل، وإنشاء إيصال التدقيق
POST
/
v1
/
tools
/
{toolName}
/
invoke
استدعاء أداة
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
}استدعاء الأداة
POST /v1/tools/{toolName}/invoke
يطلب استدعاء أداة مسجلة نيابة عن وكيل آلي. تقوم المنصة بإجراء فحص متعدد الطبقات للتحكم في الوصول قبل منح الوصول:
- حالة الوكيل — يجب أن يكون الوكيل
"active" - فحص النطاق — يجب أن يمتلك الوكيل النطاق المطلوب للأداة
- حد المعدل — يجب ألا يتجاوز الوكيل حد المعدل لكل دقيقة للأداة
- بوابة الموافقة — إذا كانت الأداة تتطلب موافقة، فإن الاستجابة هي
pending_approval؛ المعالج الحالي لا ينشئ طلب موافقة
تنفذ نقطة النهاية هذه قرار التحكم في الوصول وتسجل القرار. لا تقوم بتوكيل التنفيذ الفعلي للأداة. تطبيقك هو
مسؤول عن استدعاء نقطة نهاية الأداة الأساسية بعد تلقي
"allowed" الاستجابة.المصادقة
يتطلب رأسX-API-Key أو رمز Bearer JWT. يتم اشتقاق مساحة العمل من بيانات الاعتماد الموثقة؛ لا ترسل X-Tenant-ID.
الاستجابة
true عندما تتطلب الأداة موافقة بشرية. لا يتم وضع الاستدعاء تلقائيًا في قائمة الانتظار للموافقة.
موجود فقط عندما يكون status هو "pending_approval".مثال: استدعاء مسموح به
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"
}'
تدفق التحكم في الوصول
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: "..." }
نمط التكامل
بعد تلقي استجابة"allowed"، قم بتنفيذ الأداة وسجل النتيجة اختياريًا:
# 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

