Phase 13: Tools & Protocols

A2A پروتکل از یک عامل به دیگر

Type: Build

Languages: Python (stdlib, Agent Card + Task harness)

Prerequisites: Phase 13 · 06 (MCP fundamentals), Phase 13 · 08 (MCP client)

Time: ~75 minutes

اهداف یادگیری

• از موارد استفاده از عامل به ابزار (MCP) و از موارد استفاده از عامل به عامل (A2A) تفاوت کنید.
• کارت مامور را در /.well-known/agent-card.jsonبا مهارت ها وsupportedInterfacesمتاداتا
• چرخه عمر کار رو دنبال کن: TASK_STATE_SUBMITTED،TASK_STATE_WORKING،TASK_STATE_INPUT_REQUIRED، و حالت پايانTASK_STATE_COMPLETED،TASK_STATE_FAILED،TASK_STATE_CANCELED،TASK_STATE_REJECTED. .
• از پيام هاي که هر قسمتي از آنها يک عدد دارد استفاده کنtext،raw،url، یاdataو آثار هنری به عنوان محصول

مشکل

یک مامور خدمات مشتری باید گزارش های را به یک مامور متخصص نویسندگی اختصاص دهد.

• .آپي آي آي آر اس رو سفارشي ميکنه .کار ميکنه ولي هر جفتي يه باريه
• . پايگاه کد مشترک . به دو عامل مي خواد که يه چارچوب رو اجرا کنن
• MCP: مناسب نیست: MCP برای تماس ابزار است، نه برای دو عامل همکاری در حالی که حفظ هر عامل غیر شفاف استدلال داخلی است.

A2A شکاف را پر می کند. این تعامل را به عنوان یک عامل ارسال یک وظیفه به دیگری، با چرخه زندگی، پیام ها و آثار هنری مدل می کند. حالت داخلی عامل نامیده شده نامشخص باقی می ماند.

A2A پروتکل "به اجازه دهید عوامل در چارچوب ها با یکدیگر صحبت کنند" است. این جایگزین MCP نیست؛ این دو مکمل هستند.

مفهوم

کارده

هر مامور مطابق با قانون A2A کارت رو به شماره ي /.well-known/agent-card.json:

jsonCopy{
  "name": "research-agent",
  "description": "Summarizes academic papers and drafts citations.",
  "version": "1.2.0",
  "supportedInterfaces": [
    {
      "url": "https:TOK0
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    }
  ],
  "capabilities": {"streaming": true, "pushNotifications": true},
  "securitySchemes": {
    "bearer": {"httpAuthSecurityScheme": {"scheme": "Bearer"}}
  },
  "securityRequirements": [{"schemes": {"bearer": {"list": []}}}],
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["text/markdown"],
  "skills": [
    {
      "id": "summarize_paper",
      "name": "Summarize a paper",
      "description": "Read a paper PDF and produce a 3-paragraph summary.",
      "tags": ["research", "summarization"],
      "inputModes": ["text/plain", "application/pdf"],
      "outputModes": ["text/markdown"]
    }
  ]
}

کشف بر اساس URL است: کارت رو بیار، اولش رو انتخاب کنsupportedInterfacesورودی که protocolBindingموظف شما صحبت می کند و مهارت های خود را به شمار می آورد. حالت ورودی و خروجی انواع رسانه ای هستند.

کارت های امضا شده

کارت مي تونه يه کارت رو نگه دارهsignaturesهر ورودی یک JWS (RFC 7515) است که بر روی RFC 8785 JSON کانونیک کارت محاسبه شده است.signaturesمصرف کنندگان کارت را به همان شیوه می توانند تصدیق کنند.

چرخه عمر وظایف

textCopyTASK_STATE_SUBMITTED
  -> TASK_STATE_WORKING
  -> TASK_STATE_COMPLETED | TASK_STATE_FAILED | TASK_STATE_CANCELED | TASK_STATE_REJECTED

TASK_STATE_WORKING
  -> TASK_STATE_INPUT_REQUIRED
  -> TASK_STATE_WORKING (the client sends a message with the same taskId)

