چیت‌شیت

پروتکل A2A

A2A Protocol

کارت‌ها، پیام‌ها، وظایف، وضعیت‌ها، سه بایندینگ، خطاها و لایه 0.3 از A2A 1.0.1. نکات برگرفته از مستندات رسمی.

۱۱ بخش
کد و دستورها عیناً از دوره‌ی اصلی

فهرست مطالب

معماری پروتکل
ارسال و خواندن یک وظیفه
دستورات روی HTTP+JSON
تنظیمات و پیش‌فرض‌ها
مقایسه‌ی بایندینگ‌ها
وضعیت‌های وظیفه
یک وظیفه، گام‌به‌گام
درخواست JSON-RPC
عیب‌یابی
پرسش و پاسخ
نکات کاربردی

معماری پروتکل

معماری

ارسال و خواندن یک وظیفه

کار و کد

Task	کد
خواندن کارت ایجنت	`GET /.well-known/agent-card.json HTTP/1.1`
ارسال یک پیام	`"method": "SendMessage"` posted to `/a2a/jsonrpc`
ارسال نسخه	`A2A-Version: 1.0`
ارسال و بازگشت آنی	`"returnImmediately": true` in `configuration`
باز کردن یک استریم	`"method": "SendStreamingMessage"`

دستورات روی HTTP+JSON

دستورها

دستور	کارکرد
`POST /a2a/rest/message:send`	یک پیام ارسال می‌کند. پاسخ یک وظیفه یا یک پیام است.
`POST /a2a/rest/tasks/<task id>:cancel`	از سرور می‌خواهد وظیفه‌ای که غیرنهایی است را متوقف کند.
`GET /.well-known/agent-card.json`	کارت ایجنت را از مسیر well-known می‌خواند.
`POST /a2a/rest/tasks/<task id>:cancel`	وقتی وظیفه قبلاً نهایی شده باشد، خطای وظیفه برمی‌گرداند.

تنظیمات و پیش‌فرض‌ها

پیش‌فرض‌ها

تنظیم	پیش‌فرض	نکته
`returnImmediately`	`false`	عملیات ارسال منتظر وضعیت نهایی یا دارای وقفه می‌ماند
`historyLength`	`unset`	سرور تعیین می‌کند چه مقدار از تاریخچه بازگردانده شود. `0` هیچ تاریخچه‌ای برنمی‌گرداند.
`pageSize`	`50`	حداکثر مقدار در `ListTasks` برابر 100 است
`includeArtifacts`	`false`	دست‌سازه‌ها از نتایج لیست حذف می‌شوند
`A2A-Version`	`1.0`	الزامی در تمام درخواست‌ها، بدون شماره پچ

مقایسه‌ی بایندینگ‌ها

مقایسه

معیار	JSON-RPC	HTTP+JSON	gRPC
نام‌گذاری عملیات با	`method`، مانند `SendMessage`	route، مانند `POST /message:send`	rpc با نام `SendMessage` در `A2AService`
محل ارسال	یک URL واحد، `/a2a/jsonrpc` در کیت	یک route به‌ازای هر عملیات	`lf.a2a.v1.A2AService` روی HTTP/2 با TLS
فریم استریم	یک خط `data:` با پاسخ کامل JSON-RPC	یک خط `data:` فقط با `StreamResponse`	یک rpc سرور-استریمینگ از `StreamResponse`
`TaskNotFoundError`	`-32001` با HTTP 200	HTTP 404	`NOT_FOUND`
هدر نسخه	هدر `A2A-Version`	هدر `A2A-Version`	کلید متادیتای `a2a-version`

وضعیت‌های وظیفه

مفهوم‌ها

Active: وضعیت‌های TASK_STATE_SUBMITTED و TASK_STATE_WORKING. ایجنت هنوز در حال کار است.
Interrupted: وضعیت‌های TASK_STATE_INPUT_REQUIRED و TASK_STATE_AUTH_REQUIRED. وظیفه منتظر شماست.
Terminal: وضعیت‌های TASK_STATE_COMPLETED، TASK_STATE_FAILED، TASK_STATE_CANCELED، TASK_STATE_REJECTED. وظیفه دیگر هرگز تغییر نمی‌کند.
TASK_STATE_UNSPECIFIED: هرگز توسط کیت ارسال نمی‌شود. با آن مثل یک خطا برخورد کنید.

