مرجع المخطط · 14 fieldsA2A v1.0
Agent Card هي المستند JSON الموحّد الذي يخبر عملاء A2A من هو الوكيل، وأين يمكن الوصول إليه، وماذا يستطيع أن يفعل، وكيف يُحمى الوصول إليه. يغطي هذا المرجع كل حقل من حقول v1.0 مع الأنواع والمتطلبات والأمثلة والأخطاء التي تكتشفها أدوات التحقق في أغلب الأحيان.
كيف يعمل الاكتشاف
يجلب عميل A2A Agent Card من رابط well-known، ويقيّم المهارات والقدرات ومتطلبات الأمان مقابل مهمته، ثم يستدعي الواجهة المفضّلة — أول إدخال في supportedInterfaces. إذا كانت capabilities.extendedAgentCard صحيحة، يمكن للعملاء الموثّقين طلب Agent Card أكثر ثراءً عبر عملية GetExtendedAgentCard.
تسجّل المواصفة /.well-known/agent-card.json كموقع معياري. استخدمت عمليات النشر القديمة لـ v0.x المسار /.well-known/agent.json، وهذا سبب فحص أداة التحقق لدينا لكليهما.
# Fetch a public Agent Card
GET /.well-known/agent-card.json HTTP/1.1
Host: agent.example.com
HTTP/1.1 200 OK
Content-Type: application/a2a+json
{
"name": "GeoSpatial Route Planner Agent",
"supportedInterfaces": [
{ "url": "https://georoute-agent.example.com/a2a/v1",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0" }
],
...
}مرجع الحقول
تتبع علامات الإلزامية تعريفات protobuf لإصدار v1.0 في المواصفة الرسمية. تجعل روابط الإرساء كل حقل قابلاً للاستشهاد من التذاكر والمراجعات ومخرجات CI.
اسم الوكيل القابل للقراءة من قبل البشر.
يظهر في قوائم الأسواق وواجهات العملاء. اجعله قصيرًا ومحددًا — يستخدمه العملاء كتسمية أساسية عند مقارنة الوكلاء المرشحين.
خطأ شائع: استخدام اسم عام مثل "AI Assistant" لا يمنح أنظمة التوجيه أي أساس للتمييز.
"name": "وكيل مخطط الطريق الجغرافي المكاني"
ما يفعله الوكيل ومتى ينبغي لوكيل آخر استدعاءه.
هذه هي الإشارة النصية الحرة الرئيسية لكل من المكاملين البشريين والموجّهات القائمة على LLM التي تقرر ما إذا كان وكيلك مناسبًا لمهمة ما. اذكر مجال المهمة والقدرات الأساسية والحدود.
خطأ شائع: أوصاف من سطر واحد أقل من 20 حرفًا. لا يمكن للموجّهات مطابقة ما لا تصفه.
"description": "يوفر تخطيطًا متقدمًا للطريق، وتحليل حركة المرور، وخدمات إنشاء الخرائط المخصصة."
قائمة مرتبة من نقاط النهاية وربط البروتوكولات. الإدخال الأول هو المفضّل.
جديد في v1.0: يحل محل حقول المستوى الأعلى القديمة url وpreferredTransport وadditionalInterfaces. يعلن كل إدخال عن url خاص به، وprotocolBinding (JSONRPC أو GRPC أو HTTP+JSON أو URI ربط مخصص)، وprotocolVersion، ومفتاح توجيه مستأجر اختياري — بحيث يمكن لوكيل واحد خدمة إصدارات بروتوكول ووسائل نقل متعددة في وقت واحد.
خطأ شائع: الإعلان عن ربط لا يخدمه الخادم فعليًا على ذلك الرابط — تتطلب المواصفة أن يكون كل إدخال دقيقًا.
"supportedInterfaces": [
{ "url": "https://api.example.com/a2a/v1",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0" }
]من يشغّل الوكيل: المنظمة والموقع الإلكتروني.
إشارة ثقة للأسواق والتدقيقات المؤسسية. أعادت v1.0 تسمية حقل name إلى organization؛ يكون url إلزاميًا داخل الكائن عند وجوده.
خطأ شائع: استمرار استخدام provider.name (قبل v1.0). أدوات التحقق التي تقرأ Agent Cards v1.0 لن تتعرف عليه.
"provider": {
"organization": "شركة مثال للخدمات الجغرافية",
"url": "https://www.examplegeoservices.com"
}إصدار الوكيل نفسه، وليس إصدار البروتوكول.
يسمح للعملاء باكتشاف متى تغيّرت Agent Card تغييرًا جوهريًا وإعادة تقييم التوافق. اتبع مخطط الإصدار الخاص بك، عادةً semver.
خطأ شائع: الخلط بين هذا وإصدار بروتوكول A2A — الذي يقيم الآن في كل إدخال من supportedInterfaces.
"version": "1.2.0"
رابط إلى وثائق قابلة للقراءة من قبل البشر للوكيل.
يمنح المكاملين مكانًا لقراءة عقد API الكامل وحدود المعدل والشروط التي لا تنتمي إلى مستند اكتشاف.
خطأ شائع: الإشارة إلى صفحة رئيسية تسويقية بدلاً من وثائق تقنية.
"documentationUrl": "https://docs.example.com/agent"
أعلام ميزات البروتوكول: streaming وpushNotifications وextensions وextendedAgentCard.
يجب على العملاء عدم استدعاء ميزات لم تُعلن عنها — استدعاءات البث غير المعلنة تُعيد أخطاء. extendedAgentCard: true يعلن عن Agent Card موثّقة أكثر ثراءً عبر عملية GetExtendedAgentCard. أزالت v1.0 حقل stateTransitionHistory.
خطأ شائع: الإعلان عن streaming: true عندما لا يملك الخادم نقطة نهاية بث. سيستدعيها العملاء وتفشل.
"capabilities": {
"streaming": true,
"pushNotifications": true,
"extendedAgentCard": false
}مخططات مصادقة مسمّاة: مفتاح API، مصادقة HTTP، OAuth 2.0، OpenID Connect، أو TLS المتبادل.
كل مخطط مسمّى يغلّف كائن مخطط محدد واحد (apiKeySecurityScheme، httpAuthSecurityScheme، oauth2SecurityScheme، openIdConnectSecurityScheme، mtlsSecurityScheme). يكتشف العملاء من هنا كيفية المصادقة — يتم دائمًا الحصول على بيانات الاعتماد نفسها خارج النطاق.
خطأ شائع: تضمين مفتاح API أو رمز فعلي في Agent Card. Agent Card مستند عام.
"securitySchemes": {
"google": {
"openIdConnectSecurityScheme": {
"openIdConnectUrl": "https://accounts.google.com/.well-known/openid-configuration"
}
}
}أي المخططات المعلنة (والنطاقات) مطلوبة لاستدعاء الوكيل.
يربط كل إدخال اسم مخطط من securitySchemes بالنطاقات التي يحتاجها، مما يعكس نمط متطلبات الأمان في OpenAPI. احذف كلا الحقلين تمامًا للوكلاء العامين عمدًا.
خطأ شائع: الإعلان عن securitySchemes دون متطلبات security، تاركًا العملاء يخمنون ما إذا كانت المصادقة مفروضة.
"security": [{ "google": ["openid", "profile", "email"] }]أنواع الوسائط التي يقبلها الوكيل عبر جميع المهارات.
أنواع MIME القياسية مثل text/plain وapplication/json أو image/png. يمكن للمهارات الفردية تجاوز ذلك باستخدام inputModes الخاصة بها.
خطأ شائع: حذف الحقل. إنه إلزامي في v1.0 — يحتاجه العملاء لتشكيل الطلبات.
"defaultInputModes": ["application/json", "text/plain"]
أنواع الوسائط التي يعيدها الوكيل عبر جميع المهارات.
يخبر المستدعين بما إذا كان يجب توقع نص أو JSON منظّم أو صور أو ملفات. يمكن للمهارات التجاوز لكل مهارة باستخدام outputModes.
خطأ شائع: إدراج text/plain فقط بينما يعيد الوكيل فعليًا نتائج منظّمة.
"defaultOutputModes": ["application/json", "image/png"]
القدرات الملموسة التي من المرجح أن ينجح الوكيل فيها.
تتطلب كل مهارة id وname وdescription وtags؛ أما examples وأنماط لكل مهارة وأمان لكل مهارة فهي اختيارية. المهارات هي وحدة الاكتشاف — تطابق الموجّهات المهام معها، لذا حدد نطاق كل واحدة إلى حد مهمة واحد.
خطأ شائع: مهارات بدون وسوم. أصبحت الوسوم إلزامية في v1.0 وتقود المطابقة على مستوى المهارة.
"skills": [{
"id": "route-optimizer-traffic",
"name": "مُحسِّن الطريق لحركة المرور",
"description": "يحسب مسارات القيادة المثلى باستخدام حركة المرور في الوقت الحقيقي...",
"tags": ["maps", "routing", "traffic"],
"examples": ["خطط طريقًا من النقطة A إلى النقطة B مع تجنب رسوم المرور."]
}]توقيعات JSON Web تثبت أن Agent Card صادرة عن مزوّد الخدمة.
يحمل كل توقيع رأس JWS محميًا بترميز base64url وقيمة توقيع، محسوبة على Agent Card المُقيّسة وفق RFC 8785 (JCS). ينبغي للعملاء التحقق من توقيع واحد على الأقل قبل الوثوق Agent Card تم جلبها من الويب المفتوح.
خطأ شائع: توقيع البطاقة ثم تعديل أي حقل — حتى تغييرات القيمة غير المؤثرة في المسافات البيضاء تُبطل JWS.
"signatures": [{
"protected": "eyJhbGciOiJFUzI1NiIs...",
"signature": "QFdkNLNszlGj3z3u0YQ..."
}]رابط لأيقونة تمثّل الوكيل.
تُستخدم من قبل الكتالوجات وواجهات العملاء. قدّمها عبر HTTPS من موقع مستقر.
خطأ شائع: الربط بأيقونة على نطاق مختلف وغير موثوق قد يتغير من تحت قائمتك.
"iconUrl": "https://agent.example.com/icon.png"
ترحيل الإصدار
إذا كانت Agent Card لا تزال تحتوي على url أو preferredTransport على المستوى الأعلى، فإنها تسبق v1.0. تعلّم أداة التحقق كلا هذين تلقائيًا.
| حقل v0.x | بديل v1.0 | سبب التغيير |
|---|---|---|
| url | supportedInterfaces[0].url | نقطة النهاية المفضّلة هي الآن ببساطة أول إدخال واجهة. |
| preferredTransport | supportedInterfaces[] ordering | يُعبَّر عن التفضيل بترتيب المصفوفة بدلاً من حقل منفصل. |
| additionalInterfaces | supportedInterfaces[] | تعيش جميع الواجهات في مصفوفة واحدة مرتبة. |
| protocolVersion (top level) | supportedInterfaces[].protocolVersion | تعلن كل واجهة عن إصدار البروتوكول الخاص بها، مما يتيح دعم إصدارات متعددة. |
| supportsAuthenticatedExtendedCard | capabilities.extendedAgentCard | انتقل إلى كائن capabilities؛ أُعيدت تسمية RPC إلى GetExtendedAgentCard. |
| provider.name | provider.organization | أُعيدت تسميته من أجل الوضوح. |
| capabilities.stateTransitionHistory | — removed | ليس جزءًا من v1.0؛ صمّم سلوكًا مكافئًا كامتداد إذا لزم الأمر. |
قالب جاهز
ضع هذه الواجهات في عميل أو خادم أو فحص CI لتحليل وإنتاج Agent Cards بأمان نوعي. تعكس هذه الواجهات تعريفات protobuf في مستودع المواصفة الرسمي، بصيغة JSON من نوع camelCase التي تُنشر بها Agent Cards.
هل تبني Agent Card يدويًا بدلاً من ذلك؟ ينتج المولّد هذا الشكل بالضبط.
// A2A v1.0 Agent Card — TypeScript definitions
export interface AgentCard {
name: string
description: string
supportedInterfaces: AgentInterface[]
provider?: AgentProvider
version: string
documentationUrl?: string
capabilities: AgentCapabilities
securitySchemes?: Record<string, SecurityScheme>
security?: Record<string, string[]>[]
defaultInputModes: string[]
defaultOutputModes: string[]
skills: AgentSkill[]
signatures?: AgentCardSignature[]
iconUrl?: string
}
export interface AgentInterface {
url: string
protocolBinding: 'JSONRPC' | 'GRPC' | 'HTTP+JSON' | (string & {})
protocolVersion: string
tenant?: string
}
export interface AgentProvider {
organization: string
url: string
}
export interface AgentCapabilities {
streaming?: boolean
pushNotifications?: boolean
extensions?: AgentExtension[]
extendedAgentCard?: boolean
}
export interface AgentExtension {
uri: string
description?: string
required?: boolean
params?: Record<string, unknown>
}
export interface AgentSkill {
id: string
name: string
description: string
tags: string[]
examples?: string[]
inputModes?: string[]
outputModes?: string[]
}
export interface AgentCardSignature {
protected: string
signature: string
header?: Record<string, unknown>
}
export type SecurityScheme =
| { apiKeySecurityScheme: { location: 'header' | 'query' | 'cookie'; name: string; description?: string } }
| { httpAuthSecurityScheme: { scheme: string; bearerFormat?: string; description?: string } }
| { oauth2SecurityScheme: { flows: Record<string, unknown>; oauth2MetadataUrl?: string; description?: string } }
| { openIdConnectSecurityScheme: { openIdConnectUrl: string; description?: string } }
| { mtlsSecurityScheme: Record<string, never> }السلامة
نظرًا لأن Agent Cards تُجلب من الويب المفتوح، تُضفي v1.0 الصفة الرسمية على التوقيع: يتم تقييس Agent Card (باستثناء حقل signatures والقيم الافتراضية) وفق RFC 8785 JSON Canonicalization، ثم توقيعها كـ JWS. ينبغي للعملاء التحقق من توقيع واحد على الأقل — عبر رأس kid/jku أو مخزن مفاتيح موثوق — قبل التصرف بناءً على Agent Card. تدعم التوقيعات المتعددة تدوير المفاتيح.
قدّم Agent Card على /.well-known/agent-card.json عبر HTTPS.
كل إدخال من supportedInterfaces قابل للوصول ويتحدث الربط المُعلن.
تحتوي المهارات على وسوم إلزامية إضافة إلى أوصاف بحدود مهام واضحة.
تطابق القدرات المُعلنة الخادم — يجب أن تُعيد الميزات غير المُعلنة أخطاءً، ويجب أن تعمل الميزات المُعلنة.
تصف securitySchemes كيفية المصادقة؛ لا تظهر أي بيانات اعتماد في أي مكان في Agent Card.
يتم رفع version كلما تغيّر محتوى Agent Card.
وكيل دعم عملاء يستخدم OAuth 2.0 والبث والإشعارات الفورية — مع وجود جميع الحقول الإلزامية. توجد أنماط أخرى في مكتبة الأمثلة.
{
"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"
]
}
]
}الأسئلة الشائعة
تغييرات الإصدار وحقول الاكتشاف وتفاصيل النشر التي تحدد ما إذا كانت Agent Card تجتاز المراجعة.
دمجت v1.0 حقول url وpreferredTransport وadditionalInterfaces في مصفوفة واحدة مرتبة supportedInterfaces حيث يعلن كل إدخال عن url وprotocolBinding وprotocolVersion الخاصة به. انتقل supportsAuthenticatedExtendedCard إلى capabilities.extendedAgentCard، وأصبح provider.name هو provider.organization، وأصبحت وسوم المهارات إلزامية، وأُضفيت الصفة الرسمية على توقيعات Agent Card JWS باستخدام تقييس RFC 8785.
لا. Agent Card هي مستند اكتشاف للوكيل. تلخّص الهوية والواجهات والقدرات والمهارات والأنماط ومزوّد الخدمة وبيانات الأمان الوصفية، بينما يصف مخطط API الكامل أشكال الطلب والاستجابة التفصيلية. تلعب الدور الذي يلعبه README أو نظرة عامة على OpenAPI لخدمة ما: يكفي لتقرير ما إذا كنت ستستدعيها وكيف.
name وdescription وsupportedInterfaces وskills (مع الوسوم) وdefaultInputModes وdefaultOutputModes وcapabilities وprovider وبيانات الأمان الوصفية. تطابق أنظمة التوجيه المهام مقابل description والوسوم الخاصة بمهاراتك، ثم تستخدم الواجهات والقدرات لتخطيط الاستدعاء الفعلي.
انشر فقط المهارات الآمنة للاكتشاف غير الموثّق. إذا لزمت Agent Card خاصة أكثر ثراءً، اضبط capabilities.extendedAgentCard على true واكشف عن المهارات الحساسة عبر عملية GetExtendedAgentCard الموثّقة.
على رابط well-known https://{your-domain}/.well-known/agent-card.json، مُقدَّمة بنوع محتوى application/a2a+json (يعمل application/json أيضًا عمليًا). استخدمت التطبيقات الأقدم /.well-known/agent.json، لذا فإن نشر كليهما أثناء الانتقال خيار عملي.
استخدم المخطط عمليًا
أنشئ Agent Card بشكل v1.0 من تفاصيل خدمتك، أو الصق Agent Card موجودة في أداة التحقق لترى بالضبط أي الحقول تحتاج إلى انتباه.