شروع پروژه

چیت‌شیت

A2A و پروتکل‌های ارتباطی ایجنت‌ها

A2A and Agent Communication Protocols

مقایسه‌ی رو در روی MCP، A2A، ACP، ANP و FIPA-ACL. کارت‌های ایجنت، تسک‌ها، نام‌های روی سیم و خطاها. A2A 1.0.1.

  • ۱۱ بخش
  • ۴ درس مرتبط
  • کد و دستورها عیناً از دوره‌ی اصلی
فهرست مطالب
  1. مقایسه‌ی چهار پروتکل در کنار هم
  2. کِی از کدام استفاده کنیم؟
  3. فراخوانی A2A روی بستر HTTP+JSON
  4. چرخه‌ی حیات وظیفه با وقفه
  5. وظایف A2A روی سیم
  6. ساختار کارت ایجنت و پیام
  7. پیش‌فرض‌ها و اعداد
  8. میراث FIPA-ACL
  9. عیب‌یابی
  10. کوته‌نوشت‌ها
  11. پرسش‌ها

مقایسه‌ی چهار پروتکل در کنار هم

مقایسه
فاکتورMCPA2AACPANP
کاربرد اصلیایجنت به ابزارایجنت به ایجنتایجنت به ایجنتایجنت به ایجنت
فرمت مشخصاتJSON-RPCJSON-RPC / REST / gRPCOpenAPI 3.1 (REST)JSON-RPC
شناساییفهرست ابزارها/.well-known/agent-card.jsonGET /agents، /.well-known/agent.yml/.well-known/agent-descriptions
هویتضمنی (محلی)طرح‌های امنیتی (OAuth، mTLS)در سطح سرورشناسه W3C DID (did:wba) با رمزنگاری E2EE
ردگیری ممیزینداردپایه‌ای (تاریخچه‌ی وظیفه)TrajectoryMetadataبه صورت رسمی مشخص نشده
استریمینگنداردSSESSEمستقل از بستر انتقال
ویژگی منحصربه‌فرداسکیماهای ابزارکارت‌های ایجنت + مهارت‌هاردگیری ممیزی با مسیر کامل اجرامذاکره‌ی فراپروتکل
وضعیتپایدارپایدار (نسخه 1.0)در حال ادغام در A2Aتوسعه‌ی فعال

کِی از کدام استفاده کنیم؟

مفهوم‌ها
MCP
قصد فراخوانی یک ابزار خاص را دارید. ایجنت به ابزار.
A2A
قصد واگذاری یک وظیفه‌ی کامل به ایجنتی دیگر را دارید.
الگوهای A2A + ACP
برای انطباق به ردگیری ممیزی نیاز دارید.
ANP + A2A
ایجنت‌ها خارج از سازمان شما هستند و زیرساخت مشترکی ندارند.
A2A + بروکر پیام
ایجنت‌های بیرونی روی زیرساخت مشترک.
فراخوانی مستقیم RPC
ریزفراخوانی‌های حساس به تاخیر. چرخه‌ی حیات A2A ناهمگام است.
بدون پروتکل
ایجنت‌ها نیازی به گفت‌وگو با یکدیگر ندارند.

فراخوانی A2A روی بستر HTTP+JSON

معماری
شناساییپیامایجاد وظیفهوظیفهایجنت کلاینتارسال می‌کند: A2A-Version: 1.0کارت ایجنت/.well-known/agent-card.jsonPOST /message:sendreturnImmediatelyTaskStoreوضعیت + دست‌سازه‌هاGET /tasks/{id}تا رسیدن به وضعیت پایانی

چرخه‌ی حیات وظیفه با وقفه