یک وظیفه، گام‌به‌گام

گام‌به‌گام

Clientیک SendMessage مسدودکننده (blocking) با messageId جدید و بدون taskId ارسال می‌کند.
Serverوظیفه را می‌سازد و taskId و contextId آن را تولید می‌کند.
Agentدر TASK_STATE_INPUT_REQUIRED متوقف می‌شود، و فراخوانی وظیفه را همراه با سؤالش برمی‌گرداند.
Clientبا دومین SendMessage با همان taskId و contextId پاسخ می‌دهد.
Serverهمان وظیفه را در وضعیت TASK_STATE_COMPLETED به همراه دست‌سازه‌اش برمی‌گرداند.
Clientمتد GetTask را با taskId فراخوانی می‌کند تا وظیفه‌ی ذخیره‌شده را دوباره بخواند.

درخواست JSON-RPC

کد

bash

curl -s http://localhost:41242/a2a/jsonrpc \                 # یک URL واحد برای تمام عملیات
  -H 'Content-Type: application/json' \                      # بدنه‌ی JSON
  -H 'A2A-Version: 1.0' \                                    # الزامی در تمام درخواست‌ها
  -d '{
    "jsonrpc": "2.0",                                        # نسخه‌ی پاکت (envelope)، همیشه 2.0
    "id": 1,                                                 # پاسخ همین id را تکرار می‌کند
    "method": "SendMessage",                                 # نام عملیات به صورت PascalCase
    "params": {"message": {
      "messageId": "d95bafc8-f2a4-427b-9cf4-bb99f4bea973",   # تولیدشده توسط کلاینت
      "role": "ROLE_USER",                                   # کلاینت همیشه ROLE_USER را ارسال می‌کند
      "parts": [{"text": "What languages can you review?"}]  # حداقل یک بخش
    }}
  }'

عیب‌یابی

-32009 در تمام فراخوانی‌ها
علت
نبود هدر A2A-Version
راه‌حل
ارسال A2A-Version: 1.0
-32601 همراه با message/send
علت
نام متد مربوط به نسخه 0.3 است
راه‌حل
ارسال SendMessage
-32004 روی یک وظیفه‌ی خاتمه‌یافته
علت
وظیفه نهایی (terminal) است
راه‌حل
شروع یک وظیفه با referenceTaskIds در همان context
-32003 روی فراخوانی تنظیمات push
علت
کارت فاقد فلگ pushNotifications است
راه‌حل
خواندن کارت قبل از فراخوانی
-32602 با جزئیات BadRequest
علت
message.messageId موجود نیست
راه‌حل
تولید یک messageId برای هر پیام
-32001 یا HTTP 404
علت
شناسه نامعتبر، پاک‌شده یا پنهان است
راه‌حل
شناسه را بررسی کنید، سپس متوقف شوید

پرسش و پاسخ

چرا ارسال منتظر می‌ماند؟: مقدار پیش‌فرض returnImmediately برابر false است. فراخوانی تا رسیدن به وضعیت نهایی یا وقفه معلق می‌ماند.
نتیجه کجاست؟: در artifacts. یک پیام نباید خروجی وظیفه را حمل کند.
چرا برای وظیفه‌ی یک فراخواننده‌ی دیگر TaskNotFoundError بازگردانده می‌شود؟: مشخصات پروتکل فاش کردن وجود منبع را منع کرده است.

نکات کاربردی

نکته‌ها

برای هر پیام جدید یک messageId نو تولید کنید. از آن فقط برای تلاش مجدد استفاده کنید.
از کلاینت ROLE_USER و از سرور ROLE_AGENT ارسال کنید.
برای بررسی وضعیت، historyLength را 0 بفرستید.
پیش از فراخوانی اختیاری، کارت و فلگ‌های قابلیت آن را بررسی کنید.