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

قطع استریمینگ، مجموعه‌ی تست را دو بار اجرا کرد

A dropped stream ran the suite twice

  • سطح ۳: ارشد
  • سناریوی رخداد
  • ۲۵ دقیقه

وضعیت

یک برنامه‌ریز (planner) از طریق استریمینگی از ایجنت test-runner، روند اجرای یک مجموعه‌ی تست طولانی را زیر نظر دارد. یک لودبالانسر (load balancer) میان آن‌ها قرار گرفته که اتصالاتِ طولانی‌مدت را می‌بندد. کنترل‌کننده‌ی استریم در برنامه‌ریز، از یک کلاینت REST آمده است و در مواجهه با قطعی ارتباط پیش از رسیدن فریم نهایی فقط یک قانون دارد: درخواست را دوباره بفرست. دیروز مجموعه‌ی تستِ payments-api با هر بار قطع اتصال دو بار اجرا شد. این اتفاق هزینه‌ی CI را دو برابر کرد و یک تست ناپایدار (flaky test) که بار اول پاس شده بود، در اجرای دوم رد شد و جلوی انتشار نسخه را گرفت.

یکی از هم‌تیمی‌ها کنترل‌کننده را پچ کرد تا پس از قطع ارتباط، متد SubscribeToTask را صدا بزند و در صورت بروز هر خطایی، همان فراخوانی را مجدداً تلاش کند. دفعه‌ی بعد، پیش از اتصال مجدد کنترل‌کننده، وظیفه (task) به پایان رسیده بود؛ در نتیجه فراخوانی با خطا روبه‌رو شد، کنترل‌کننده لاگ زد که «این سرور از سابسکرایب پشتیبانی نمی‌کند» و قابلیت استریمینگ را برای آن ایجنت خاموش کرد. شما داده‌های ضبط‌شده‌ی همین سناریو را در اختیار دارید: استریمی که کلاینت پس از چهار فریم می‌بندد، فراخوانی‌ای که آن را ادامه می‌دهد، و فراخوانی سومی که پس از اتمام کار انجام می‌گیرد.

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

شواهد

first-stream.txt
title: the first stream, four frames, then the client closes the connection
source: manuals/a2a-101/capture/out/14-resubscribe.http
lines: 25-36
lang: text
note: Each data line is one complete frame. Read the state in frame 1 and 2, the artifact in frames 3 and 4, and the last line.
---
HTTP/1.1 200 OK
Content-Type: text/event-stream

data: {"jsonrpc": "2.0", "id": 1, "result": {"task": {"id": "25239d4c-798b-4754-be06-d1f94d0645b1", "contextId": "ed92749e-5686-4e20-a1cf-d3b2aee3b1da", "status": {"state": "TASK_STATE_SUBMITTED", "timestamp": "2026-10-06T09:00:04.000Z"}, "history": [{"messageId": "c15521b1-b3dc-450a-9daa-37e51b591d75", "contextId": "ed92749e-5686-4e20-a1cf-d3b2aee3b1da", "taskId": "25239d4c-798b-4754-be06-d1f94d0645b1", "role": "ROLE_USER", "parts": [{"text": "Run the full suite for payments-api at commit 9f3c2e1"}]}]}}}

data: {"jsonrpc": "2.0", "id": 1, "result": {"statusUpdate": {"taskId": "25239d4c-798b-4754-be06-d1f94d0645b1", "contextId": "ed92749e-5686-4e20-a1cf-d3b2aee3b1da", "status": {"state": "TASK_STATE_WORKING", "message": {"messageId": "47206245-9085-4c5c-9899-3f2b41a7a980", "contextId": "ed92749e-5686-4e20-a1cf-d3b2aee3b1da", "taskId": "25239d4c-798b-4754-be06-d1f94d0645b1", "role": "ROLE_AGENT", "parts": [{"text": "Checking out 9f3c2e1 and starting the suite"}]}, "timestamp": "2026-10-06T09:00:04.250Z"}}}}