مشتریان شروع می کنند با SendMessage، و سرور کار رو ایجاد ميکنه. مامور به اسم مياد از طریق ايالت ها مي گذرد.GetTaskیا جریان در SSE با SendStreamingMessageوSubscribeToTask. يه رودخانه حمل ميکنهstatusUpdateوartifactUpdateاتفاقات و بسته شدن زمانی که وظیفه به حالت نهایی می رسد.finalپرچم

پیام ها و بخش ها

يه پيام يه پيام دارهmessageId، یکrole(ROLE_USERیاROLE_AGENT), و یک یا چند بخش. هر بخش دقیقا یک زمینه محتوا را دارد و نام این زمینه نوع است.kindمیدان

• text: محتوای ساده
• raw: بائتهای فایل، base64 در JSON، معمولا با filenameوmediaType. .
• url: یک لینک به محتوای فایل
• data: ساختار JSON (دخل ساختار یافته برای عامل تماس)

مثال:

jsonCopy{
  "messageId": "msg-001",
  "role": "ROLE_USER",
  "parts": [
    {"text": "Summarize this paper."},
    {"raw": "...", "filename": "paper.pdf", "mediaType": "application/pdf"},
    {"data": {"targetLength": "3 paragraphs"}, "mediaType": "application/json"}
  ]
}

آثار هنری

محصولات آثار هنری هستند نه رشته های خام. آثار هنری یک محصول نامگذاری شده و تایپ شده است:

jsonCopy{
  "artifactId": "art-001",
  "name": "summary",
  "parts": [{"text": "...", "mediaType": "text/markdown"}]
}

آثار هنری می تونه به شکل قطعه ها پخش بشهartifactUpdateاتفاقي که اين آثار رو همراه دارهappendوlastChunk. تماس گیرنده جمع می شه

سه پروتکل متعهد

1. JSON-RPC 2.0 over HTTP(JSONRPC) POST برای درخواست ها، SSE برای پخش. روش ها PascalCase: SendMessage،SendStreamingMessage،GetTask،ListTasks،CancelTask،SubscribeToTask،CreateTaskPushNotificationConfig،GetTaskPushNotificationConfig،ListTaskPushNotificationConfigs،DeleteTaskPushNotificationConfigوGetExtendedAgentCard. .
2. gRPC(GRPC) برای محیط های شرکتی که gRPC بومی است. نام های روش مشابه.
3. HTTP+JSON/REST(HTTP+JSON). URL منابع مانند POST /message:sendوGET /tasks/{id}. .

هر سه پیوند مدل داده های مشابه را دارند.supportedInterfacesنام ورودی یک متعهد وprotocolVersion. مشتریان سرش رو بفرستندA2A-Version: 1.0در هر درخواست، چون یک سرور یک درخواست بدون آن را به عنوان نسخه 0.3 می خواند.

httpCopyPOST /a2a HTTP/1.1
Host: research.example.com
Content-Type: application/json
A2A-Version: 1.0

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "SendMessage",
  "params": {
    "message": {
      "messageId": "msg-001",
      "role": "ROLE_USER",
      "parts": [{"text": "Summarize this paper."}]
    }
  }
}

حفظ قابلیت خالی

یک اصل طراحی کلیدی: وضعیت داخلی عامل نامیده شده غیر شفاف است. تماس گیرنده حالت کار و آثار را می بیند. زنجیره فکر عامل نامیده شده، تماس های ابزار آن، نمایندگی فرعی آن همه نامرئی است. این از MCP متفاوت است، جایی که تماس های ابزار شفاف است.

استدلال: A2A به رقبای خود امکان همکاری را بدون افشای اطلاعات داخلی می دهد. A2A می تواند "به این نماینده خدمات مشتری تماس بگیرید" بدون اینکه تماس گیرنده یاد بگیرد که چگونه این عامل خدمات را اجرا می کند.

خط زمانی

