سؤال مصاحبه

دو خطا از کلاینتی که نسخه‌گذاری را فراموش کرده است

Two errors from a client that forgot the version

  • سطح ۲: میانی
  • اشکال‌یابی
  • ۸ دقیقه

کلاینتی که بر اساس یکی از نسخه‌های قدیمی A2A نوشته شده است، یک ایجنت (Agent) امروزی را صدا می‌زند. اولین فراخوانی SendMessage آن فقط هدرهای Host و Content-Type را ارسال می‌کند و پاسخ HTTP 200 را همراه با یک خطای JSON-RPC با کد -32009 تحویل می‌گیرد. فراخوانی دوم آن، هدر A2A-Version: 1.0 را می‌فرستد، نام متد را message/send می‌گذارد و با کد -32601 مواجه می‌شود. هر دو پاسخ را توضیح دهید و بگویید کلاینت باید چه دو تغییری ایجاد کند.

اول خودتان جواب بدهید، بعد پاسخ را باز کنید.

پاسخ کوتاه

هر دو پاسخ از سوی یک سرور نسخه‌ی جدید بازگردانده شده‌اند که در حال پردازش درخواستی از یک کلاینت قدیمی است. نبودِ هدر A2A-Version طبق پروتکل باید نسخه‌ی 0.3 تلقی شود، و رابطی که فقط از 1.0 پشتیبانی می‌کند خطای VersionNotSupportedError را برمی‌گرداند؛ در اجرای ثبت‌شده، درخواست به‌صورت 0.3 (no header) در برابر supported: 1.0 گزارش شده است. از سوی دیگر، message/send نام قدیمی متد است، در حالی که نسخه‌ی 1.0 از نام‌های rpc با فرمت PascalCase مثل SendMessage استفاده می‌کند؛ بنابراین فراخوانی دوم با خطای «متد پیدا نشد» روبه‌رو می‌شود. کلاینت باید در تمام درخواست‌ها A2A-Version: 1.0 را ارسال کند و نام متدها را هم به نام‌های نسخه‌ی 1.0 تغییر دهد.

پاسخ کامل

هدر نسخه

A2A-Version و A2A-Extensions جزو پارامترهای سرویس هستند. این پارامترها در اتصالات JSON-RPC و HTTP+JSON در قالب هدرهای درخواست HTTP، و در gRPC به‌صورت کلیدهای متاداده با حروف کوچک منتقل می‌شوند. نسخه در قالب Major.Minor مشخص می‌شود و درخواست‌ها، پاسخ‌ها و کارت‌ها نباید شماره‌ی پچ (Patch) داشته باشند. سرور دو وظیفه دارد: پردازش درخواست با قواعد معنایی همان نسخه، و برگرداندن خطای VersionNotSupportedError در صورتی که رابط از آن نسخه پشتیبانی نکند. این خطا در JSON-RPC با کد -32009، در HTTP+JSON با کد 400 و در gRPC با وضعیت FAILED_PRECONDITION برگردانده می‌شود.

هرگز فرض نکنید که اگر هدر وجود نداشته باشد، سرور حتماً درخواست را رد می‌کند. در بررسی و مقایسه‌ی ثبت‌شده میان SDKها، یکی از سرورها اصلاً هدر را نمی‌خواند و سروری دیگر هم نبودِ هدر را معادل 1.0 در نظر می‌گیرد. علاوه بر این، سه نمونه‌کد در خود سند مشخصات هنوز مقدار قدیمی را می‌فرستند؛ بنابراین مقدار نسخه را مستقیماً از فیلد protocolVersion کارت بردارید، نه از نمونه‌کدها.

سایر تغییرات اعمال‌شده

بخش قدیم 1.0
نام متدها message/send، tasks/get، tasks/resubscribe SendMessage، GetTask، SubscribeToTask
وضعیت‌های وظیفه (Task) و نقش‌ها "working"، "user" TASK_STATE_WORKING، ROLE_USER
پارت‌ها (Parts) TextPart، FilePart، DataPart به همراه فیلد kind یک ساختار واحد Part که یکی از اعضای text، raw، url یا data نوع آن را مشخص می‌کند
پایان استریم مقدار final: true روی آخرین به‌روزرسانی وضعیت بستر انتقال (Transport) استریم را می‌بندد
اندپوینت (Endpoint) کارت فیلدهای url، preferredTransport، additionalInterfaces آرایه‌ی supportedInterfaces[] همراه با url، protocolBinding، protocolVersion
خطاها ساختار problem details شیء Status به همراه جزئیات ErrorInfo، به‌علاوه‌ی کدهای خطای -32008 و -32009

