وكلاء A2A

يعرض MCP الأدوات والموارد، بينما يتيح A2A تفويض العمل بين الوكلاء وتبادل الرسائل ومتابعة المهام ومخرجاتها. يحتفظ Powerduck بهما كبروتوكولين مستقلين في المواصفة المحلية نفسها.

الإنشاء والتصحيح

1. اختر طلب جديد → A2A. الإعداد الافتراضي 1.0 / JSON-RPC. يدعم الإصدار 1.0 أيضًا REST وgRPC لسطح المكتب؛ أما 0.3 فيدعم JSON-RPC فقط. لا يتم تحويل الإصدارات ضمنيًا.
2. حدّد نقطة النهاية والطريقة. اضغط إنشاء محتوى الطلب لمعاينة القالب، ثم استبدال محتوى الطلب لتطبيقه. الإلغاء أو تغيير الطريقة وحده يحفظ المسودة.
3. عدّل params في JSON-RPC، أو كائن الطلب مباشرة في REST/gRPC دون غلاف خارجي من jsonrpc وid وparams. اضبط بيانات الاعتماد في المصادقة والترويسات؛ تُضاف A2A-Version عند الإرسال.
4. افحص الرد كاملًا: قد يتضمن HTTP 200 حقل RPC باسم error. يحتوي result في JSON-RPC 1.0 على task أو message.
5. احفظ في المواصفة. يحتفظ x-a2a بالإعدادات والأمثلة والعقود. يستخدم JSON-RPC الطريقة في المحتوى، ويستخدم REST/gRPC الطريقة المحددة. معرّف الطلب مستقل عن معرّف الرسالة. لمتابعة المحادثة، احتفظ بمعرّفات السياق والمهمة التي يعيدها الخادم.

وسائل النقل

عنوان REST هو العنوان الأساسي مثل https://agent.example/rest. تحدد الطريقة فعل HTTP والمسار، وتُرمّز معرّفات المهام، وتتحول المرشحات وتقسيم الصفحات إلى معلمات استعلام. يشترك التصحيح والتوثيق في هذا التحويل.

يتطلب gRPC تطبيق سطح المكتب. استخدم https://host:port لاتصال TLS مع ثقة شهادات النظام، أو http://localhost:port للاختبار المحلي غير المشفر، دون مسار إضافي. تتحول الترويسات إلى بيانات وصفية. يُستخدم الواصف الرسمي lf.a2a.v1.A2AService وProtoJSON. تُرفض نصوص HTTP والوكلاء وإعدادات TLS المخصصة لهذا النقل.

بطاقة الوكيل وJWS

يجلب جلب بطاقة الوكيل العامة عادةً /.well-known/agent-card.json. راجع الإصدار والمهارات والقدرات والمصادقة قبل تطبيق إحدى الواجهات صراحةً. لا يغير الجلب نقطة النهاية ولا يعيد إرسال بيانات الاعتماد إلى مصدر آخر. لا يرسل الاكتشاف العام بيانات اعتماد ولا يتبع إعادة التوجيه، ويحد الرد إلى 1 MiB. يحتاج المتصفح إلى CORS.

افتح التحقق من توقيع JWS والصق JWKS عامًا حصلت عليه من قناة موثوقة. يتم التحقق محليًا ولا تُفتح روابط المفاتيح الموجودة في البطاقة. يشمل حقول A2A 1.0 القياسية فقط، ولا يشمل الحقول المخصصة. تتبع الصيغة المعيارية قواعد وجود حقول A2A وRFC 8785، مع الاحتفاظ بالسلاسل والمصفوفات الفارغة المطلوبة والقيم المنطقية الاختيارية الموجودة صراحةً. تُرفض التواقيع التي تحذف هذه القيم. لا يثبت نجاح التوقيع وحده هوية المؤسسة المالكة لمفتاح مجهول.

حفظ البطاقة يحفظ لقطة فقط وليس قرار الثقة. احذف البيانات الخاصة قبل المشاركة. للحصول على بطاقة محمية، استخدم طريقة extended-card مع المصادقة.

المهام والتدفق

استخدم SendStreamingMessage أو SubscribeToTask في 1.0، وmessage/stream أو tasks/resubscribe في 0.3. يمكن فحص أحداث SSE أو gRPC الأصلية والحالات والمخرجات. الإيقاف يغلق الاتصال المحلي فقط. للإلغاء البعيد، أرسل CancelTask أو tasks/cancel مع معرّف المهمة. لا يمكن إعادة تشغيل مهمة منتهية مباشرةً.

