6 قالب JSON جاهز للنسخ · A2A v1.0

أمثلة A2A Agent Card

تصفّح قوالب A2A v1.0 العملية، وافهم قرارات تصميمها، ثم كيّف أي مثال لوكيلك الخاص.

الاكتشاف العام للوكلاء

استخدم هذه الأمثلة لتشكيل JSON الذي يجلبه عميل A2A آخر قبل أن يقرر ما إذا كان بإمكان وكيلك إكمال مهمة ما.

التقديم إلى السوق

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

كتالوجات الوكلاء الداخلية

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

قوالب JSON

أمثلة Agent Card لوكلاء الدعم والحجز والتسوق والبرمجة والبحث وسير العمل.

تحقّق من قالب
تصفية

وكيل دعم العملاء

يتعامل مع أسئلة المنتجات، والاستعلام عن الطلبات، والإرجاعات، وتسليمات التصعيد.

لماذا صُمم بهذه الطريقة

  • بيانات اعتماد عميل OAuth 2.0 تحمي بيانات الطلبات: تعلن Agent Card عن رابط الرمز المميز والنطاق حتى يتمكن العملاء من المصادقة دون توثيق خارج النطاق.
  • كل من streaming وpushNotifications صحيحان لأن محادثات الدعم طويلة الأمد وتصل تحديثات الحل بشكل غير متزامن.
  • المهارة الوحيدة محصورة في حد مهمة واحد (تصنيف، حل، تصعيد) بدلاً من وصف غامض مثل "مساعدة العملاء"، حتى تتمكن أنظمة التوجيه من مطابقتها بدقة.