data: {"jsonrpc": "2.0", "id": 1, "result": {"artifactUpdate": {"taskId": "25239d4c-798b-4754-be06-d1f94d0645b1", "contextId": "ed92749e-5686-4e20-a1cf-d3b2aee3b1da", "artifact": {"artifactId": "test-log", "name": "test-log.txt", "parts": [{"text": "tests/test_suite_01.py ........\n"}]}}}}

data: {"jsonrpc": "2.0", "id": 1, "result": {"artifactUpdate": {"taskId": "25239d4c-798b-4754-be06-d1f94d0645b1", "contextId": "ed92749e-5686-4e20-a1cf-d3b2aee3b1da", "artifact": {"artifactId": "test-log", "parts": [{"text": "tests/test_suite_02.py ........\n"}]}, "append": true}}}

# the client closes the connection after 4 events
message-id-rule.txt
title: what a repeated messageId does on every implementation
source: manuals/a2a-101/sections/3-1-message.md
lines: 84-84
lang: text
note: Read the last sentence.
---
Send Message operations are allowed to be idempotent, and an agent can use the `messageId` to find duplicate messages {{spec §3.3.1}}. So a retry of a send that timed out can reuse the same `messageId`. No SDK rejects a repeated id, and without a `taskId` each one creates another task for it.
resumed-stream.txt
title: the second stream, six frames to the end
source: manuals/a2a-101/capture/out/14-resubscribe.http
lines: 54-67
lang: text
note: Read the member of frame 1, the test file names in frames 2 to 5, and the state in frame 6.
---
HTTP/1.1 200 OK
Content-Type: text/event-stream

data: {"jsonrpc": "2.0", "id": 2, "result": {"task": {"id": "25239d4c-798b-4754-be06-d1f94d0645b1", "contextId": "ed92749e-5686-4e20-a1cf-d3b2aee3b1da", "status": {"state": "TASK_STATE_WORKING", "message": {"messageId": "47206245-9085-4c5c-9899-3f2b41a7a980", "contextId": "ed92749e-5686-4e20-a1cf-d3b2aee3b1da", "taskId": "25239d4c-798b-4754-be06-d1f94d0645b1", "role": "ROLE_AGENT", "parts": [{"text": "Checking out 9f3c2e1 and starting the suite"}]}, "timestamp": "2026-10-06T09:00:04.250Z"}, "history": [{"messageId": "c15521b1-b3dc-450a-9daa-37e51b591d75", "contextId": "ed92749e-5686-4e20-a1cf-d3b2aee3b1da", "taskId": "25239d4c-798b-4754-be06-d1f94d0645b1", "role": "ROLE_USER", "parts": [{"text": "Run the full suite for payments-api at commit 9f3c2e1"}]}], "artifacts": [{"artifactId": "test-log", "name": "test-log.txt", "parts": [{"text": "tests/test_suite_01.py ........\n"}, {"text": "tests/test_suite_02.py ........\n"}, {"text": "tests/test_suite_03.py ........\n"}, {"text": "tests/test_suite_04.py ........\n"}]}]}}}

data: {"jsonrpc": "2.0", "id": 2, "result": {"artifactUpdate": {"taskId": "25239d4c-798b-4754-be06-d1f94d0645b1", "contextId": "ed92749e-5686-4e20-a1cf-d3b2aee3b1da", "artifact": {"artifactId": "test-log", "parts": [{"text": "tests/test_suite_05.py ........\n"}]}, "append": true}}}

data: {"jsonrpc": "2.0", "id": 2, "result": {"artifactUpdate": {"taskId": "25239d4c-798b-4754-be06-d1f94d0645b1", "contextId": "ed92749e-5686-4e20-a1cf-d3b2aee3b1da", "artifact": {"artifactId": "test-log", "parts": [{"text": "tests/test_suite_06.py ........\n"}]}, "append": true}}}

