> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# تفويض الوكيل

> الترخيص المستند إلى النطاق، وإدارة الجلسات، واستدعاء الأدوات لوكلاء الذكاء الاصطناعي.

# تفويض الوكيل

يعمل كل وكيل ذكاء اصطناعي في منصة Truthlocks بموجب نموذج ترخيص صارم. يجب تسجيل الوكلاء، وتعيين نطاقات لهم، وإنشاء جلسات محددة بوقت قبل أن يتمكنوا من اتخاذ أي إجراء.

## تدفق التفويض

```
Register Agent → Assign Scopes → Create Session → Execute Actions → Terminate Session
      │               │                │                │               │
      ▼               ▼                ▼                ▼               ▼
  agent_id        scope_ids       session_token    audit_logged      cleanup
```

> [!TIP]
>
> تحتوي جميع نقاط نهاية ترخيص الوكيل — النطاقات، والجلسات، والأدوات — على منصة اختبار واجهة برمجة تطبيقات تفاعلية. افتح أي نقطة نهاية في مرجع واجهة برمجة تطبيقات [جلسات وأدوات الوكيل](https://docs.truthlocks.com/ar/api-reference/machine-identity/sessions/create.md) وانقر على **إرسال** لتجربتها مقابل Sandbox.

## نموذج النطاق

تتبع النطاقات نمطًا هرميًا `resource:action`. عندما يطلب وكيل جلسة، يمكنه فقط طلب النطاقات التي تم تعيينها عند التسجيل.

### تحديد النطاقات المخصصة

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/scopes \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "name": "invoices:approve",
    "description": "Approve invoices up to configured threshold",
    "constraints": {
      "max_amount_cents": 500000,
      "require_dual_approval_above": 100000
    }
  }'
```

### النطاقات المضمنة

| النطاق | الوصف |
| - | - |
| `agents:read` | قائمة الوكلاء وفحصهم |
| `agents:write` | تسجيل وتحديث الوكلاء |
| `receipts:write` | إيصالات إجراءات السك |
| `attestations:read` | قراءة بيانات التصديق |
| `attestations:write` | إنشاء شهادات جديدة |
| `trust-scores:read` | قراءة بيانات درجة الثقة |
| `trust-scores:compute` | تشغيل إعادة حساب درجة الثقة |
| `delegations:offer` | تقديم تفويض عبر المستأجرين |
| `delegations:accept` | قبول عروض التفويض |
| `compliance:write` | إنشاء فحوصات الامتثال |
| `orchestrations:execute` | تنفيذ سير عمل متعدد الوكلاء |
| `datasets:attest` | إثبات مصدر مجموعة البيانات |
| `models:attest` | إثبات نسب النموذج |

## إدارة الجلسة

توفر الجلسات سياقات تنفيذ محددة بوقت مع انتهاء صلاحية تلقائي وقائمة IP مسموح بها اختيارية.

### إنشاء جلسة

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/agent-sessions \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "agent_id": "maip-agent:01JXXXX",
    "scopes": ["receipts:write", "attestations:read"],
    "ttl_seconds": 3600,
    "ip_allowlist": ["10.0.0.0/8"],
    "metadata": {
      "task": "process-quarterly-invoices",
      "initiated_by": "user:alice@corp.com"
    }
  }'
```

**الاستجابة:**

```json theme={null}
{
  "id": "maip-session:01JYYYY",
  "agent_id": "maip-agent:01JXXXX",
  "token": "mst_live_...",
  "scopes": ["receipts:write", "attestations:read"],
  "expires_at": "2026-04-06T13:00:00Z",
  "status": "active"
}
```

### دورة حياة الجلسة

| الحالة | الوصف |
| - | - |
| `active` | الجلسة صالحة وتقبل الطلبات |
| `expired` | انقضى TTL — تنظيف تلقائي |
| `terminated` | تم إنهاؤه صراحةً بواسطة المستخدم أو النظام |
| `suspended` | متوقف مؤقتًا بسبب اكتشاف الشذوذ |

### إنهاء جلسة

```bash theme={null}
curl -X DELETE https://api.truthlocks.com/v1/agent-sessions/maip-session:01JYYYY \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Task completed" }'
```

## تسجيل الأدوات واستدعاؤها

يمكن للوكلاء تسجيل الأدوات التي يكشفونها واستدعاء الأدوات المسجلة بواسطة وكلاء آخرين (وفقًا لفحوصات النطاق).

### تسجيل أداة

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/tools \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "agent_id": "maip-agent:01JXXXX",
    "name": "generate-invoice",
    "description": "Generate PDF invoice from order data",
    "input_schema": {
      "type": "object",
      "properties": {
        "order_id": { "type": "string" },
        "format": { "type": "string", "enum": ["pdf", "html"] }
      },
      "required": ["order_id"]
    }
  }'
```

### استدعاء أداة

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/tools/invoice-generator/invoke \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "session_id": "maip-session:01JYYYY",
    "input": { "order_id": "ord_123", "format": "pdf" }
  }'
```

كل استدعاء أداة هو:

1. **تم فحص النطاق** — يجب أن تحتوي الجلسة على النطاق المطلوب
2. **محدود المعدل** — حسب حصة استدعاء الأداة في خطتك
3. **مسجل في التدقيق** — يتم تسجيل المدخلات والمخرجات الكاملة في سجل التدقيق
4. **مفوتر** — يتم احتسابه ضمن استحقاقات الفواتير الخاصة بك

## أفضل ممارسات الأمان

> [!WARNING]
>
> لا تقم أبدًا بتضمين رموز الجلسة في التعليمات البرمجية من جانب العميل. تمنح رموز الجلسة النطاق الكامل للجلسة ويجب التعامل معها كأسرار.

1. **مبدأ الحد الأدنى من الامتيازات** — اطلب فقط النطاقات المطلوبة للمهمة الحالية
2. **جلسات قصيرة الأجل** — استخدم أقصر TTL عملي (الافتراضي: ساعة واحدة)
3. **قائمة IP المسموح بها** — تقييد الجلسات على نطاقات الشبكة المعروفة
4. **تدوير بيانات الاعتماد** — أعد إنشاء مفاتيح توقيع الوكيل بجدول زمني منتظم
5. **مراقبة درجات الثقة** — تعيين تنبيهات عندما تنخفض درجات الثقة عن الحدود الدنيا
6. **استخدم مفتاح الإيقاف الطارئ** — إلغاء الوكلاء المخترقين فورًا

## الخطوات التالية

> [card] [سياسات MAIP](https://docs.truthlocks.com/guides/maip-policies.md)
>
> قواعد التنفيذ في وقت التشغيل بناءً على درجات الثقة، والنطاقات، وعمق التفويض.

> [card] [درجات الثقة](https://docs.truthlocks.com/guides/trust-scores.md)
>
> تقييم مستمر للثقة السلوكية للوكلاء.

> [card] [تفويض عبر المستأجرين](https://docs.truthlocks.com/guides/cross-tenant-delegation.md)
>
> السماح للوكلاء بالعمل عبر الحدود التنظيمية.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.