الأدوات وموصّلات الأنظمة

واجهتان في اتجاهين#

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

مثلًا، يمكن لشركة خدمات توفير request.status للاستعلام عن طلب قائم، ثم إضافة request.create كأداة تعديل منفصلة. هذه الأسماء تخصّ موصّلك، ولا يفرض موكّل تسمية لسجلات أعمالك.

عرّف الأدوات المتاحة#

تقرأ عملية الاكتشاف GET /.well-known/agent-provider على عنوان الموصّل باستخدام بيانات اعتماده المحفوظة. يحدّد الوصف protocol_version وcontract_version وcapabilities وlanguages وtools. هذا مثال صالح لوصف أداة قراءة فقط.

{
  "protocol_version": "1",
  "contract_version": "2026-09-01",
  "capabilities": [
    "read"
  ],
  "languages": [
    "en",
    "ar"
  ],
  "tools": [
    {
      "name": "request.status",
      "mutating": false,
      "produces_evidence": [
        "entity",
        "value"
      ],
      "timeout_ms": 5000,
      "parameters": {
        "type": "object",
        "properties": {
          "reference": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100
          }
        },
        "required": [
          "reference"
        ],
        "additionalProperties": false
      }
    }
  ]
}

استقبل استدعاء أداة#

يرسل موكّل POST /tools/{tool_name} مع arguments وكائن context. يتضمّن السياق مساحة العمل والمحادثة ودورة المعالجة وهوية الطرف كما تؤكّدها القناة واللغة والمنطقة الزمنية والوقت. لا يجوز لمعلمات الأداة إعادة تعريف حقول السياق.

تتضمّن الترويسات Contract-Version وTrace-Id. ويحمل التعديل أيضًا Operation-Id وRequest-Fingerprint. تحقّق من المدخلات وفق مخطّط JSON المغلق المعلن قبل قراءة السجلات أو تعديلها. تتراوح timeout_ms المدعومة بين 1 و10000 مللي ثانية.

احتفظ بإيصال دائم للإجراء#

تعلن أداة التعديل mutating: true واسم action وإمكانية mutate ونوع action ضمن produces_evidence. ويحدّد وصفها receipt_retention_seconds أيضًا. احفظ هوية العملية وبصمة الطلب والنتيجة مع التغيير في سجل الأعمال.

يجب أن تؤدّي العملية والبصمة نفسيهما إلى النتيجة المسجّلة نفسها. اختلاف البصمة تعارض. وبعد استجابة غير مؤكّدة، تستطيع المنصة مراجعة الإيصال الأصلي بدل اعتبار المحاولة الجديدة طلب أعمال جديدًا.

أعِد أدلة يمكن أن يستند إليها الردّ#

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

تُصاغ الحقائق المحمية وتأكيدات الإجراءات من أدلة مصادر تم التحقّق منها. ويُفحص النص الحرّ قدر الإمكان وقد يحتوي على تأكيدات غير مدعومة.