• 2025-04-09.گوگل اعلام کرد A2A
• 2025-06-23.به بنياد لينکس اهدا شد
• 2025-08.آکسيپ IBM رو جذب ميکنه
• 2025-09.کشتی های توسعه AP2 (دفع توسط آژانس)
• 2026-04.نسخه 1.0 با 150+ سازمان پشتیبانی منتشر شد.

رابطه با MCP

استفاده از MCP هنگامی که می خواهید یک ابزار خاص را فراخوانید. استفاده از A2A هنگامی که می خواهید یک کار را به یک عامل دیگر اختصاص دهید. بسیاری از سیستم های تولید از هر دو استفاده می کنند: یک عامل از MCP برای لایه ابزار خود و A2A برای لایه همکاری خود استفاده می کند.

ازش استفاده کن

code/main.pyاستفاده از یک آرم A2A کمترین: نویسنده آژانس کارت خود را منتشر می کند، آژانس تحقیقاتی ارسال می کند SendMessageدرخواست با یک بخش PDF و یک دستورالعمل متن، و کار حرکت می کند از طریق TASK_STATE_WORKING→ TASK_STATE_INPUT_REQUIRED→ TASK_STATE_WORKING→ TASK_STATE_COMPLETEDقبل از بازگشت یک متن آرتیفکت. تمام stdlib؛ از یک حمل و نقل در حافظه برای تمرکز بر روی اشکال پیام استفاده می کند.

چه چیزی رو باید ببینیم:

• شکل کارت مامور JSON
• تعیین هویت وظیفه در سمت سرور و انتقال حالت.
• قسمت هایی که با وجود زمینه محتوا تایپ شده اند.
• TASK_STATE_INPUT_REQUIREDشاخه وسط کار
• آثار آثار بعد از اتمام بازگردانده شد

-باده

این درس به ما کمک می کندoutputs/skill-a2a-agent-spec.md. با توجه به یک عامل جدید که باید توسط سایر عوامل تماس گرفته شود، مهارت JSON کارت عامل، طرح مهارت و طرح نقطه پایان را تولید می کند.

تمرینات

1. فرار کنcode/main.py.تراسه کل چرخه عمر وظیفه، از جمله TASK_STATE_INPUT_REQUIREDوقتي که مامور تماس گرفته ازش درخواست تصحيحات مي کنه

1. يه کارت مامور امضا شده رو اضافه کنsignaturesباalgبه HS256، امضا کردن JSON کانونیک کارت بدون signaturesیک تایید کننده بنویسید و تایید کنید که در کارت جهش یافته شکست خورده.

1. اجرا کردن جریان کاری با SendStreamingMessage: مامور نویسنده ارسال می کندtask، سهartifactUpdateقطعات و یکstatusUpdateباTASK_STATE_COMPLETED، سپس جریان رو می بندد. تماس گیرنده قطعات را جمع می کند.

1. طراحی یک عامل A2A که یک سرور MCP را بسته کند. هر ابزار MCP را به یک مهارت A2A نقشه بزنید. توجه به تعادلات کنید عدم شفافیت چه چیزی از دست می دهد؟

1. اعلامیه A2A v1.0 را بخوانید و ویژگی ای را شناسایی کنید که هنوز توسط هیچ چارچوبی از آوریل 2026 اجرا نشده است.

اصطلاحات کلیدی

خواندن بیشتر

• a2a-protocol.org مشخصات A2A قانونی
• a2aproject/A2A — GitHub پیاده سازی های مرجع و SDK ها
• A2A v1.0.1 release: برچسب هاdocs/specification.mdو قانون سنجشspecification/a2a.protoاین درس میخواد
• Linux Foundation — A2A launch press release انتقال حاکمیت در ژوئن 2025
• Google Cloud — A2A protocol upgrade نقشه راه و حرکت شرکا
• Google Dev — A2A 1.0 milestone یادداشت های انتشار v1.0 و راهنمایی های کمپیکت عقب

This free lesson is part of the AI Engineering from Scratch curriculum. Read the full explanation, run the lesson code, and verify the result in the interactive reader or from the repository source.

Browse the complete course catalog or open this lesson on GitHub.