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

یک ساعت سرکشی به وظیفه‌ای که منتظر ما بود

An hour of polling a task that waited for us

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

وضعیت

یک برنامه‌ریز (planner) تفاوت‌های بازنگریِ (diff) مخزن payments-api را برای ایجنت code-reviewer می‌فرستد و منتظر نتایج می‌ماند. حلقه‌ی انتظارِ آن همان حلقه‌ای است که برای همه‌ی ایجنت‌های دوردست (remote) استفاده می‌کند: ارسال پیام، و سپس فراخوانی GetTask هر چند ثانیه یک بار، تا زمانی که وضعیت به completed، failed یا canceled برسد. دیشب هیچ نتیجه‌ای از بررسی بازنگشت. برنامه‌ریز به مدت یک ساعت مدام به همان وظیفه سرکشی کرد (poll)، تا این‌که مهلت اجرای خودش تمام شد و انتشار نسخه تا صبح معطل یک بررسی‌کننده‌ی انسانی ماند.

مهندس نوبت پاسخگویی (آنکال)، اولین پاسخی را که بررسی‌کننده فرستاده بود بررسی می‌کند. پیام حاکی از شکست نبود و ایجنت هم بی‌صدا نشده بود. برنامه‌ریز می‌دانست که این diff از کدام branch گرفته شده است؛ چون خودش سورس‌کد را تحویل گرفته بود (checkout). شما دو تبادلِ مربوط به این بازنگری از بسته‌ی ثبت لاگ (capture kit)، یک نمونه تبادل سرکشی روی ایجنتی دیگر برای مقایسه، و لاگ برنامه‌ریزِ خودِ بسته را در اختیار دارید که در اجرای خودش با همین پرسش روبه‌رو شده و آن را مدیریت کرده است.

نسخه
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

شواهد

