سناریوی رخداد

خاموش‌سازی سیستمی که تا ابد لغو وظایف را تکرار می‌کرد

A shutdown that retried a cancel forever

  • سطح ۲: میانی
  • سناریوی رخداد
  • ۲۰ دقیقه

وضعیت

یک سرویس ناظر (supervisor)، ناوگانی از ایجنت‌های راه‌دور (remote agents) را هدایت می‌کند. در پایان هر اجرا، ناظر فهرستی از تمام وظایف (tasks) شروع‌شده تهیه کرده و برای هر کدام یک درخواست CancelTask می‌فرستد. قاعده‌ی آن برای تمام فراخوانی‌ها ساده است: دریافت خطا یعنی «هنوز نه»؛ بنابراین فراخوانی آن‌قدر تکرار می‌شود تا سرانجام یک شیء وظیفه برگرداند. دیشب فرایند خاموش‌سازی هرگز تمام نشد. دو وظیفه روی ایجنت test-runner در تمام طول شب و در تک‌تک تلاش‌ها با خطا پاسخ دادند.

مهندس نوبت پاسخگویی (آنکال)، لاگ ناظر را بررسی می‌کند. یکی از این دو وظیفه پیش‌تر در حین اجرا، به‌صورت دستی و از طریق همان ایجنت توسط یک اپراتور متوقف شده بود. پس از آن‌که روتین خاموش‌سازی در لغو آن ناموفق ماند، مهندس پیام «Try again» را برای بیدار کردن وظیفه فرستاد و با نوع دومی از خطا روبه‌رو شد. در تیکت ثبت‌شده آمده که ایجنت قفل کرده است و درخواست ری‌استارت آن داده شده است. شما چهار تبادل ثبتی را که کیت ضبط ترافیک برای همین توالی از فراخوانی‌ها ذخیره کرده در اختیار دارید.

نسخه
A2A 1.0.1 with the manual's capture kit (the test-runner, code-reviewer and deployer agents)
مدل
no model; the agents are deterministic fixtures
سخت‌افزار
one machine, localhost, no network

شواهد

after-a-cancel-that-errors.txt
title: what the specification and the implementations say about a repeated cancel
source: manuals/a2a-101/sections/4-4-cancel-task-and-terminal-states.md
lines: 61-63
lang: text
note: Two sections of the specification disagree, and the last line gives the call that settles it.
---
A second `CancelTask` gets `TaskNotCancelableError`, `-32002`, from the kit and the reference SDK {{sdk src/a2a/server/request_handlers/default_request_handler_v2.py}}, as §3.1.5 lists for a finished task {{spec §3.1.5}}. Section 3.3.1 disagrees: it calls Cancel Task idempotent, so several cancel requests have the same effect {{spec §3.3.1}}. A repeat on a deleted task is allowed to return `TaskNotFoundError` {{spec §3.3.1}}.