data: {"jsonrpc": "2.0", "id": 2, "result": {"artifactUpdate": {"taskId": "25239d4c-798b-4754-be06-d1f94d0645b1", "contextId": "ed92749e-5686-4e20-a1cf-d3b2aee3b1da", "artifact": {"artifactId": "test-log", "parts": [{"text": "tests/test_suite_07.py ........\n"}]}, "append": true}}}

data: {"jsonrpc": "2.0", "id": 2, "result": {"artifactUpdate": {"taskId": "25239d4c-798b-4754-be06-d1f94d0645b1", "contextId": "ed92749e-5686-4e20-a1cf-d3b2aee3b1da", "artifact": {"artifactId": "test-log", "parts": [{"text": "tests/test_suite_08.py ........\n"}]}, "append": true, "lastChunk": true}}}

data: {"jsonrpc": "2.0", "id": 2, "result": {"statusUpdate": {"taskId": "25239d4c-798b-4754-be06-d1f94d0645b1", "contextId": "ed92749e-5686-4e20-a1cf-d3b2aee3b1da", "status": {"state": "TASK_STATE_COMPLETED", "message": {"messageId": "b9264586-875b-4914-992a-7a26235a16ba", "contextId": "ed92749e-5686-4e20-a1cf-d3b2aee3b1da", "taskId": "25239d4c-798b-4754-be06-d1f94d0645b1", "role": "ROLE_AGENT", "parts": [{"text": "96 passed"}]}, "timestamp": "2026-10-06T09:00:04.500Z"}}}}
snapshot-artifacts.txt
title: the artifact inside the first frame of the second stream
source: manuals/a2a-101/capture/out/14-resubscribe.events.json
lines: 137-157
lang: text
note: Count the parts and compare them with the two the first stream carried.
---
            "artifacts": [
              {
                "artifactId": "test-log",
                "name": "test-log.txt",
                "parts": [
                  {
                    "text": "tests/test_suite_01.py ........\n"
                  },
                  {
                    "text": "tests/test_suite_02.py ........\n"
                  },
                  {
                    "text": "tests/test_suite_03.py ........\n"
                  },
                  {
                    "text": "tests/test_suite_04.py ........\n"
                  }
                ]
              }
            ]
          }
subscribe-after-completion-reason.txt
title: the detail inside that error
source: manuals/a2a-101/capture/out/14-resubscribe.http
lines: 97-105
lang: text
note: The reason and the state in the metadata.
---
        "reason": "UNSUPPORTED_OPERATION",
        "domain": "a2a-protocol.org",
        "metadata": {
          "taskId": "25239d4c-798b-4754-be06-d1f94d0645b1",
          "state": "TASK_STATE_COMPLETED"
        }
      }
    ]
  }