a-working-task-for-comparison.txt
title: a GetTask on a task that is still running, from another capture
source: manuals/a2a-101/capture/out/04-polling.http
lines: 77-110
lang: text
note: Compare this state and status message with the ones in the review reply.
---
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "id": "d0c28826-28b8-4b15-8b53-4e01ae7a5a3c",
    "contextId": "3afa8576-7a83-4167-bb58-01c3b0942c8f",
    "status": {
      "state": "TASK_STATE_WORKING",
      "message": {
        "messageId": "fb999be8-dce9-416b-b397-d74b090f121a",
        "contextId": "3afa8576-7a83-4167-bb58-01c3b0942c8f",
        "taskId": "d0c28826-28b8-4b15-8b53-4e01ae7a5a3c",
        "role": "ROLE_AGENT",
        "parts": [
          {
            "text": "Checking out 9f3c2e1 and starting the suite"
          }
        ]
      },
      "timestamp": "2026-10-06T09:00:01.250Z"
    },
    "artifacts": [
      {
        "artifactId": "test-log",
        "name": "test-log.txt",
        "parts": [
          {
            "text": "collected 12 items\n"
          }
        ]
      }
    ]
  }
}
completed-reply.txt
title: the reply to the answer
source: manuals/a2a-101/capture/out/06-input-required.http
lines: 104-125
lang: text
note: Same task id, new state, new status message.
---
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "task": {
      "id": "e5c95b09-6d4b-4b3b-8693-91e81472d12f",
      "contextId": "49c5a238-4158-455d-8d63-b2cb39c0ecac",
      "status": {
        "state": "TASK_STATE_COMPLETED",
        "message": {
          "messageId": "cdf017cb-27ab-4cd1-9b83-6d0995c9da8b",
          "contextId": "49c5a238-4158-455d-8d63-b2cb39c0ecac",
          "taskId": "e5c95b09-6d4b-4b3b-8693-91e81472d12f",
          "role": "ROLE_AGENT",
          "parts": [
            {
              "text": "2 findings"
            }
          ]
        },
        "timestamp": "2026-10-06T09:00:01.250Z"
      },
first-reply.txt
title: the reply to the review request
source: manuals/a2a-101/capture/out/06-input-required.http
lines: 32-53
lang: text
note: Read the state, the role of the status message, and what it asks.
---
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "task": {
      "id": "e5c95b09-6d4b-4b3b-8693-91e81472d12f",
      "contextId": "49c5a238-4158-455d-8d63-b2cb39c0ecac",
      "status": {
        "state": "TASK_STATE_INPUT_REQUIRED",
        "message": {
          "messageId": "46494a30-e224-4d71-8d6f-50c110597e3b",
          "contextId": "49c5a238-4158-455d-8d63-b2cb39c0ecac",
          "taskId": "e5c95b09-6d4b-4b3b-8693-91e81472d12f",
          "role": "ROLE_AGENT",
          "parts": [
            {
              "text": "Which base branch should I compare this diff against?"
            }
          ]
        },
        "timestamp": "2026-10-06T09:00:00.500Z"
      },
planner-log.txt
title: how the kit's planner handled the same question
source: manuals/a2a-101/capture/out/19-planner.log
lines: 7-11
lang: text
note: Five lines, from the delegation to the review result.
---
delegate review-diff to code-reviewer
  task 80bc7784 is TASK_STATE_INPUT_REQUIRED
  it asks: Which base branch should I compare this diff against? The planner answers from its own context: main
  task 80bc7784 is TASK_STATE_COMPLETED
review: 1 finding, 0 blocking
send-both-ids.txt
title: why the answer carries both ids
source: manuals/a2a-101/sections/3-1-message.md
lines: 95-95
lang: text
note: One sentence on what the implementations do with a message that names only the task.
---
Five SDKs infer the context for the agent and store the message as sent, and the reference SDK generates a new one. Send both ids, and the difference never reaches you.
state-table.txt
title: the nine states, their class, and the client's next step
source: manuals/a2a-101/sections/r-3-task-states.md
lines: 7-17
lang: text
note: Find the two interrupted rows and read their last column.
---
| State | Class | Set by | The client does next |
|---|---|---|---|
| TASK_STATE_UNSPECIFIED | none | Nobody: the zero value | Treat it, and any unknown name, as an error. |
| TASK_STATE_SUBMITTED | active | The server, on creation | Wait, poll, or subscribe. |
| TASK_STATE_WORKING | active | The agent, while it works | As for a submitted task |
| TASK_STATE_INPUT_REQUIRED | interrupted | The agent, with a question | Answer with a new message that carries the same `taskId` and `contextId`. |
| TASK_STATE_AUTH_REQUIRED | interrupted | The agent, for an authorization | Pass the request to whoever approves it, outside A2A, and subscribe, register a webhook, or poll. |
| TASK_STATE_COMPLETED | terminal | The agent, when the work is done | Read the artifacts for the result. Follow up in a new task with `referenceTaskIds`. |
| TASK_STATE_FAILED | terminal | The agent, unable to do the work | Read the status message, fix the input, and start a new task. |
| TASK_STATE_CANCELED | terminal | The agent, after `CancelTask` | Start a new task in the same context. |
| TASK_STATE_REJECTED | terminal | The agent, refusing the task | Stop the loop, and follow the status message. |
the-answer.txt
title: the message that answers the question
source: manuals/a2a-101/capture/out/06-input-required.http
lines: 82-99
lang: text
note: Read which ids the message carries and where they came from.
---
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "SendMessage",
  "params": {
    "message": {
      "messageId": "096d3737-42f9-4039-8320-a4737c2b3abe",
      "contextId": "49c5a238-4158-455d-8d63-b2cb39c0ecac",
      "taskId": "e5c95b09-6d4b-4b3b-8693-91e81472d12f",
      "role": "ROLE_USER",
      "parts": [
        {
          "text": "main"
        }
      ]
    }
  }
}

سؤال‌ها

  1. پاسخ اول حامل چه وضعیتی بود، و چه کسی پیام درون آن را نوشته بود؟
  2. با نگاه به دو بار سرکشی، یک وظیفه‌ی منتظرِ ورودی چه تفاوتی با وظیفه‌ای دارد که در حال کار است؟
  3. پاسخ برنامه‌ریز به کجا فرستاده می‌شود، و چه فیلدهایی را باید همراه داشته باشد؟
  4. یک حلقه‌ی انتظار باید روی کدام وضعیت‌ها متوقف شود، و گام بعدی برای هر یک از آن‌ها چیست؟
  5. برنامه‌ریز نام branch را در بافتار (context) خود داشت؛ چرا حلقه هرگز از آن استفاده نکرد؟

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

راه‌حل گام‌به‌گام
  1. پاسخ اول را بخوانید. وضعیت TASK_STATE_INPUT_REQUIRED است. پیام وضعیت، نقشِ ROLE_AGENT را دارد و می‌پرسد این diff باید با کدام branch مبنا مقایسه شود. یک ارسالِ مسدودکننده (blocking send) با رسیدن به وضعیتی پایانی یا وضعیتی همراه با وقفه (interrupted) بازمی‌گردد؛ بنابراین، این پرسش از همان پاسخ اول، پیش از نخستین سرکشی، در اختیار برنامه‌ریز بوده است.
  2. با یک وظیفه‌ی در حال اجرا مقایسه کنید. در لاگ سرکشی، وضعیت برابر با TASK_STATE_WORKING است، پیام وضعیت پیشرفت کار را گزارش می‌دهد، و دست‌سازه (artifact) بین هر سرکشی رشد می‌کند. یک وظیفه‌ی متوقف‌شده (parked) هیچ‌کدام از این کارها را نمی‌کند. وضعیت آن در واقع پیام ایجنت است که می‌گوید «نوبت شماست»، و هیچ تعداد سرکشی هم این وضعیت را تغییر نمی‌دهد.
  3. پاسخ ارسالی را بخوانید. این یک SendMessage معمولی است. پیام یک messageId تازه، نقشِ ROLE_USER، متنِ main، و هر دو شناسه‌ی contextId و taskId را که از وظیفه کپی شده‌اند همراه دارد. کیت توسعه‌ی مرجع (reference SDK) بافتار را از روی وظیفه استنتاج نمی‌کند و یک شناسه‌ی جدید روی آن می‌زند؛ به همین دلیل کلاینت هر دو شناسه را می‌فرستد.
  4. پاسخ دوم را بخوانید. همان شناسه‌ی وظیفه با وضعیت TASK_STATE_COMPLETED و پیام وضعیت 2 findings برمی‌گردد. تاریخچه اکنون شامل پرسش و پاسخ است، و دست‌سازه‌ی review.json نام main را به عنوان مبنا آورده و دو یافته را همراه با شماره خطوطشان فهرست کرده است. وظیفه هرگز شناسه یا بافتار خود را تغییر نداد.
  5. لاگ برنامه‌ریز را بخوانید. برنامه‌ریزِ بسته وضعیت وقفه را می‌بیند، پرسش را می‌خواند، از بافتار خودش با main پاسخ می‌دهد، و تنها با یک فراخوانیِ بعد، نتیجه‌ی بازنگری را گزارش می‌کند. وضعیت وقفه، یک شاخه (branch) در حلقه‌ی آن است، نه دلیلی برای انتظار.
  6. جدول وضعیت‌ها را بخوانید. نُه وضعیت در سه دسته قرار می‌گیرند. دو وضعیت دارای وقفه هستند و هر کدام گام بعدی متفاوتی دارند: روی همان وظیفه برای ورودی پاسخ دهید، یا درخواست را به تأییدکننده بسپارید و منتظر مجوز بمانید. چهار وضعیت پایانی (terminal) هستند، و چهارمین مورد، یعنی rejected، همان وضعیتی است که بیشترِ حلقه‌ها فراموشش می‌کنند.
نتیجه

حلقه‌ی انتظار، مجموعه‌ی توقف اشتباهی داشت. این حلقه منتظر سه وضعیت پایانی می‌ماند و با هر وضعیت دیگری مثل «هنوز در حال اجرا» برخورد می‌کرد؛ بنابراین، وظیفه‌ای که دچار وقفه شده بود کند به نظر می‌رسید. راه‌حل این است که این دو وضعیتِ همراه با وقفه به مجموعه‌ی توقف اضافه شوند و برای هر کدام یک branch جداگانه در نظر گرفته شود. برای TASK_STATE_INPUT_REQUIRED، برنامه‌ریز پیام وضعیت را می‌خواند و با پیامی تازه که شناسه‌ی وظیفه و شناسه‌ی بافتارِ وظیفه‌ی متوقف‌شده را دارد پاسخ می‌دهد. برای TASK_STATE_AUTH_REQUIRED، درخواست را به فرد تأییدکننده تحویل می‌دهد و در اشتراکِ رویدادها باقی می‌ماند یا سرکشی می‌کند. برای TASK_STATE_REJECTED، کار را متوقف می‌کند و از پیام پیروی می‌نماید. لاگ ثبت‌شده درستیِ این مسیر را اثبات می‌کند: بررسی‌کننده تنها یک فراخوانی پس از دریافت پاسخ کار را تمام کرد و دست‌سازه‌ی بازنگری را بازگرداند، و لاگ برنامه‌ریزِ بسته نیز همین شیوه‌ی مدیریت را از ابتدا تا انتها نشان می‌دهد.

مسیرهای اشتباه رایج
  • «سریع‌تر سرکشی کنید؛ بررسی‌کننده کند است.» وضعیت می‌گوید ایجنت منتظر کلاینت است. سرعت سرکشی چیزی را عوض نمی‌کند.
  • «وظیفه را رها کنید و درخواست تازه‌ای بفرستید که نام branch در آن باشد.» این کار جواب می‌دهد، اما یک وظیفه‌ی معلق روی ایجنت باقی می‌گذارد، diff را دوباره می‌فرستد، و تاریخچه را از بین می‌برد. مسیر استاندارد پروتکل، ارسال پیامی تازه روی همان وظیفه است.
  • «پاسخ را فقط با taskId بفرستید؛ سرور خودش بافتار را می‌داند.» کیت توسعه‌ی مرجع یک بافتار تازه روی چنین پیامی می‌زند. هر دو شناسه را کپی کنید.
  • «با وضعیت وقفه مانند یک شکست رفتار کنید و آن را گزارش دهید.» وظیفه، شناسه، تاریخچه و دست‌سازه‌های خود را حفظ کرده است. چیزی شکست نخورده و فقط یک پاسخ کار را تمام می‌کند.
  • «پاسخ را با نقشِ ROLE_AGENT بفرستید، چون برنامه‌ریز خودش یک ایجنت است.» نقش (role)، جهت پیام را مشخص می‌کند نه ماهیتِ فرستنده را. سمت کلاینت ROLE_USER است و کیت، نقش دیگر را با خطای -32602 رد می‌کند.
درس کلی

یک حلقه‌ی انتظار باید تمام وضعیت‌هایی را که طرف مقابل ممکن است وارد آن‌ها شود بشناسد، و باید روی هر وضعیتی که چیزی از فراخواننده می‌خواهد متوقف شود، نه فقط روی وضعیت‌هایی که کار را تمام می‌کنند. وقتی یک سیستم دوردست با طرح یک پرسش مکث می‌کند، پاسخ اغلب از قبل در بافتارِ فراخواننده وجود دارد، و حلقه‌ی انتظار تنها مانع میان این دو است.

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

در صفحه‌ی وضعیت‌های همراه با وقفه در A2A 101 این بازنگری از پرسش تا پاسخ دنبال می‌شود؛ صفحه‌ی وضعیت وظیفه و جدول وضعیت‌ها وضعیت‌های نُه‌گانه را دسته‌بندی می‌کنند؛ صفحه‌ی پیام قواعد مربوط به شناسه‌ها را شرح می‌دهد؛ و درس حالت‌های شکست (failure modes) از دست رفتن بافتار را به عنوان یکی از پنج عاملی معرفی می‌کند که حلقه‌ی ایجنت (agent loop) را از کار می‌اندازند.