گام‌به‌گام
  1. کلاینتSendMessage را بدون taskId می‌فرستد. سرور وظیفه را ایجاد می‌کند.
  2. سرورمقدار TASK_STATE_SUBMITTED و سپس TASK_STATE_WORKING را تنظیم می‌کند.
  3. سرورداده ناقص است. وضعیت TASK_STATE_INPUT_REQUIRED را با پیام ROLE_AGENT تنظیم می‌کند.
  4. کلاینتپیام جدیدی با همان taskId و بخش data ارسال می‌کند.
  5. سروربه وضعیت TASK_STATE_WORKING برمی‌گردد و یک دست‌سازه اضافه می‌کند.
  6. سرورمقدار TASK_STATE_COMPLETED را ثبت می‌کند. وضعیت‌های پایانی تغییرناپذیرند.
  7. کلاینتپیگیری بعدی، وظیفه‌ی جدیدی در همان contextId می‌سازد.

وظایف A2A روی سیم

کار و کد
وظیفهکد
شناسایی یک ایجنتGET /.well-known/agent-card.json
ارسال و انتظار (JSON-RPC)"method": "SendMessage"
ارسال، بازگشت فوری (HTTP+JSON)`POST /message:send` with `configuration.returnImmediately`
بررسی دوره‌ای یک وظیفه`GetTask` or `GET /tasks/{id}`
استریمینگ وظیفه روی بستر SSE`SendStreamingMessage` or `POST /message:stream`
اتصال مجدد به نشست یک وظیفه‌ی در حال اجرا`SubscribeToTask` or `/tasks/{id}:subscribe`
لغو یا فهرست‌کردن وظایف`CancelTask`, `ListTasks`
اجرای سرور و کلاینت نمایشیpython3 code/main.py

ساختار کارت ایجنت و پیام

کد
json
{"name": "research-agent", "version": "1.2.0",
 "supportedInterfaces": [{"url": "<url>",        // اولین بایندینگی که پشتیبانی می‌کنید را انتخاب کنید
   "protocolBinding": "JSONRPC", "protocolVersion": "1.0"}],
 "capabilities": {"streaming": true, "pushNotifications": true},
 "securitySchemes": {"bearer": {"httpAuthSecurityScheme": {"scheme": "Bearer"}}},
 "securityRequirements": [{"schemes": {"bearer": {"list": []}}}],
 "defaultInputModes": ["text/plain"],            // نوع‌های مدیا
 "skills": [{"id": "summarize_paper", "tags": ["research"]}]}
{"messageId": "msg-001", "role": "ROLE_USER",    // یا ROLE_AGENT
 "parts": [{"text": "Summarize this paper."},    // یک فیلد محتوا برای هر Part
   {"raw": "...", "filename": "paper.pdf", "mediaType": "application/pdf"},
   {"data": {"targetLength": "3 paragraphs"}}]}  // بدون فیلد نوع (kind)

پیش‌فرض‌ها و اعداد

پیش‌فرض‌ها
تنظیمپیش‌فرضنکته
A2A_VERSION"1.0"روی هر درخواست A2A-Version: 1.0 را ارسال کنید
No `A2A-Version` header0.3سرور درخواست را با نسخه‌ی 0.3 می‌خواند
returnImmediatelyFalseSendMessage تا زمان وضعیت پایانی یا وقفه مسدود می‌ماند
A2A_MEDIA_TYPE"application/a2a+json"Content-Type بایندینگ HTTP+JSON
PORT8765سرور نمایشی درس 16.12
ANP negotiationmax 10 roundsسپس پایان مهلت زمانی (timeout)

میراث FIPA-ACL

مقایسه
مشخصات نوینمعادل FIPAموارد حفظ‌شدهموارد حذف‌شده
ابزار tools/call در MCPrequestنیت، شناسه‌ی تطبیقمعناشناسی، هستی‌شناسی
ابزار resources/read در MCPquery-refنیت، شناسه‌ی تطبیقمعناشناسی رسمی
چرخه‌ی حیات وظیفه‌ی A2Acontract-net + request-whenچرخه‌ی حیات ناهمگامتضمین‌های جامعیت
رویدادهای استریمینگ A2Asubscribe/notifyارسال به روش push ناهمگاماشتراک با گزاره‌های نوع‌دار
NLIPمحتوای زبان طبیعیسازگار با LLMاسکیما

عیب‌یابی

