مدقق A2A Agent Card

يفحص مدقق Agent Card JSON الملصق، وملفات Agent Card المرفوعة، وروابط الوكلاء العامة مقابل متطلبات اكتشاف A2A v1.0.

استخدم أداة التحقق من Agent Card

الصق JSON، أو عنوان URL للوكيل العام، أو اسحب ملف JSON إلى المحرر.

نطاق تغطية مدقق Agent Card

ما الذي يفحصه مدقق Agent Card قبل أن يكتشف العملاء وكيلك.

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

الصق مستند JSON محلي أثناء التطوير، أو ارفع Agent Card من مستودعك، أو استخدم التحقق المباشر من الرابط مقابل نطاق منشور للتحقق من مسارات الاكتشاف العامة.

توافق المخطط (A2A v1.0)

يتحقق من الحقول المطلوبة مقابل مواصفة v1.0: name، description، version، supportedInterfaces مع protocolBinding وprotocolVersion لكل واجهة، capabilities، أنماط المحتوى، ومهارة واحدة على الأقل بوسوم مطلوبة.

المشكلات الدلالية ومشكلات الترحيل

يكتشف البنى السابقة لـ v1.0 — url على المستوى الأعلى، وpreferredTransport، وprotocolVersion، وprovider.name، وstateTransitionHistory — ويخبرك بالضبط أين انتقل كل حقل في v1.0.

فحص الأمان والأسرار

يتحقق من إعلان securitySchemes ومتطلبات الأمان لنقاط النهاية غير العامة، ويعلّم الروابط غير HTTPS، ويفحص القيم التي تبدو مثل مفاتيح API أو JWT أو رموز bearer المضمّنة.

جاهزية الاكتشاف

يجلب /.well-known/agent-card.json والمسار القديم /.well-known/agent.json من نطاق حقيقي ويؤكد أن كليهما يعيدان JSON قابلاً للتحليل خاصًا بـ Agent Card.

أين يندرج التحقق

تحقّق في كل مرحلة: المحرر، خط أنابيب CI، النطاق الفعلي.

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

أبسط حارس CI لا يحتاج إلى أكثر من curl: تأكد من أن مسار well-known يستجيب بـ JSON قابل للتحليل قبل أن تنتقل حركة المرور إلى نشر جديد.

# deploy pipeline: fail if the published card breaks

curl -fsS https://your-domain/.well-known/agent-card.json \
  | python3 -c '
import json, sys
card = json.load(sys.stdin)
assert card.get("name"), "name is required"
assert card.get("supportedInterfaces"), "supportedInterfaces missing"
assert card.get("skills"), "skills missing"
print("agent card OK:", card["name"])'

دليل الإصلاح

إصلاحات Agent Card الشائعة

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

استبدل روابط نقطة النهاية النائبة برابط خدمة A2A المنشورة عبر HTTPS.

انقل url وpreferredTransport على المستوى الأعلى إلى مصفوفة supportedInterfaces مرتبة — الإدخال الأول هو الواجهة المفضلة.

أضف حقل version المطلوب على المستوى الأعلى الذي يصف الوكيل نفسه، وأضف وسومًا لكل مهارة.

أعد تسمية provider.name إلى provider.organization ووسّع الأوصاف القصيرة حتى يعرف العملاء متى يستدعون الوكيل.

أعلن عن بيانات وصفية أمنية كلما لم تكن نقطة نهاية الوكيل عامة بالكامل — ولا تُضمّن بيانات الاعتماد نفسها أبدًا.

انشر نفس Agent Card الصالحة على /.well-known/agent-card.json (وعلى مسار agent.json القديم طالما لا يزال العملاء يتحققون من كليهما).

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

أسئلة حول مدقق Agent Card

اضبط الأساسيات قبل أن يصل وكيلك إلى عميل A2A.

قارن أمثلة صالحة

أي إصدار من A2A يستهدفه المدقق؟

تتبع الفحوصات بنية Agent Card الخاصة بـ A2A v1.0 — supportedInterfaces، وإصدارات البروتوكول لكل واجهة، ووسوم المهارات المطلوبة، وprovider.organization. لا تُرفض Agent Cards السابقة لـ v1.0 مباشرة: تظهر الحقول القديمة كتحذيرات مع البديل الدقيق في v1.0.

لماذا يتحقق من كلا رابطي well-known؟

تسجّل مواصفة v1.0 مسار /.well-known/agent-card.json، لكن تطبيقات A2A السابقة استخدمت /.well-known/agent.json. يكتشف التحقق من كليهما فجوات الاكتشاف قبل أن يفشل العملاء.

هل يمكن تجاهل التحذيرات؟

التحذيرات لا تحجب مثل أخطاء JSON، لكنها عادةً ما تشير إلى بيانات وصفية تجعل الوكيل أسهل في الاكتشاف والثقة والاستدعاء — أو إلى حقول سابقة لـ v1.0 سيتوقف العملاء الأحدث عن قراءتها.

متى يجب تشغيل التحقق؟

ثلاث لحظات: أثناء تحرير Agent Card خلال التطوير، وكبوابة CI قبل النشر، وبعد النشر — الصق رابط الخدمة الفعلي لتأكيد ما يستلمه العملاء فعليًا من كلا مساري الاكتشاف.

جاهز للتحقق

تحقّق من Agent Card الخاصة بك قبل أن يكتشفها العملاء.

الصق JSON، أو أسقط ملف Agent Card، أو تحقق من رابط عام من مساحة عمل المدقق الموحدة.

افتح مدقق Agent Card أنشئ Agent Card