تعتمد قراءة المهام وقائمتها في 1.0 والبطاقات الموسعة وإعداد الإشعارات على قدرات الوكيل. لا يستضيف Powerduck مستقبلًا لإشعارات الدفع.

امتداد OpenAPI

x-a2a امتداد خاص بـ Powerduck، وليس بطاقة وكيل قياسية أو كلمة مفتاحية قياسية في OpenAPI. يعرّف المسار الموثق العملية، بينما يمثل endpoint العنوان الفعلي.

openapi: 3.2.0
info:
  title: A2A demo
  version: 1.0.0
paths:
  /agents/research/send:
    post:
      summary: SendMessage
      x-protocol: a2a
      x-a2a:
        version: '1.0'
        binding: JSONRPC
        endpoint: https://agent.example.com/rpc
        agentCardUrl: https://agent.example.com/.well-known/agent-card.json
        method: SendMessage
        requestSchema:
          type: object
          description: A2A SendMessage
        responseSchema:
          type: object
          description: JSON-RPC
        example:
          jsonrpc: '2.0'
          id: request-1
          method: SendMessage
          params:
            message:
              messageId: message-1
              role: ROLE_USER
              parts:
                - text: 12 30
      responses:
        '200':
          description: A2A result / error
          content:
            application/json:
              schema:
                type: object

تكون version إما 1.0 أو 0.3. تكون binding هي JSONRPC، ويضيف 1.0 الخيارين HTTP+JSON وGRPC. يحدد agentCardUrl عنوان الاكتشاف وagentCard لقطة اختيارية. يحتوي example على غلاف JSON-RPC أو كائن REST/gRPC. يصف requestSchema وresponseSchema عقودًا صريحة ولا يُستنتج العقد الكامل من رد واحد. يستخدم SSE النوع text/event-stream وitemSchema من OAS 3.2. يحتفظ التوثيق وCopy for LLM بالإعدادات؛ يعرض gRPC صيغة ProtoJSON، وتعرض وسائل HTTP أمثلة الشيفرة.

إنشاء خادم

افتح إنشاء خادم → تنزيل مشروع الخادم للحصول على مشروع Node.js 22+. نفّذ npm install، واضبط A2A_TOKEN على 32 محرفًا عشوائيًا على الأقل وHANDLER_URL، ثم npm start. يتلقى معالج HTTP الكائن {message, contextId} ويعيد Message يحتوي parts غير فارغ. لا تُصدّر بيانات الاعتماد الحالية.

يحد الخادم حجم البيانات والتزامن، ويفرض مهلة 60 ثانية وينظف الموارد عند الإغلاق. يفعّل SIGNING_JWK_FILE التوقيع، ويسمح CORS_ORIGINS بمصادر المتصفح المحددة. هذا محوّل عديم الحالة، وليس محرك مهام دائمة أو إرسال إشعارات. قبل النشر العام، اضبط العناوين العامة وTLS وحدود المعدل في الوكيل العكسي والمصادقة المناسبة لتعدد المستخدمين.

مثال محلي قابل للتشغيل

يتضمن مستودع React المجلد examples/a2a-demo لخدمة جمع الأعداد، دون مفتاح ذكاء اصطناعي أو خدمة خارجية. يتطلب Node.js 22+.

cd powerduck-react/examples/a2a-demo
npm ci
npm start
# في نافذة طرفية أخرى، داخل المجلد نفسه:
npm test

شغّل npm test من نافذة طرفية أخرى في المجلد نفسه. استورد openapi.json واستخدم Bearer Token بالقيمة powerduck-local-demo-token-0123456789. إرسال [12,30] يعيد Sum: 42 وبيانات منظمة تتضمن total: 42. عنوان JSON-RPC هو http://127.0.0.1:9999/rpc، وREST هو http://127.0.0.1:9999/rest، وgRPC هو http://127.0.0.1:9998. البطاقة في http://127.0.0.1:9999/.well-known/agent-card.json. المفتاح العام المحلي الموثوق موجود في .runtime/trusted-jwks.json ويتغير عند إعادة التشغيل.

تستخدم الاختبارات منافذ معزولة للتحقق من وسائل النقل الثلاث وSSE والردود المنظمة ورفض التلاعب والمصادقة وCORS. يستمع المثال محليًا فقط، ولا ينفذ مهام دائمة أو إشعارات دفع. لا تنشره للعامة باستخدام الرمز التجريبي. المصادر الافتراضية للمتصفح هي http://localhost:3000 وhttp://127.0.0.1:3000؛ اضبط غيرها عبر CORS_ORIGINS.

A2A 1.0 · A2A 0.3