سؤال مصاحبه

کلاینت A2A پیش از ارسال اولین پیام چه مواردی را بررسی می‌کند؟

What an A2A client reads before its first message

  • سطح ۱: غربالگری
  • مفهومی
  • ۷ دقیقه

ایجنت برنامه‌ریز (planner agent) شما باید اجرای یک آزمون را به ایجنتی ریموت بسپارد که فقط آدرس هاست و پورت آن را می‌داند. توضیح دهید این ایجنت ابتدا چه چیزی را دریافت می‌کند، چگونه درباره‌ی اندپوینت مدنظر برای فراخوانی تصمیم می‌گیرد، و پیش از درخواست استریمینگ از آن ایجنت چه مواردی را بررسی می‌کند.

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

پاسخ کوتاه

ایجنت ابتدا با یک درخواست GET ساده روی مسیر /.well-known/agent-card.json کارت ایجنت (Agent Card) را دریافت می‌کند. سپس از فیلد supportedInterfaces، اولین گزینه‌ای را انتخاب می‌کند که با بایندینگ (binding) و نسخه‌ی پشتیبانی‌شده توسط خودش همخوانی دارد و URL همان گزینه را فراخوانی می‌کند. پیش از اجرای SendStreamingMessage نیز مقدار capabilities.streaming را می‌خواند؛ زیرا اگر این فلگ وجود نداشته باشد یا مقدارش false باشد، سرور باید این فراخوانی را با خطای UnsupportedOperationError رد کند.

پاسخ کامل

یک درخواست GET، یک سند

مشخصات پروتکل سه روش برای دسترسی به کارت تعریف می‌کند: نشانی استاندارد و شناخته‌شده (well-known URI)، یک رجیستری یا کاتالوگ، و پیکربندی مستقیم. استاندارد فعلی فقط روش اول را رسماً مشخص کرده است. برنامه‌ریزی که هاست‌ها را در پیکربندی خود دارد، کارت هر ایجنت را از همین مسیر شناخته‌شده دریافت می‌کند.

فایل proto برای AgentCard تعداد 14 فیلد در نظر گرفته که هشت مورد از آن‌ها الزامی (REQUIRED) هستند: name، description، supportedInterfaces، version، capabilities، defaultInputModes، defaultOutputModes و skills. چهار مورد از این فیلدها از نوع لیست هستند و طبق استاندارد، هر لیست الزامی باید حداقل یک عنصر داشته باشد. اگر کارتی یکی از این موارد را نداشته باشد، آن را نامعتبر دانسته و رد کنید.

اندپوینت از لیست اینترفیس‌ها استخراج می‌شود

هر ورودی در supportedInterfaces سه فیلد الزامی دارد: url، protocolBinding و protocolVersion. این لیست مرتب است و کلاینت اولین گزینه‌ای را که پیاده‌سازی کرده و پشتیبانی می‌کند برمی‌گزیند. منظور از پشتیبانی، تطابق نوع بایندینگ و نسخه‌ی پروتکل با قابلیت‌های کلاینت است. کلاینت همچنین مقدار tenant آن ورودی را در صورت وجود، به تمام درخواست‌ها اضافه می‌کند و اگر فاقد آن بود، این فیلد را حذف می‌کند.

فلگ‌ها مشخص می‌کنند کدام عملیات‌ها مجاز هستند

فلگ موجود در capabilities عملیات‌های مجاز خطا در صورت نبود یا مقدار false
streaming SendStreamingMessage، SubscribeToTask UnsupportedOperationError با کد -32004
pushNotifications چهار عملیات مربوط به پیکربندی push PushNotificationNotSupportedError با کد -32003
extendedAgentCard GetExtendedAgentCard UnsupportedOperationError با کد -32004

اگر فلگی در این بخش وجود نداشته باشد، مقدار آن معادل false در نظر گرفته می‌شود. در گزارش خطای ثبت‌شده، ارسال درخواست پیکربندی push به ایجنتی بدون این فلگ، حتی با اینکه شناسه‌ی وظیفه (task id) اصلاً وجود نداشت، منجر به خطای -32003 شد؛ چرا که کارت ایجنت از قبل پاسخ این ماجرا را داده بود.

کش کردن مانند هر سند معمولی

کارت ایجنت به‌ندرت تغییر می‌کند. سرور باید هدر Cache-Control را همراه با max-age و ETag ارسال کند. کلاینت نیز از این هدرها پیروی می‌کند و برای اعتبارسنجی مجدد از If-None-Match بهره می‌گیرد.

سؤال‌های تکمیلی مصاحبه‌گر
  • سطح 1: کدام فیلد مشخص می‌کند ایجنت چه کارهایی می‌تواند انجام دهد؟ پاسخ مورد انتظار: فیلد skills، که هر مهارت شامل id، name، description و حداقل یک تگ است؛ انتخاب ایجنت بر اساس همین مهارت‌ها و حالت‌های رسانه (media modes) انجام می‌شود.
  • سطح 2: در کارتی گزینه‌ی اول gRPC و گزینه‌ی دوم JSON-RPC ذکر شده، اما کلاینت شما فقط JSON-RPC را می‌فهمد. کدام URL را فراخوانی می‌کنید؟ پاسخ مورد انتظار: آدرس مربوط به JSON-RPC؛ زیرا طبق قاعده، اولین گزینه‌ای انتخاب می‌شود که شما از آن پشتیبانی می‌کنید.
  • سطح 2: انواع رسانه‌ها (media types) چگونه به ایجنت می‌رسند؟ پاسخ مورد انتظار: از طریق defaultInputModes و defaultOutputModes موجود در کارت، فیلدهای اختصاصی هر مهارت شامل inputModes و outputModes، و فیلد mediaType در هر بخشی (part) که کلاینت ارسال می‌کند.
  • سطح 3: شما یک توکن حامل (bearer token) دارید و کارت نیز فلگ extendedAgentCard را فعال کرده است. چه تغییری ایجاد می‌شود؟ پاسخ مورد انتظار: متد GetExtendedAgentCard را همراه با اطلاعات احراز هویت اعلام‌شده فراخوانی کنید و کارت کامل‌تر را برای آن نشست (Session) یا تا زمانی که version کارت تغییر نکرده، جایگزین نسخه‌ی عمومیِ کش‌شده قرار دهید.
جواب‌های اشتباهی که مصاحبه‌گرها زیاد می‌شنوند
  • «خواندن فیلد url در ریشه‌ی کارت.» نسخه‌ی فعلی اندپوینت را به supportedInterfaces منتقل کرده است و فیلد url در سطح ریشه وجود ندارد.
  • «تست کردن استریم و برگشت به حالت قبل در صورت بروز خطا.» فلگ قابلیت‌ها پاسخ این پرسش را از پیش داده است؛ ارسال درخواستی ناموفق صرفاً یک رفت‌وبرگشت شبکه‌ای بیهوده تحمیل می‌کند.
  • «قرار دادن شناسه‌ی مهارت در پیام تا سرور همان مهارت را اجرا کند.» هیچ فیلدی در SendMessageRequest یا Message برای مشخص کردن نام مهارت وجود ندارد؛ فهرست مهارت‌ها صرفاً برای شناسایی و توصیف قابلیت‌های ایجنت است.

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

فهرست فیلدها در بخش فیلدهای AgentCard و قواعد رابط‌ها به‌همراه جدول فلگ‌ها در بخش شناسایی (Discovery) و رابط‌های پشتیبانی‌شده بررسی شده‌اند.