عیب‌یابی

  • خطای JSON-RPC کد -32009

    علت
    نبود یا نادرستی A2A-Version
    راه‌حل
    ارسال هدر A2A-Version: 1.0

  • خطای JSON-RPC کد -32601

    علت
    نام متد نامعتبر است
    راه‌حل
    استفاده از نام‌های PascalCase مانند SendMessage

  • کد 400 در HTTP با عنوان VERSION_NOT_SUPPORTED

    علت
    فراخوانی HTTP+JSON بدون هدر
    راه‌حل
    افزودن هدر مربوطه به تمام درخواست‌ها

  • کد 404 در HTTP با عنوان TASK_NOT_FOUND

    علت
    شناسه‌ی وظیفه‌ی نامعتبر در GET /tasks/{id}
    راه‌حل
    استفاده از شناسه‌ی دریافتی در پاسخ task

  • از دست رفتن به‌روزرسانی‌ها پس از اتمام

    علت
    تسک پس از رسیدن به وضعیت نهایی تغییرناپذیر است
    راه‌حل
    پیش از yield وضعیت نهایی را بررسی کنید

  • داده‌های نامعتبر پس از به‌روزرسانی کارت

    علت
    دریفت اسکیما میان نسخه‌ها
    راه‌حل
    نسخه‌بندی مهارت‌ها و اسکیماهای خروجی

  • واژه‌ی یکسان، عمل اشتباه

    علت
    انحراف معنایی در نبود هستی‌شناسی
    راه‌حل
    استفاده از JSON Schema روی content و دست‌سازه‌های نوع‌دار

  • هجوم همزمان 50 ایجنت به GET /agents

    علت
    گله‌ی خروشان در فاز شناسایی
    راه‌حل
    کش‌کردن کارت‌های ایجنت با استفاده از TTL

کوته‌نوشت‌ها

اصطلاح‌ها
A2A
ارتباط Agent2Agent. پروتکل همتا با کارت‌های ایجنت و تسک‌ها.
ACP
پروتکل ارتباطی ایجنت. اجراهای بر بستر REST همراه‌با TrajectoryMetadata.
ANP
پروتکل شبکه‌ی ایجنت. هویت با did:wba و رمزنگاری E2EE از نوع HPKE.
DID
شناسه‌ی غیرمتمرکز. هویت استاندارد W3C روی دامنه‌ی اختصاصی خود ایجنت.
NLIP
پروتکل تعاملی زبان طبیعی از Ecma. نوع محتوای مبتنی بر زبان طبیعی.
FIPA
بنیاد ایجنت‌های فیزیکی هوشمند. استانداردساز ACL در سال 2000.
ACL
زبان ارتباطی ایجنت. کلام‌کنش به‌همراه محتوا و متادیتا.
KQML
زبان پرس‌وجو و دستکاری دانش (1993). پیش‌نیاز و نیای FIPA.

پرسش‌ها

پرسش و پاسخ
فراخوان در پروتکل A2A چه چیزهایی را می‌بیند؟
وضعیت وظیفه و دست‌سازه‌ها را. جزئیات داخلی ایجنت فراخوانده‌شده پنهان می‌ماند.
چگونه از ثبت تسک تکراری در تلاش مجدد جلوگیری کنم؟
با یکتاسازی بر اساس messageId ارسالی از سمت کلاینت.
کارت ایجنت چگونه امضا می‌شود؟
با یک JWS داخل signatures روی متن استاندارد JSON طبق RFC 8785، منهای خود فیلد signatures.
پروتکل ACP چه چیزی به سیستم اضافه می‌کند؟
هر پارت می‌تواند متادیتای tool_name، tool_input و tool_output را با خود حمل کند.
در صورت ناموفق بودن واکشی DID، سیستم باز بماند یا بسته؟
طبق اصل حداقل اعتماد، دسترسی باید مسدود (Fail closed) شود.
کدام پروتکل‌های FIPA ارزش بازپیاده‌سازی دارند؟
پروتکل‌های Contract Net، Subscribe/Notify و Request-When.

درس‌هایی که این موضوع را از صفر می‌سازند