تصور کنید یک برنامه‌نویس بخواهد عاملی بسازد که به ۱۰۰ ابزار مختلف دسترسی داشته باشد؛ در این حالت، مدل به‌جای تمرکز بر پاسخ، در میان انبوهی از توصیفات فنی غرق می‌شود. این همان نقطه‌ای است که «انفجار زمینه» (Context Blow-up) رخ می‌دهد و صورت‌حساب توکن‌های شما به‌طور غیرمنتظره‌ای جهش می‌کند. وقتی یک عامل به‌طور هم‌زمان با ۸۰ ابزار روبه‌رو می‌شود، دقت در انتخاب ابزار به‌شدت افت می‌کند و یک درخواست ساده برای «بررسی وضعیت سفارش»، ممکن است ناگهان نیمی از فضای OpenAPI یک شرکت را در پنجره متنی اشغال کند.
طبق مستندات فنی Solon AI، این مشکل در نسخه ۴.۰.۳ با جایگزینی لیست‌های ایستا با مکانیزم کشف پویا به نام Gateway Talents حل شده است. این سیستم که توسط ماژول solon-ai-talent-gateway مدیریت می‌شود، به‌جای تحمیل تمام طرح‌واره‌های (Schema) API به مدل در اولین گام، پیچیدگی‌ها را به‌صورت تدریجی پنهان می‌کند تا مدل تنها با آنچه در لحظه نیاز دارد مواجه شود.
برخی توسعه‌دهندگان ابزارها را صرفاً توابعی اتمیک می‌بینند، اما در مقیاس صنعتی، حجم عظیم مشخصات OpenAPI می‌تواند استدلال مدل را مختل کند. در این معماری، «ابزار» (Tool) یک تابع اتمیک است، اما «استعداد» (Talent) مجموعه‌ای از ابزارهاست که با دستورالعمل‌ها، مکانیزم‌های فعال‌سازی و محدودیت‌های سبک SOP (روش اجرای استاندارد) بسته‌بندی شده‌اند. گیت‌وی‌ها به این بسته‌بندی نیاز دارند زیرا طرح‌واره‌های خام بیش از حد زیاد هستند و ابزارهای سیستم‌های مختلف نیاز به گروه‌بندی و مدیریت چرخه حیات دارند. به همین دلیل، گیت‌وی‌ها به‌جای ریختن تمام عملیات‌ها در defaultToolAdd توسط متد defaultTalentAdd(...) (یا talentAdd در محدوده درخواست) پیاده‌سازی می‌شوند.
چهار مرحله کشف تطبیقی
بر اساس بررسی منابع متعدد و مستندات مقالات ۱۳۵۳، ۱۳۸۹، ۱۳۳۵ و ۱۲۹۳، تمامی گیت‌وی‌ها از یک مدل چهار مرحله‌ای کشف تطبیقی پیروی می‌کنند. هدف این طراحی آن است که کاتالوگ‌های کوچک در دستورالعمل‌ها جای گیرند تا فراخوانی‌ها تک‌مرحله‌ای باشند، در حالی که کاتالوگ‌های بزرگ به‌صورت لایه‌لایه جمع شوند تا مدل مجبور به کشف تدریجی شود:
- حالت FULL (تعداد ≤ dynamicThreshold، پیش‌فرض ۸): مدل تمام طرح‌واره‌های کامل ابزارها یا ابزارهای اصلی را دریافت می‌کند. در این مرحله، عملیات‌های OpenAPI به یک ابزار ساده به نام
call_apiتبدیل (Collapse) می‌شوند. - حالت SUMMARY (۸ < تعداد ≤ listThreshold، پیش‌فرض ۳۰ برای OpenAPI و ۴۰ برای سایرین): سیستم تنها نام ابزارها، توضیحات و نقطه اتصال (Endpoint) را ارائه می‌دهد. مدل ابزارهای
get_*_detailوcall_*را می‌بیند و برای اجرای یک ابزار، ابتدا باید از طریق یک فراخوانی Detail، طرح‌واره کامل آن را مشاهده کند. - حالت LIST (listThreshold < تعداد ≤ searchThreshold، پیش‌فرض ۱۰۰): در این مرحله تنها نام‌های گروه‌بندی شده نمایش داده می‌شوند. مدل به ابزارهای
search_*(جست‌وجو)،get_*_detail(دریافت جزئیات) وcall_*(اجرا) دسترسی دارد. - حالت SEARCH (تعداد > ۱۰۰): هیچ کاتالوگی به مدل ارسال نمی‌شود. مدل به‌طور اجباری باید مسیر جست‌وجوی مشخصی را طی کند: ابتدا استفاده از
search_*$\rightarrow$ سپسget_*_detail$\rightarrow$ و در نهایتcall_*.
اهرم‌های تنظیمات برای توسعه‌دهندگان
توسعه‌دهندگان می‌توانند نقاط گذار بین این چهار مرحله را با استفاده از چندین متد مشترک تنظیم کنند:
dynamicThreshold(n): سقف تعداد برای فعال ماندن حالت FULL (پیش‌فرض ۸).listThreshold(n): سقف تعداد برای حالت SUMMARY (پیش‌فرض ۳۰ برای OpenAPI و ۴۰ برای سایر موارد).searchThreshold(n): سقف تعداد برای حالت LIST (پیش‌فرض ۱۰۰).retryConfig(maxRetries, retryDelayMs): مدیریت بازیابی در صورت شکست فراخوانی (پیش‌فرض ۳ بار تلاش با تأخیر ۱۰۰۰ میلی‌ثانیه).maxContextLength(n): این تنظیم به‌طور خاص برایOpenApiGatewayTalentاست تا پاسخ‌های بسیار طولانی را برای جلوگیری از پر شدن Context قطع (Truncate) کند (پیش‌فرض ۸۰۰۰).
سه نوع گیت‌وی تخصصی
Solon AI سه پیاده‌سازی متمایز از گیت‌وی را بر اساس منبع پیدایش ابزارها ارائه می‌دهد:
۱. OpenApiGatewayTalent: زمانی استفاده می‌شود که ابزارها به‌صورت اسناد OpenAPI یا Swagger (به‌صورت HTTP از راه دور یا در مسیر Classpath محلی) باشند.
- قابلیت‌ها: پشتیبانی از تشخیص خودکار Swagger 2.0 و OpenAPI 3.0، بارگذاری از منابع متعدد با گروه‌بندی بر اساس تگ‌ها، گسترش ارجاعات ($ref expansion) و علامت‌گذاری ارجاعات دوری (Circular-ref markers).
- ابزارها: ابزارهای پروکسی داخلی شامل
call_api(در تمام مراحل)،get_api_detail(در مراحل Summary/List/Search) وsearch_apis(در مراحل List/Search) را فراهم می‌کند. - امنیت: برای مدیریت توکن‌های Bearer، کلیدهای API یا منطق‌های سفارشی از
ApiAuthenticatorاستفاده می‌کند. اولویت احراز هویت به این ترتیب است: احراز هویت منبع $\rightarrow$ احراز هویت پیش‌فرض. - فیلترینگ: از
allowedTools(ابزارهای مجاز) وdisallowedTools(ابزارهای غیرمجاز) برای هر منبع پشتیبانی می‌کند و به‌طور خودکار عملیات‌های علامت‌گذاری شده با@Deprecatedرا نادیده می‌گیرد.
۲. ToolGatewayTalent: برای حاکمیت بر FunctionTools محلی، AbsToolProvider یا ابزارهای MCP که قبلاً دریافت شده‌اند. این گزینه اصلی برای افزودن یا حذف ابزارهای تکی در زمان اجرا (Runtime) به‌صورت دقیق است.
- ابزارها: ابزارهای پروکسی
call_tool،get_tool_detailوsearch_toolsرا برای مراحل Summary/List/Search فراهم می‌کند. - منطق: در حالت FULL، ابزارهای تجاری اصلی مستقیماً در دسترس مدل قرار می‌گیرند و سه ابزار پروکسی تنها زمانی ظاهر می‌شوند که تعداد کاتالوگ از
dynamicThresholdعبور کند.
۳. McpGatewayTalent: برای پروتکل زمینه مدل (Model Context Protocol) و از طریق وابستگی solon-ai-mcp ساخته شده است. این گیت‌وی اتصالات به سرورهای MCP را از طریق McpServerParameters (مثلاً با استفاده از انتقال stdio و npx) مدیریت می‌کند.
- چرخه حیات: مدیریت کامل اتصال را بر عهده دارد. متد
removeMcpServerاتصال زیربنایی را می‌بندد، در حالی که غیرفعال کردن از طریقMcpClientProvider.setEnabled(false)تنها ایندکس ابزارها را حذف می‌کند. - کنترل: از لیست‌های مجاز/غیرمجاز در سطح سرور پشتیبانی می‌کند. توسعه‌دهندگان برای کنترل هر ابزار نیازی به انتقال به
ToolGatewayTalentندارند، زیراMcpServerParametersاین مورد را به‌طور بومی مدیریت می‌کند. - ابزارها: نام ابزارهای پروکسی آن مشابه
ToolGatewayTalentاست (call_tool,get_tool_detail,search_tools).
مدیریت چرخه حیات و دسترسی
مدیریت این گیت‌وی‌ها نیازمند نظم خاصی در زمان اجرا است. ویرایش دسترسی‌ها روی یک کپی از ApiSourceClient کافی نیست؛ توسعه‌دهنده باید حتماً متدهای refreshApi(...) یا refreshMcpServer(...) را فراخوانی کند تا تغییرات اعمال شوند. چارچوب Solon AI در هنگام رفرش از استراتژی «تعویض سایه‌ای» (Shadow Swap) استفاده می‌کند؛ به این معنا که ابتدا ابزارهای جدید اضافه و سپس قدیمی‌ها حذف می‌شوند تا فراخوانی‌های در جریان (In-flight calls) با جدول ابزار خالی مواجه نشوند.
حفاظ‌های تولید (Production Guardrails)
برای جلوگیری از شکست سیستم در محیط عملیاتی، یادداشت‌های رسمی موارد زیر را الزامی می‌دانند:
- نام‌گذاری: اطمینان حاصل کنید که نام ابزارها و عملیات‌ها در تمام منابع منحصر‌به‌فرد باشد. این نام‌ها به‌صورت حروف کوچک ذخیره می‌شوند و در زمان فراخوانی به حروف بزرگ و کوچک حساس نیستند.
- رمزگذاری URL: پارامترهای مسیر در OpenAPI حتماً باید از فرمت
{name}استفاده کنند. گیت‌وی جایگزینی‌های رمزگذاری URL را مدیریت می‌کند؛ هرگونه توکن{xxx}باقی‌مانده باعث شکست شدید و صریح سیستم خواهد شد. - وضعیت‌ها: منابع غیرفعال شده (
setEnabled(false)) برای مدیریت ثبت شده می‌مانند اما تا زمانی که دوباره فعال و رفرش نشوند، از ایندکس ابزارها حذف می‌شوند.
این چرخش معماری، فرض بنیادین استفاده از ابزار توسط عامل را تغییر می‌دهد. Solon AI با تغییر مدل از «هدایت» (Push) به «برداشت» (Pull) یا همان کشف تدریجی، اجازه می‌دهد عامل‌ها بدون قربانی کردن کیفیت استدلال در برابر حجم توکن‌ها، روی سطوح عظیم APIهای سازمانی فعالیت کنند.
برای کسانی که در حال مهاجرت هستند، قانون ساده است: تا زمانی که مجموعه ابزارها کوچک است، از AbsToolProvider و defaultToolAdd استفاده کنید. اما به محض اینکه با ده‌ها عملیات OpenAPI، سرورهای MCP که نباید طرح‌واره‌های کامل را ارسال کنند، یا کاتالوگ‌های سبک پلاگین که در زمان اجرا رشد و کاهش می‌یابند مواجه شدید، به Gateway Talent منتقل شوید. گیت‌وی‌ها جایگزین برنامه‌ریزی ReAct یا حافظه جلسه نیستند؛ آن‌ها به‌طور خاص مشکل مقیاس‌پذیری سطوح ابزار را حل می‌کنند. برای پیاده‌سازی، وابستگی solon-ai-talent-gateway را اضافه کرده و dynamicThreshold را بر اساس کارایی پنجره متنی مدل خود تنظیم کنید.
گام بعدی شما
- اگر از
AbsToolProviderاستفاده می‌کنید و تعداد ابزارهای شما از ۲۰ مورد بیشتر شده، سریعاً به Gateway Talent مهاجرت کنید. - مقدار
dynamicThresholdرا بر اساس کارایی پنجره متنی مدل خود تنظیم کنید تا توکن‌های اضافی مصرف نشود. - برای ابزارهای OpenAPI، فرمت
{name}را در تمام مسیرها بررسی کنید تا خطاهای Runtime کاهش یابد.
اما برای بهینه‌سازی عمیق‌تر هزینه استنتاج، استراتژی‌های کوانتش مدل‌ها مسیر متفاوتی را دنبال می‌کنند — به تحلیل ما درباره‌ی کاهش حافظه VRAM مراجعه کنید.
گفتگو