أداة اكتشاف · A2A v1.0

افحص روابط اكتشاف A2A Agent Card

تكتشف عملاء A2A الوكيل عبر جلب Agent Card بصيغة JSON من رابط well-known. اختبر كلا الاصطلاحين على نطاق حقيقي وشاهد بالضبط ما يستلمه العملاء.

يبني كلا رابطي الاكتشاف المحتملين من نفس النطاق الأساسي.

يجلب JSON المُعاد ويُبلغ عن رمز الحالة ونوع المحتوى.

يحلّل الاستجابة كـ JSON خاص بـ Agent Card عند الإمكان.

يشغّل فحوصات الجاهزية للواجهات والمهارات ومزوّد الخدمة والأنماط والقدرات وبيانات الأمان.

فحص نطاق وكيل عام

أدخل نطاقًا أساسيًا. تجلب الأداة كلا مساري الاكتشاف، وتحلّل JSON المُعاد، وتشغّل فحوصات جاهزية Agent Card.

كيف يعمل الاكتشاف

رابط well-known واحد يبدأ كل تكامل A2A.

قبل أن يتمكّن وكيل آخر من استدعاء خدمتك، يجلب أولاً Agent Card من رابط well-known (RFC 8615) على نطاقك، ويقيّم المهارات ومتطلبات الأمان، ثم يستدعي الواجهة المفضّلة. إذا كانت Agent Card مفقودة أو قديمة أو مخفية خلف إعادة توجيه، ينتهي التكامل قبل أن يبدأ.

هذا الموقع يطبّق ما يفحصه: تنشر AgentCard.net Agent Card الخاصة على كلا المسارين، والمثال على اليمين هو الوثيقة الفعلية.

عرض Agent Card الحية الخاصة بنا
agentcard.net discovery
GET /.well-known/agent-card.json HTTP/1.1
Host: www.agentcard.net

HTTP/1.1 200 OK
Content-Type: application/a2a+json

{
  "name": "AgentCard.net Toolkit",
  "version": "1.0.0",
  "supportedInterfaces": [
    { "url": "https://www.agentcard.net/api/agent-card",
      "protocolBinding": "HTTP+JSON",
      "protocolVersion": "1.0" }
  ],
  "skills": [
    { "id": "generate-agent-card", ... },
    { "id": "validate-agent-card", ... },
    { "id": "check-well-known-discovery", ... }
  ]
}

مسارات الاكتشاف

اصطلاحان، Agent Card واحدة.

فتح المدقق الكامل
معيار A2A v1.0

/.well-known/agent-card.json

رابط well-known المسجّل في مواصفة A2A v1.0. تجلب العملاء الجديدة هذا المسار أولاً؛ قدّمه بنوع محتوى application/a2a+json.

قديم (قبل v1.0)

/.well-known/agent.json

يُستخدم في تطبيقات A2A المبكرة وأمثلة codelab. لا تزال عملاء منشورة كثيرة تفحص هذا المسار فقط، لذا فإن تقديم نفس Agent Card هنا استراتيجية انتقال آمنة.

نمط النشر

اجعل اكتشاف Agent Card قويًا وموثوقًا.

نادرًا ما تكون إخفاقات الاكتشاف غريبة: إعادة توجيه، صفحة خطأ مخزّنة مؤقتًا، أو نشر مسار ونسيان الآخر. يحافظ روتين النشر هذا على تقديم كلا الاصطلاحين لنفس Agent Card المحدَّثة.

  1. 1

    النشر على المسار المعياري

    قدّم Agent Card المراجَعة على /.well-known/agent-card.json عبر HTTPS على نفس نطاق خدمة A2A، بنوع محتوى application/a2a+json.

  2. 2

    عكس المسار القديم

    أعد نفس الوثيقة من /.well-known/agent.json طالما لا تزال العملاء القديمة قيد التداول — تباين Agent Cards على المسارين يربك التوجيه.

  3. 3

    إبقاء Agent Card متزامنة

    متى تغيّرت نقاط النهاية أو المهارات أو القدرات أو المصادقة، حدّث Agent Card وارفع حقل version وأعد نشر المسارين معًا.

  4. 4

    إعادة الفحص بعد كل تغيير

    شغّل هذه الأداة بعد عمليات النشر أو تغييرات DNS أو ترحيلات البوابة أو تعديلات السوق. عادةً ما يعود الفشل إلى إعادة توجيه أو صفحات خطأ HTML أو مسار منسي.

الأسئلة الشائعة

أسئلة شائعة حول Well-known Agent JSON

ماذا تنشر، وأين تنشره، وكيف تُبقي عملاء كلا الاصطلاحين يعملان.

أي مسار well-known لـ Agent Card يجب أن أستخدم؟

تسجّل A2A v1.0 مسار /.well-known/agent-card.json كمسار الاكتشاف المعياري. يسبق المسار القديم /.well-known/agent.json إصدار v1.0 لكنه لا يزال مفحوصًا من قِبل عملاء منشورة كثيرة، لذا فإن نشر نفس Agent Card على المسارين هو الخيار العملي خلال فترة الانتقال.

هل يجب أن يُعيد المساران نفس JSON؟

نعم. إعادة نفس Agent Card العامة من كلا المسارين تحافظ على الاتساق للعملاء التي تدعم اصطلاحًا واحدًا فقط. الوثائق المتباينة تجعل الوكيل يبدو مختلفًا حسب المسار الذي يجلبه العميل.

بأي نوع محتوى يجب تقديم Agent Card؟

تسجّل المواصفة application/a2a+json لـ Agent Card. يُقبل application/json العادي على نطاق واسع عمليًا، لكن نوع المحتوى HTML علامة موثوقة على أن المسار يُعيد صفحة خطأ بدلاً من Agent Card.

هل يمكن لـ Agent Card العامة إخفاء قدرات خاصة؟

نعم. انشر في Agent Card العامة فقط البيانات الوصفية الآمنة للاكتشاف، واضبط capabilities.extendedAgentCard على true، واكشف عن المهارات الحساسة عبر عملية GetExtendedAgentCard الموثّقة.

لماذا تفشل فحوصات الاكتشاف بعد النشر؟

الأسباب الشائعة هي إعادة التوجيه إلى صفحة تسجيل دخول أو تسويقية، صفحات HTML 404 تُعاد برمز حالة 200، JSON قديم مخزَّن مؤقتًا في CDN، أو نشر أحد المسارين فقط. تُبلغ الأداة عن رمز الحالة ونوع المحتوى لكل مسار، فيصبح الفشل مرئيًا فورًا.

قبل النشر

تحقّق من Agent Card، ثم افحص الروابط.

مرّر JSON أولاً عبر المدقق الكامل، وانشره على كلا مساري well-known، وأكّد الاكتشاف بهذه الأداة.

فتح المدققإنشاء Agent Card