subscribe-after-completion.txt
title: a third SubscribeToTask after the task completed, status and code
source: manuals/a2a-101/capture/out/14-resubscribe.http
lines: 85-95
lang: text
note: Read the content type and the code.
---
HTTP/1.1 200 OK
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 3,
  "error": {
    "code": -32004,
    "message": "This operation is not supported",
    "data": [
      {
subscribe-request.txt
title: the request that picks the stream back up
source: manuals/a2a-101/capture/out/14-resubscribe.http
lines: 38-52
lang: text
note: Compare the method and the params with the first request. There is no message here.
---
### 2 · SubscribeToTask: pick the stream back up
POST /a2a/jsonrpc HTTP/1.1
Host: localhost:41241
Content-Type: application/json
A2A-Version: 1.0
Accept: text/event-stream

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "SubscribeToTask",
  "params": {
    "id": "25239d4c-798b-4754-be06-d1f94d0645b1"
  }
}

سؤال‌ها

  1. پس از بسته شدن استریم اول در فریم چهارم، چه بر سر وظیفه می‌آید و رویدادهایی که ایجنت در ادامه صادر می‌کند چه می‌شوند؟
  2. تفاوت این دو درخواست چیست و چرا یکی از آن‌ها کار جدیدی ایجاد می‌کند و دیگری نه؟
  3. فریم اولِ استریم دوم شامل چیست و کلاینت چطور آن را با داده‌هایی که پیش‌تر داشت merge می‌کند؟
  4. فراخوانی سوم خطا برمی‌گرداند. معنای آن چیست و فراخوانی بعدی باید چه باشد؟
  5. آیا یک messageId تکراری در این سناریو از برنامه‌ریز محافظت می‌کند؟ چرا بله یا چرا خیر؟

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

راه‌حل گام‌به‌گام
  1. بررسی استریم اول. چهار فریم دریافت می‌شود: یک task با وضعیت TASK_STATE_SUBMITTED، یک statusUpdate به وضعیت TASK_STATE_WORKING، یک artifactUpdate که فایل test-log.txt را با اولین فایل تست باز می‌کند، و یک artifactUpdate که فایل دوم را به آن می‌افزاید. سپس یادداشت پکیج نشان می‌دهد که کلاینت ارتباط را بسته است. هیچ فریمی وضعیت نهایی را حمل نکرده، بنابراین وظیفه زنده است. چرخه‌ی حیات وظیفه وابسته به هیچ استریم خاصی نیست. ایجنت کارش را ادامه می‌دهد و دو فایل دیگر را به دست‌سازه‌ی ذخیره‌شده‌ی خود اضافه می‌کند، اما این رویدادها ارتباط بازی برای انتقال در اختیار ندارند.
  2. بررسی درخواست دوم. متد ارسالی SubscribeToTask است و پارامترها فقط شناسه‌ی وظیفه را دارند. خبری از پیام یا messageId نیست. این فراخوانی پنجره‌ای به سمت کارِ در حال اجرا باز می‌کند و هیچ چیز جدیدی نمی‌سازد. در مقابل، کنترل‌کننده‌ی قبلی برنامه‌ریز یک SendStreamingMessage جدید می‌فرستاد؛ و پیامی که taskId نداشته باشد، هر بار یک وظیفه‌ی جدید خلق می‌کند.
  3. بررسی استریم دوم. فریم اول یک شیء کامل task است که همچنان در وضعیت TASK_STATE_WORKING قرار دارد. دست‌سازه‌ی test-log آن از قبل شامل چهار بخش است: test_suite_01 تا test_suite_04؛ یعنی همان دو فایلی را هم که استریم اول هرگز منتقل نکرد، در بر دارد. فریم‌های 2 تا 5 بخش‌های test_suite_05 تا test_suite_08 را اضافه می‌کنند و آخرین فریم فلگ lastChunk را فعال می‌کند. فریم ششم یک statusUpdate به وضعیت TASK_STATE_COMPLETED با پیام 96 passed است. هیچ رویدادی بازپخش (replay) نمی‌شود و پروتکل نیز هیچ مکان‌نمایی (cursor) ندارد. کلاینت لاگ ناقص قبلی‌اش را با دست‌سازه‌ی اسنپ‌شات (snapshot) جایگزین می‌کند و سپس فریم‌های بعدی را به ادامه‌ی آن می‌افزاید.
  4. بررسی فراخوانی سوم. پاسخ با هدر Content-Type: application/json می‌آید، نه یک استریم رویداد. پاسخ یک error با کد -32004 و دلیل UNSUPPORTED_OPERATION است، و فراداده (metadata) نام وضعیت را TASK_STATE_COMPLETED ذکر می‌کند. این خطا نشان‌دهنده‌ی رسیدن وظیفه به وضعیت نهایی است، نه نبودِ یک قابلیت در سرور. کلاینت تلاش مجدد برای اتصال را متوقف می‌کند و وظیفه‌ی نهایی را با GetTask می‌خواند.
  5. بررسی قاعده‌ی شناسه. تلاش مجدد برای ارسالی که پاسخش هرگز نیامده، ممکن است از همان messageId دوباره استفاده کند. هیچ پیاده‌سازی خاصی شناسه‌ی تکراری را رد نمی‌کند؛ بنابراین هر نسخه بدون taskId یک وظیفه‌ی جدید می‌سازد. در نتیجه، این شناسه برنامه‌ریز را تنها در برابر درخواستی محافظت می‌کند که ممکن است به مقصد نرسیده باشد. در این سناریو، وظیفه وجود دارد، کلاینت شناسه‌ی آن را در دست دارد، و فراخوانی درست یک سابسکرایب است، نه ارسال پیام.
نتیجه

علت اجرای دوباره، منطق اتصال مجدد بود. متد SendStreamingMessage هم‌زمان یک دستور به‌علاوه‌ی یک پنجره‌ی مشاهده است؛ ارسال مجدد دستور، اجرای کار را تکرار می‌کند. راهکار اصلاحی چهار بخش دارد: بسته‌شدن اتصال صرفاً به معنای پایان خواندن است و نه چیز دیگر. اگر آخرین فریم حاوی وضعیت نهایی نبود، کنترل‌کننده باید SubscribeToTask را همراه با شناسه‌ی وظیفه صدا بزند. سپس نسخه‌ی محلی‌اش را بر اساس اسنپ‌شات task در فریم اول بازسازی کند و داده‌های بعدی را به آن بیفزاید. با دریافت خطای -32004، تلاش برای اتصال را متوقف کند و GetTask را فرا بخواند. داده‌های ضبط‌شده اثبات (proof) ماجرا هستند: یک شناسه‌ی وظیفه‌ی یکسان در هر دو استریم جریان دارد، استریم ازسرگرفته‌شده چهار فایل جاافتاده و پیام نهایی 96 passed را تحویل می‌دهد، و ایجنت کل مجموعه را فقط یک بار اجرا می‌کند.

مسیرهای اشتباه رایج
  • «وقتی ارتباط قطع شد، درخواست را دوباره بفرست.» درخواست حامل پیام است و پیام بدون شناسه‌ی وظیفه، کار جدیدی را آغاز می‌کند. در نتیجه، مجموعه‌ی تست دوباره اجرا می‌شود.
  • «با همان messageId دوباره بفرست تا سرور پیام تکراری را نادیده بگیرد.» تشخیص پیام تکراری اختیاری است؛ هیچ پیاده‌سازی‌ای شناسه‌ی تکراری را رد نمی‌کند و هر نسخه‌ی بدون شناسه‌ی وظیفه، کار جدیدی می‌سازد.
  • «اتصال بسته شد، پس کار تمام است.» فقط ثبت وضعیت نهایی در یک فریم نشانه‌ی پایان وظیفه است. این ابزار هنگام درخواست ورودی نیز اتصال را می‌بندد، و زمان قطع اتصال در سرورهای مختلف تفاوت دارد. بعد از هر بار بسته‌شدن، GetTask را صدا بزنید.
  • «کد خطای -32004 یعنی این سرور از SubscribeToTask پشتیبانی نمی‌کند.» فراداده وضعیت تکمیل‌شده را مشخص کرده است. برای دریافت نتیجه کافی است GetTask فراخوانی شود.
  • «فریم‌های جدید را به انتهای همان لاگ ناقص قدیمی بچسبان.» دو فایل در زمانی که هیچ ارتباطی باز نبود نوشته شده‌اند. اسنپ‌شات آن‌ها را دارد، پس ابتدا نسخه‌ی قبلی را جایگزین کنید و بعد داده‌های جدید را بیفزایید.
درس کلی

همیشه میان اجرای کار و مشاهده‌ی کار تمایز قائل شوید. دستوری که کاری را ایجاد می‌کند باید فقط یک بار فرستاده شود؛ در اتصال مجدد، باید پنجره‌ی مشاهده را بر اساس شناسه‌ی کار باز کرد، نه اینکه کل دستور را از نو فرستاد. فرآیند را از اسنپ‌شاتی که در اختیار سرور است ادامه دهید و پایان کار را از وضعیت نهایی در خود داده‌ها بفهمید، نه از قطع شدن اتصال.

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

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