ایجنت برنامهریز (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) و رابطهای پشتیبانیشده بررسی شدهاند.