تغییری که در راهنمای مهاجرت نیامده است

در گذشته مقدار پیش‌فرض پرچم blocking برابر با false بود؛ در نتیجه عملیات ارسال بلافاصله برمی‌گشت. جایگزین جدید آن، یعنی returnImmediately هم به‌طور پیش‌فرض false است، با این تفاوت که در نسخه‌ی جدید false بودن به این معناست که فراخوانی منتظر می‌ماند تا وظیفه به وضعیت نهایی برسد یا دچار وقفه (Interrupt) شود. کلاینتی که به نسخه‌ی جدید مهاجرت کرده و می‌خواهد بعد از ارسال، وضعیت را به‌صورت دوره‌ای استعلام کند (Polling)، باید حتماً مقدار returnImmediately: true را تنظیم کند؛ وگرنه یک درخواست تا تمام‌شدن کل وظیفه باز می‌ماند.

سرویس‌دهی به کلاینت‌های قدیمی در دوران همپوشانی (Overlap)

هر SDK یک لایه‌ی سازگاری با 0.3 دارد. SDK مرجع روی سازنده‌های مسیر (Route builders) خود یک پرچم دریافت می‌کند، یک رابط دوم به نام AgentInterface با مقدار 0.3 برای protocolVersion به کارت اضافه می‌کند، و قبل از بررسی نسخه، مسیریابی را بر اساس نام متد انجام می‌دهد. بقیه‌ی SDKها مسیریابی را با هدر یا با یک URL دوم پیش می‌برند. در مواردی که راهنمای مهاجرت نام فیلدی را آورده ولی آن فیلد در فایل proto وجود ندارد، مرجع اصلی و قطعی همان فایل proto است.

سؤال‌های تکمیلی مصاحبه‌گر
  • سطح 2: چرا باید 1.0 فرستاده شود و نه نسخه‌ی انتشار مثل 1.0.1؟ پاسخ مورد انتظار: فرمت نسخه Major.Minor است؛ هیچ شماره‌ی پچی در درخواست‌ها، پاسخ‌ها یا کارت‌ها منتقل نمی‌شود.
  • سطح 3: بعد از اعمال این تغییرات، فراخوانی‌های ارسال کلاینت تا پایان کار هر وظیفه معلق می‌مانند. علت چیست؟ پاسخ مورد انتظار: مقدار پیش‌فرض blocking قبلاً false بود و پیش‌فرض returnImmediately جدید هم false است، که حالا یعنی منتظر بمان؛ باید آن را روی true تنظیم کنید و بعد استعلام دوره‌ای (Poll) بگیرید یا اشتراک (Subscribe) ایجاد کنید.
  • سطح 3: آیا همه‌ی سرورها درخواستی را که هیچ هدری از نسخه ندارد رد می‌کنند؟ پاسخ مورد انتظار: خیر؛ یک SDK اصلاً هدر را نمی‌خواند و یکی دیگر هم نبودِ آن را قبول می‌کند، بنابراین کلاینت باید در تمام فراخوانی‌ها آن را بفرستد.
  • سطح 4: باید برای مدت یک فصل (سه ماه) هم‌زمان به کلاینت‌های قدیمی و جدید سرویس بدهید. سمت سرور چه تغییراتی می‌دهید؟ پاسخ مورد انتظار: لایه‌ی 0.3 را در SDK فعال کنید، رابط دومی با protocolVersion برابر با 0.3 به کارت اضافه کنید، و بسته به سازوکار آن SDK، مسیریابی را بر اساس هدر، نام متد یا URL انجام دهید.
جواب‌های اشتباهی که مصاحبه‌گرها زیاد می‌شنوند
  • «کد وضعیت HTTP 200 یعنی فراخوانی موفقیت‌آمیز بوده است.» خطاهای JSON-RPC داخل پاسخ 200 برگردانده می‌شوند؛ باید عضو error را قبل از result بررسی کنید.
  • «به‌جای هدر، نسخه را در قالب query parameter بفرستید.» هر دو اتصال مبتنی بر JSON به هدر نیاز دارند و SDK مرجع هم فقط هدر را می‌خواند.
  • «نام متد به بزرگی و کوچکی حروف حساس نیست.» نام‌ها دقیقاً نام‌های rpc با فرمت PascalCase هستند و فرمت قدیمی اسلش‌دار برای سرور نسخه‌ی 1.0 کاملاً ناشناخته است.

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

بخش هدر نسخه خطای ثبت‌شده‌ی -32009 و رفتار هر کدام از SDKها را توضیح می‌دهد، و بخش مهاجرت جدول تطبیق همه‌ی فیلدهای تغییرنام‌یافته را آورده است.