So after a cancel that errors, call `GetTask`. Canceled means an earlier cancel worked, another terminal state means the task ended first, and running means the server cannot stop it {{spec §3.1.5}}.
first-cancel.txt
title: the reply to the first CancelTask
source: manuals/a2a-101/capture/out/10-cancel.http
lines: 73-136
lang: text
note: Read the state, the status message, and what the task still carries in history and artifacts.
---
HTTP/1.1 200 OK
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "id": "f22ed7af-848d-4f4d-8cd1-3204d1e1bbaf",
    "contextId": "9b584e1f-b948-453f-9250-18314071afc7",
    "status": {
      "state": "TASK_STATE_CANCELED",
      "message": {
        "messageId": "9f730657-74a7-43df-b405-5a8270fe73a9",
        "contextId": "9b584e1f-b948-453f-9250-18314071afc7",
        "taskId": "f22ed7af-848d-4f4d-8cd1-3204d1e1bbaf",
        "role": "ROLE_AGENT",
        "parts": [
          {
            "text": "Canceled at the client's request."
          }
        ]
      },
      "timestamp": "2026-10-06T09:00:03.750Z"
    },
    "history": [
      {
        "messageId": "7b89296c-6dcb-4c50-8857-7eb1924770d3",
        "contextId": "9b584e1f-b948-453f-9250-18314071afc7",
        "taskId": "f22ed7af-848d-4f4d-8cd1-3204d1e1bbaf",
        "role": "ROLE_USER",
        "parts": [
          {
            "text": "Run the full suite for payments-api at commit 9f3c2e1"
          }
        ]
      },
      {
        "messageId": "4e4233ac-1dca-4ecc-8b5f-0a7afff7c0bf",
        "contextId": "9b584e1f-b948-453f-9250-18314071afc7",
        "taskId": "f22ed7af-848d-4f4d-8cd1-3204d1e1bbaf",
        "role": "ROLE_AGENT",
        "parts": [
          {
            "text": "Checking out 9f3c2e1 and starting the suite"
          }
        ]
      }
    ],
    "artifacts": [
      {
        "artifactId": "test-log",
        "name": "test-log.txt",
        "parts": [
          {
            "text": "tests/test_suite_01.py ........\n"
          },
          {
            "text": "tests/test_suite_02.py ........\n"
          }
        ]
      }
    ]
  }
}
message-after-cancel-reason.txt
title: the detail inside the error for the message
source: manuals/a2a-101/capture/out/10-cancel.http
lines: 213-222
lang: text
note: Compare the reason and the state with the ones in the cancel error.
---
        "reason": "UNSUPPORTED_OPERATION",
        "domain": "a2a-protocol.org",
        "metadata": {
          "taskId": "f22ed7af-848d-4f4d-8cd1-3204d1e1bbaf",
          "state": "TASK_STATE_CANCELED"
        }
      }
    ]
  }
}
message-after-cancel.txt
title: a message sent to the canceled task, and the code it got
source: manuals/a2a-101/capture/out/10-cancel.http
lines: 176-211
lang: text
note: The message carries the task id and the context id of the canceled task.
---
### 4 · SendMessage: to the canceled task
POST /a2a/jsonrpc HTTP/1.1
Host: localhost:41241
Content-Type: application/json
A2A-Version: 1.0

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "SendMessage",
  "params": {
    "message": {
      "messageId": "766bad07-34c2-4a80-83cc-0f2793fdcab8",
      "contextId": "9b584e1f-b948-453f-9250-18314071afc7",
      "taskId": "f22ed7af-848d-4f4d-8cd1-3204d1e1bbaf",
      "role": "ROLE_USER",
      "parts": [
        {
          "text": "Try again"
        }
      ]
    }
  }
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 4,
  "error": {
    "code": -32004,
    "message": "This operation is not supported",
    "data": [
      {
second-cancel-reason.txt
title: the detail inside the second cancel error
source: manuals/a2a-101/capture/out/10-cancel.http
lines: 165-174
lang: text
note: The reason names the error, and the metadata names the state the task is in.
---
        "reason": "TASK_NOT_CANCELABLE",
        "domain": "a2a-protocol.org",
        "metadata": {
          "taskId": "f22ed7af-848d-4f4d-8cd1-3204d1e1bbaf",
          "state": "TASK_STATE_CANCELED"
        }
      }
    ]
  }
}
second-cancel.txt
title: the second CancelTask on the same id, status and code
source: manuals/a2a-101/capture/out/10-cancel.http
lines: 138-163
lang: text
note: The HTTP status and the code that replaced result.
---
### 3 · CancelTask: again
POST /a2a/jsonrpc HTTP/1.1
Host: localhost:41241
Content-Type: application/json
A2A-Version: 1.0

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "CancelTask",
  "params": {
    "id": "f22ed7af-848d-4f4d-8cd1-3204d1e1bbaf"
  }
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 3,
  "error": {
    "code": -32002,
    "message": "Task cannot be canceled",
    "data": [
      {
the-send.txt
title: the send that started the suite, and the state it came back in
source: manuals/a2a-101/capture/out/10-cancel.http
lines: 21-40
lang: text
note: The configuration asks the server to return at once. Read the state and the timestamp of the task that came back.
---
    "configuration": {
      "returnImmediately": true
    }
  }
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "task": {
      "id": "f22ed7af-848d-4f4d-8cd1-3204d1e1bbaf",
      "contextId": "9b584e1f-b948-453f-9250-18314071afc7",
      "status": {
        "state": "TASK_STATE_SUBMITTED",
        "timestamp": "2026-10-06T09:00:03.250Z"
      },

سؤال‌ها

  1. اولین لغو چه چیزی برگرداند و وظیفه هنوز شامل چه مواردی بود؟
  2. لغو دوم و پیام بعدی، دو کد متفاوت گرفتند. جزئیات خطای آن‌ها چه وجه اشتراکی دارد؟
  3. آیا لغو مجدد یک خطا است یا عملیاتی بی‌اثر (no-op)؟ مشخصات استاندارد چه می‌گوید و کیت و پیاده‌سازی مرجع چه می‌کنند؟
  4. کدام فراخوانی به ناظر می‌گوید که باید ادامه دهد یا نه، و سه نتیجه‌ی احتمالی آن چیست؟
  5. ناظر چگونه کاری را که وظیفه‌ی لغوشده انجام می‌داد ادامه می‌دهد؟

اول شواهد را بخوانید و به سؤال‌ها جواب بدهید، بعد راه‌حل را باز کنید.

راه‌حل گام‌به‌گام
  1. بررسی درخواست ارسال: برنامه‌ریز (planner)، کل مجموعه‌ی آزمون را با فعال بودن returnImmediately درخواست کرده بود و وظیفه با وضعیت TASK_STATE_SUBMITTED برگشت. وظیفه وجود دارد و در غیاب کلاینت به کارش ادامه می‌دهد.
  2. بررسی اولین لغو: پاسخ، خودِ شیء وظیفه است؛ این بار در وضعیت TASK_STATE_CANCELED و با پیام وضعیت «Canceled at the client's request.». تاریخچه، شامل درخواست اولیه و پیام پیشرفت ایجنت است، و دست‌سازه‌ها (artifacts) دو بخش لاگی را که مجموعه‌ی آزمون ثبت کرده بود در خود دارند. لغو، درخواستی است که سرور حق رد کردن آن را دارد و این درخواست موفقیت‌آمیز بوده است.
  3. بررسی دومین لغو: وضعیت HTTP برابر 200 است، چرا که خطاهای JSON-RPC در قالب کد 200 منتقل می‌شوند. بدنه حاوی یک error با کد -32002 و پیام «Task cannot be canceled» است. بخش جزئیات، دلیل را TASK_NOT_CANCELABLE و در metadata وضعیت را TASK_STATE_CANCELED اعلام می‌کند. این خطا نمی‌گوید «بعداً تلاش کنید»؛ بلکه می‌گوید این وظیفه قبلاً پایان یافته و دلیل و نحوه‌ی پایان آن را هم مشخص می‌کند.
  4. بررسی پیام ارسالی: پیام «Try again» شناسه‌ی وظیفه و شناسه‌ی کانتکست وظیفه‌ی لغوشده را همراه دارد. کد خطا -32004 و دلیل آن UNSUPPORTED_OPERATION است. متادیتا همان وضعیت را نام می‌برد. یک وظیفه‌ی پایانی (terminal task) پیام جدید، لغو مجدد یا اشتراک را رد می‌کند. تنها GetTask همچنان پاسخگوست.
  5. بررسی قاعده: بخشی از مشخصات استاندارد، خطای TaskNotCancelableError را برای وظیفه‌ی پایان‌یافته برمی‌شمرد و بخشی دیگر لغو را بی‌اثر در تکرار (idempotent) می‌داند. هم این سرور و هم SDK مرجع، کد -32002 را برمی‌گردانند و لغو یک وظیفه‌ی حذف‌شده ممکن است خطای یافت‌نشدن (not found) برگرداند. کلاینت نمی‌تواند از قبل رفتار دقیق سرور را بداند؛ بنابراین پس از لغوی که به خطا می‌خورد، GetTask را فراخوانی می‌کند. دریافت وضعیت Canceled یعنی لغو قبلی کارساز بوده است. وضعیت پایانی دیگر یعنی وظیفه زودتر تمام شده بود. وضعیت Running یعنی سرور نتوانسته جلوی اجرای آن را بگیرد.
  6. بررسی مجموعه‌ی وضعیت‌های پایانی: چهار وضعیت پایانی داریم: تکمیل‌شده (completed)، ناموفق (failed)، لغوشده (canceled) و ردشده (rejected). حلقه‌ای که شرط موفقیتش بازگشت «یک شیء وظیفه» باشد، روی وظیفه‌ای که در یکی از این وضعیت‌ها قرار دارد تا ابد می‌چرخد و متوقف نمی‌شود.
نتیجه

چیزی قفل نکرده بود. قاعده‌ی تلاش مجدد ناظر، یک وضعیت پایدار را خطایی گذرا فرض کرده بود و پیام «Try again» مهندس نیز همان اشتباه را با ارسال پیام تکرار کرد. راه‌حل در کلاینت است. وقتی CancelTask خطا می‌دهد، ناظر یک بار GetTask را فراخوانی کرده و وضعیت را می‌خواند. دیدن یک وضعیت پایانی، پرونده‌ی آن مدخل را می‌بندد. کد -32004 را باید همراه با متادیتای آن خواند، زیرا همین کد خطاهای مربوط به کارت بدون استریمینگ (streaming) و کارت بدون کارت توسعه‌یافته را هم پوشش می‌دهد. ناظر برای ادامه‌ی کار، وظیفه‌ی جدیدی در همان کانتکست ایجاد کرده و شناسه‌ی وظیفه‌ی پایان‌یافته را در referenceTaskIds قید می‌کند. این سرویس هرگز به یک وظیفه‌ی پایانی پیام نمی‌فرستد. در ترافیک ثبت‌شده، هر فراخوانی بعد از لغو، یک درخواست و یک پاسخ قطعی است؛ یعنی دقیقاً همان چیزی که روتین خاموش‌سازی اکنون انجام می‌دهد: یک دور پیمایش ساده روی فهرست وظایف.

مسیرهای اشتباه رایج
  • «تکرار درخواست لغو تا زمانی که شیء وظیفه را برگرداند.» لغو دوم هر بار با -32002 پاسخ می‌دهد و متادیتای آن از قبل وضعیت نهایی را مشخص کرده است. این تلاش مجدد فقط زمانی متوقف می‌شود که کلاینت جلوی آن را بگیرد.
  • «ارسال پیام به وظیفه برای راه‌اندازی مجدد آن.» وضعیت یک وظیفه‌ی پایانی هرگز دوباره تغییر نمی‌کند. پیام ارسالی با خطای -32004 مواجه می‌شود. برای کار جدید باید یک وظیفه‌ی تازه ساخت و شناسه‌ی قبلی را در referenceTaskIds آورد.
  • «برداشت از کد -32004 به عنوان 'این سرور از لغو پشتیبانی نمی‌کند'.» این کد سه حالت را پوشش می‌دهد: نبود استریمینگ، نبود کارت توسعه‌یافته، و قرار داشتن وظیفه در وضعیت پایانی. پیام، متادیتا یا فراخوانی GetTask تفاوت آن‌ها را روشن می‌کند.
  • «توقف حلقه فقط روی completed، failed و canceled.» وضعیت rejected هم پایانی است. حلقه‌ای که آن را نادیده بگیرد، وظیفه‌ی ردشده را تا ابد پولینگ (polling) می‌کند.
  • «ری‌استارت کردن ایجنت.» ایجنت به تمام فراخوانی‌ها بلافاصله و با خطای درست پاسخ داد. ری‌استارت، حافظه‌ی وظایف را پاک می‌کرد و استعلام بعدی را به خطای not found تبدیل می‌نمود.
درس کلی

خطا در عملیات تغییر وضعیت یا داده (mutation) دلیلی برای تکرار کورکورانه‌ی آن نیست. وضعیتی را که در خطا آمده بخوانید، یا آن را استعلام کنید و بر اساس همان وضعیت تصمیم بگیرید. خطاهایی را که گذر زمان حل می‌کند از خطاهایی که با هیچ فراخوانی مجددی درست نمی‌شوند تفکیک کنید. بگذارید مجموعه‌ی پایانی در ماشین وضعیت (State Machine) شما به هر حلقه‌ای پایان دهد؛ حتی وضعیتی که انتظارش را نداشتید.

کجای دوره آموزش داده می‌شود

صفحه‌ی لغو وظیفه در راهنمای جامع A2A 101 این چهار تبادل را گام‌به‌گام بررسی می‌کند؛ جدول وضعیت‌ها اقدام بعدی کلاینت را برای هر وضعیت مشخص می‌سازد؛ صفحه‌ی خطاها توضیح می‌دهد که چرا یک کد سه حالت مختلف را پوشش می‌دهد؛ و درس حالت‌های شکست اثرات زنجیره‌ای ناشی از ناتوانی کلاینت در تفکیک «شکست خوردم» از «این کار شدنی نیست» را تشریح می‌کند.