customer-support.json
{
  "name": "وكيل دعم العملاء",
  "description": "يجيب على أسئلة دعم العملاء، ويستعيد سياق الطلب، ويصعد المشكلات التي لم يتم حلها إلى فريق بشري.",
  "supportedInterfaces": [
    {
      "url": "https://api.example.com/a2a/customer-support",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    }
  ],
  "provider": {
    "organization": "شركة المثال",
    "url": "https://example.com"
  },
  "version": "1.0.0",
  "capabilities": {
    "streaming": true,
    "pushNotifications": true,
    "extendedAgentCard": false
  },
  "defaultInputModes": [
    "text/plain",
    "application/json"
  ],
  "defaultOutputModes": [
    "text/plain",
    "application/json"
  ],
  "skills": [
    {
      "id": "resolve-customer-support-request",
      "name": "حل طلب دعم العملاء",
      "description": "يصنف طلب دعم العملاء، ويجمع السياق المطلوب، ويقترح حلاً، ويصعد عندما تكون الثقة منخفضة.",
      "tags": [
        "support",
        "orders",
        "returns"
      ],
      "examples": [
        "ساعدني في إرجاع طلبي."
      ]
    }
  ],
  "securitySchemes": {
    "oauth2": {
      "oauth2SecurityScheme": {
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://api.example.com/a2a/customer-support/oauth/token",
            "scopes": {
              "agent.invoke": "Invoke agent skills"
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "oauth2": [
        "agent.invoke"
      ]
    }
  ]
}

وكيل الحجز

يجد فترات المواعيد المتاحة ويُعِد تأكيدات الحجز.

لماذا صُمم بهذه الطريقة

  • مفتاح API في رأس الطلب كافٍ هنا: الحجوزات محدودة النطاق حسب المستأجر لكنها لا تحمل مشكلة موافقة المستخدم المفوَّض التي يحلها OAuth.
  • defaultOutputModes هو application/json فقط، مما يشير إلى أن المستدعين يحصلون على مقترحات حجز منظمة بدلاً من النص النثري.
  • pushNotifications صحيح حتى يتمكن الوكيل من تأكيد الحجز بعد استقرار الخلفية التي تحتفظ بالفترة، دون أن يقوم العميل بالاستطلاع.
booking.json
{
  "name": "وكيل الحجز",
  "description": "البحث عن التوفر، واقتراح خيارات الحجز، وإعداد حجوزات المواعيد للموافقة عليها.",
  "supportedInterfaces": [
    {
      "url": "https://api.example.com/a2a/booking",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    }
  ],
  "provider": {
    "organization": "شركة المثال",
    "url": "https://example.com"
  },
  "version": "1.0.0",
  "capabilities": {
    "streaming": false,
    "pushNotifications": true,
    "extendedAgentCard": false
  },
  "defaultInputModes": [
    "text/plain",
    "application/json"
  ],
  "defaultOutputModes": [
    "application/json"
  ],
  "skills": [
    {
      "id": "find-and-prepare-booking",
      "name": "البحث عن الحجز وإعداده",
      "description": "التحقق من توفر الموارد ومقارنة نوافذ الحجز وإرجاع مقترح الحجز المنظم.",
      "tags": [
        "booking",
        "calendar",
        "availability"
      ],
      "examples": [
        "ابحث عن موعد مدته 30 دقيقة بعد ظهر الغد."
      ]
    }
  ],
  "securitySchemes": {
    "apiKey": {
      "apiKeySecurityScheme": {
        "location": "header",
        "name": "X-API-Key"
      }
    }
  },
  "security": [
    {
      "apiKey": []
    }
  ]
}

وكيل التسوق

يقارن المنتجات والتوافر والأسعار وقيود الشراء.

لماذا صُمم بهذه الطريقة

  • التوصيات المرتبة تُبث أثناء حسابها، لذا فإن streaming صحيح بينما تبقى pushNotifications خاطئة — لا يحدث شيء بعد اكتمال الاستجابة.
  • وصف المهارة يلتزم بإرجاع المقايضات والمبررات، مما يخبر أنظمة التنسيق أن هذا الوكيل يشرح الترتيبات بدلاً من مجرد سرد المنتجات.
  • نطاقات OAuth تتحكم في البيانات المتعلقة بالشراء؛ يمكن لعرض تسوق عام أن يُسقط الأمان تمامًا ويبقى Agent Card صالحة.
shopping.json
{
  "name": "وكيل التسوق",
  "description": "يقارن المنتجات مع قيود المستخدم ويعيد خيارات الشراء المصنفة مع المفاضلات.",
  "supportedInterfaces": [
    {
      "url": "https://api.example.com/a2a/shopping",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    }
  ],
  "provider": {
    "organization": "شركة المثال",
    "url": "https://example.com"
  },
  "version": "1.0.0",
  "capabilities": {
    "streaming": true,
    "pushNotifications": false,
    "extendedAgentCard": false
  },
  "defaultInputModes": [
    "text/plain",
    "application/json"
  ],
  "defaultOutputModes": [
    "application/json"
  ],
  "skills": [
    {
      "id": "compare-shopping-options",
      "name": "قارن خيارات التسوق",
      "description": "يقوم بتقييم المنتجات المرشحة، والتصفية حسب القيود، وإرجاع التوصيات المرتبة مع الأساس المنطقي.",
      "tags": [
        "shopping",
        "commerce",
        "recommendations"
      ],
      "examples": [
        "قارن بين أجهزة الكمبيوتر المحمولة خفيفة الوزن التي يقل سعرها عن 1200 دولار."
      ]
    }
  ],
  "securitySchemes": {
    "oauth2": {
      "oauth2SecurityScheme": {
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://api.example.com/a2a/shopping/oauth/token",
            "scopes": {
              "agent.invoke": "Invoke agent skills"
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "oauth2": [
        "agent.invoke"
      ]
    }
  ]
}

وكيل البرمجة

يراجع مهام الكود، ويقترح الرقع، ويشرح قرارات التنفيذ.

لماذا صُمم بهذه الطريقة

  • extendedAgentCard صحيح: تسرد Agent Card العامة مهارة عامة "تنفيذ تغيير في الكود"، بينما لا تُكشف المهارات الخاصة بالمستودع إلا للعملاء الموثّقين عبر GetExtendedAgentCard.
  • تم الإعلان عن كل من مخرجات text/plain وapplication/json لأن الوكيل يعيد شروحات قابلة للقراءة البشرية إلى جانب رقع قابلة للتطبيق آليًا.
  • البث المباشر مهم لحلقات التجميع والاختبار الطويلة؛ يرى العملاء تقدمًا وسيطًا بدلاً من استدعاء صامت لعدة دقائق.
coding.json
{
  "name": "وكيل البرمجة",
  "description": "يساعد في مهام هندسة البرمجيات من خلال تحليل التعليمات البرمجية واقتراح التغييرات وإرجاع ملاحظات التنفيذ.",
  "supportedInterfaces": [
    {
      "url": "https://api.example.com/a2a/coding",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    }
  ],
  "provider": {
    "organization": "شركة المثال",
    "url": "https://example.com"
  },
  "version": "1.0.0",
  "capabilities": {
    "streaming": true,
    "pushNotifications": true,
    "extendedAgentCard": true
  },
  "defaultInputModes": [
    "text/plain",
    "application/json"
  ],
  "defaultOutputModes": [
    "text/plain",
    "application/json"
  ],
  "skills": [
    {
      "id": "implement-code-change",
      "name": "تنفيذ تغيير التعليمات البرمجية",
      "description": "يقرأ طلب الترميز، ويفحص الملفات ذات الصلة، ويعيد مقترح التصحيح، ويلخص خطوات التحقق.",
      "tags": [
        "coding",
        "review",
        "patches"
      ],
      "examples": [
        "أضف ترقيم الصفحات إلى واجهة برمجة تطبيقات المستخدمين."
      ]
    }
  ],
  "securitySchemes": {
    "apiKey": {
      "apiKeySecurityScheme": {
        "location": "header",
        "name": "X-API-Key"
      }
    }
  },
  "security": [
    {
      "apiKey": []
    }
  ]
}

وكيل البحث

يجمع المصادر، ويستخرج الأدلة، ويعيد ملاحظات بحثية منظمة.

لماذا صُمم بهذه الطريقة

  • لا يوجد securitySchemes على الإطلاق: نقطة النهاية عامة عن قصد، وحذف الحقل هو الطريقة الصحيحة للتعبير عن ذلك — خريطة مخططات فارغة ستكون غامضة.
  • الإدخال هو text/plain فقط، لأن ملخصات البحث تبدأ من أسئلة باللغة الطبيعية؛ يصل المخرج المنظم كملاحظات application/json.
  • هذه هي Agent Card v1.0 الدنيا المفيدة: الهوية، واجهة واحدة، القدرات، الأنماط، ومهارة واحدة موسومة جيدًا.
research.json
{
  "name": "وكيل البحث",
  "description": "يجمع المواد المصدرية ويستخرج الأدلة وينتج ملاحظات بحثية منظمة مع الاستشهادات.",
  "supportedInterfaces": [
    {
      "url": "https://api.example.com/a2a/research",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    }
  ],
  "provider": {
    "organization": "شركة المثال",
    "url": "https://example.com"
  },
  "version": "1.0.0",
  "capabilities": {
    "streaming": true,
    "pushNotifications": false,
    "extendedAgentCard": false
  },
  "defaultInputModes": [
    "text/plain"
  ],
  "defaultOutputModes": [
    "text/plain",
    "application/json"
  ],
  "skills": [
    {
      "id": "prepare-research-brief",
      "name": "إعداد ملخص البحث",
      "description": "يبحث في المصادر المعتمدة، ويستخرج الادعاءات والأدلة، ويعيد ملخصًا بحثيًا موجزًا.",
      "tags": [
        "research",
        "evidence",
        "citations"
      ],
      "examples": [
        "قم بإعداد ملخص مقتبس عن سياسة الطاقة المتجددة."
      ]
    }
  ]
}

وكيل سير العمل الداخلي

ينسّق الموافقات، وفحوصات الحالة، وتحديثات سير عمل المكتب الخلفي.

لماذا صُمم بهذه الطريقة

  • application/json هو نمط الإدخال والإخراج الوحيد: يتم استدعاء هذا الوكيل من قبل أنظمة أخرى، وليس أبدًا من قبل أشخاص يكتبون نصًا نثريًا.
  • OAuth 2.0 بالإضافة إلى extendedAgentCard يناسب عمليات التدقيق المؤسسية — يمكن لفرق الأمان رؤية متطلبات المصادقة علنًا بينما تبقى مهارات سير العمل الحساسة خلف المصادقة.
  • pushNotifications ضروري لأن سلاسل الموافقة تستغرق ساعات أو أيامًا؛ تحل webhooks محل الاستطلاع لتغييرات الحالة.
internal-workflow.json
{
  "name": "وكيل سير العمل الداخلي",
  "description": "تنسيق الموافقات الداخلية، والتحقق من حالة النظام، وإعداد تحديثات سير العمل لفرق العمليات.",
  "supportedInterfaces": [
    {
      "url": "https://api.example.com/a2a/workflow",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    }
  ],
  "provider": {
    "organization": "شركة المثال",
    "url": "https://example.com"
  },
  "version": "1.0.0",
  "capabilities": {
    "streaming": false,
    "pushNotifications": true,
    "extendedAgentCard": true
  },
  "defaultInputModes": [
    "application/json"
  ],
  "defaultOutputModes": [
    "application/json"
  ],
  "skills": [
    {
      "id": "coordinate-internal-workflow",
      "name": "تنسيق سير العمل الداخلي",
      "description": "يتلقى نية سير العمل، ويتحقق من متطلبات السياسة، ويجمع الموافقات، ويبلغ عن الحالة النهائية.",
      "tags": [
        "workflow",
        "operations",
        "approval"
      ],
      "examples": [
        "طلب الموافقة لنشر تحديث الرواتب."
      ]
    }
  ],
  "securitySchemes": {
    "oauth2": {
      "oauth2SecurityScheme": {
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://api.example.com/a2a/workflow/oauth/token",
            "scopes": {
              "agent.invoke": "Invoke agent skills"
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "oauth2": [
        "agent.invoke"
      ]
    }
  ]
}

كيّف بثقة

كيفية تكييف مثال Agent Card

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

أقوى Agent Cards تشرح حد مهمة الوكيل بلغة واضحة وبيانات وصفية قابلة للقراءة الآلية. يجب أن يتمكن العميل من معرفة ما يستطيع الوكيل فعله، وما لا يستطيع فعله، وأي رابط يستدعيه، وما إذا كانت بيانات الاعتماد مطلوبة.

قبل النشر

استبدل كل رابط example.com برابط A2A المنشور فعليًا وموقع مزوّد الخدمة.

أعد كتابة اسم المهارة والوصف والوسوم (مطلوبة في v1.0) والأمثلة لتناسب حد المهمة الفعلي.

اضبط provider.organization وارفع version على المستوى الأعلى كلما تغير محتوى Agent Card.

احذف حقول المصادقة فقط عندما تكون نقطة النهاية عامة عمدًا.

حافظ على توافق defaultInputModes وdefaultOutputModes مع ما يقبله خادمك ويعيده فعليًا.

تحقّق من JSON النهائي وانشره على /.well-known/agent-card.json في نطاق خدمتك.

جاهز للبناء

ابدأ بمثال، ثم اجعله ملكك.

افتح أي نمط في مولّد Agent Card، وراجع JSON، وتحقق منه قبل النشر.