بخش 4.4 · ایجنت، خروجی ساختاریافته و میان‌افزار

ابزارهای پرتعداد و انتخاب‌گر ابزار

Many tools and the tool selector

فهرست مطالب
  1. موضع‌گیری و پیشنهادها
  2. آزمایش
  3. انتخاب‌گر چه چیزی می‌فرستد؟
  4. انتخابی که اجرا را متوقف می‌کند
  5. توکن‌ها، زمان و هزینه‌ها
  6. راهکار مناسب برای مواجهه با فهرست طولانی ابزارها

مدل Claude Haiku 5.5 با 100 ابزار به نتیجه‌ی 10 از 10 رسید؛ میان‌افزار LLMToolSelectorMiddleware فراخوانی‌ها و هزینه‌ی آن را دو برابر کرد، و همین انتخاب‌گر در مدل Qwen3 4B، نتیجه را در تمام مقیاس‌ها به 1 از 10 رساند.

ایجنت شما حالا 60 ابزار دارد؛ یکی به ازای هر API داخلی. شاید جایی خوانده باشید که فهرست طولانی ابزارها مدل را گیج می‌کند، بنابراین میان‌افزار LLMToolSelectorMiddleware را اضافه می‌کنید تا فقط چند ابزار مرتبط را بفرستد. ایده در ظاهر بی‌خطر است: فهرست کوچک‌تر، توکن کمتر و فراخوانی اشتباه کمتر. ما این موضوع را اندازه گرفتیم و مشخص شد روی هیچ‌کدام از دو ارائه‌دهنده اصلاً کار درستی نیست.

پس از پایان این بخش، می‌توانید پیش‌بینی کنید که با افزودن ابزارها، نرخ قبولی (Pass Rate)، توکن‌ها، زمان و هزینه‌ها چگونه جابه‌جا می‌شوند. همچنین می‌توانید بر اساس کد توضیح دهید که چرا این انتخاب‌گر در نسخه‌ی 1.5.0 کتابخانه‌ی langchain شکست می‌خورد، و در نهایت با یک فهرست طولانی از ابزارها چه باید کرد.

موضع‌گیری و پیشنهادها

  • همه‌ی ابزارهایتان را به یک مدل پیشرو (Frontier Model) متصل کنید. مدل Claude Haiku 5.5 در مقیاس‌های 5، 20، 50 و 100 ابزار، 10 وظیفه از 10 وظیفه را پاس کرد و در مجموعِ 40 اجرا، فقط یک فراخوانی ابزار انحرافی داشت.
  • کش کردن پرامپت (Prompt caching) را روشن کنید، چون اصل هزینه از فهرست ابزارهاست. در مقیاس 100 ابزار، میانه‌ی اجراها 44,645 توکن پرامپت فرستاد و کش توانست صورت‌حساب را به 36% قیمت مصوب کاهش دهد.
  • در نسخه‌ی 1.5.0 کتابخانه‌ی langchain، میان‌افزار LLMToolSelectorMiddleware را کنار بگذارید. درخواست انتخاب این میان‌افزار در پیام‌هایش هیچ توضیحی از ابزارها ندارد. روی Claude تعداد فراخوانی‌ها، زمان و هزینه را دو برابر کرد و هیچ دستاوردی هم نداشت. روی Qwen3 4B نیز نرخ قبولی را در همه‌ی مقیاس‌ها به 1 از 10 رساند.
  • روی مدل کوچک محلی، فهرست را کوتاه نگه دارید. مدل Qwen3 8B با افزایش ابزارها از 5 به 50، از 5 به 0 از 10 سقوط کرد. مدل Qwen3 4B با 100 ابزار نتیجه‌ی 5 از 10 را نگه داشت، اما میانه‌ی هر اجرای آن 53 ثانیه طول کشید.

آزمایش

ابزار انحرافی (Distractor tool): ابزاری با نام و توضیحات موجه که وظیفه به آن نیازی ندارد؛ مانند get_item_price_history، search_catalog یا get_delivery_estimate. این بستر ارزیابی 95 مورد از آن‌ها را دارد. یکی از آن‌ها یک مبدل ارز منسوخ‌شده است که در توضیحاتش آمده نباید استفاده شود.

بستر آزمایشی 10 وظیفه‌ی زنجیره‌ای، از chain01 تا chain19 با شماره‌های فرد را از طریق create_agent اجرا کرد. هر وظیفه به get_item_info و دو تا چهار ابزار جستجوی دیگر احتیاج دارد. ایجنت 5 ابزار جستجو، ابزار submit_answer و به اندازه‌ی کافی ابزار انحرافی دریافت کرد تا بدون احتساب submit_answer، مجموعاً به 5، 20، 50 یا 100 ابزار برسد. ترتیب ابزارها برای هر وظیفه و هر مقیاس با یک seed ثابت تصادفی شد.

سه حالت در هر مقیاس اجرا شدند:

  • بدون انتخاب‌گر: اتصال همه‌ی ابزارها در تک‌تک فراخوانی‌ها.
  • انتخاب‌گر: میان‌افزار LLMToolSelectorMiddleware همراه با مدل ایجنت، max_tools=6 و always_include=["submit_answer"]، با پرامپت پیش‌فرض آن.
  • انتخاب‌گر همراه با فهرست: همان حالت قبلی، همراه با system_prompt اختصاصی ما که نام و توضیحات تک‌تک ابزارها را اضافه می‌کند. این حالت را فقط مدل‌های Qwen3 اجرا کردند.

ما این موارد را اندازه گرفتیم: همه‌ی اجراها روی Mac ارزیابی شدند. مدل Qwen3 4B در هر چهار مقیاس و مدل Qwen3 8B در 5 و 50 ابزار، روی Ollama با دمای 0 اجرا شدند. مدل Claude Haiku 5.5 در چهار مقیاس از طریق API بررسی شد. هر خانه از جدول نماینده‌ی 10 وظیفه است که هرکدام یک بار اجرا شدند.

قبولی در اینجا به معنای قبولی آسان‌گیرانه‌ی ارزیاب است. قبولی سخت‌گیرانه که به submit_answer هم نیاز دارد، در خانه‌های مربوط به Qwen3 به 0 تا 2 از 10 رسید. تصویر همه‌ی اجراها را نشان می‌دهد.

ده وظیفه زنجیره‌ای در چهار تعداد ابزار مختلف، با و بدون انتخاب‌گربدون انتخاب‌گر، Claude در 40 اجرا از 40 مورد موفق شد، و با انتخاب‌گر پیش‌فرض، Qwen3 در هر خانه حداکثر 2 از 10 را با موفقیت گذراند.
ده وظیفه زنجیره‌ای در چهار تعداد ابزار مختلف، با و بدون LLMToolSelectorMiddleware شبکه‌ای از ده وظیفه زنجیره‌ای برای هر مدل، تعداد ابزار و تنظیمات انتخاب‌گر، شامل create_agent روی Mac و Claude Haiku 5.5 از طریق API. مربع آبی یا ارغوانی نشان‌دهنده موفقیت، مربع صورتی پررنگ فراخوانی ابزار انحرافی یا عدم فراخوانی جستجوی مورد نیاز، مربع صورتی کم‌رنگ سایر شکست‌ها، و مربع سیاه اجرای منجر به خطا است. بدون انتخاب‌گر، Haiku در 5، 20، 50 و 100 ابزار نمره 10 از 10 گرفت و با آن 10، 10، 10 و 9. مدل Qwen3 4B بدون آن به ترتیب 5، 6، 5 و 5 و با آن 1، 1، 1 و 1 را پشت سر گذاشت. مدل Qwen3 8B تنها روی 5 و 50 ابزار اجرا شد. موفقیت‌ها با معیار سهل‌گیرانه سنجیده شده‌اند. مدل، تنظیمات 5 ابزار 20 ابزار 50 ابزار 100 ابزار Haiku 5.5 بدون انتخاب‌گر 10 10 10 10 انتخاب‌گر 10 10 10 9 Qwen3 4B بدون انتخاب‌گر 5 6 5 5 انتخاب‌گر 1 1 1 1 انتخاب‌گر + فهرست 3 2 4 2 Qwen3 8B بدون انتخاب‌گر 5 0 انتخاب‌گر 2 2 انتخاب‌گر + فهرست 3 3 موفق ابزار اشتباه: انحرافی یا عدم جستجو سایر خطاها خطا (raised) The number after each group counts the passes of 10. Tools: 5 lookups, distractors, and submit_answer. انتخاب‌گر + فهرست: پرامپت سیستمی سفارشی که نام و توضیحات هر ابزار را اضافه می‌کند.
هر مربع نشان‌دهنده یک اجرای یک وظیفه است. رنگ‌های آبی و ارغوانی نشان‌دهنده موفقیت هستند. صورتی پررنگ فراخوانی ابزار انحرافی یا عدم جستجوی آیتم، صورتی کم‌رنگ سایر شکست‌ها، و مشکی یک خطای رخ‌داده است. عدد بعد از هر گروه، تعداد موفقیت‌ها از 10 را می‌شمارد. برگرفته از capture/lab/bench/summary-mac.json.
مدل و تنظیمات 5 ابزار 20 ابزار 50 ابزار 100 ابزار
Claude Haiku 5.5، بدون انتخاب‌گر 10 10 10 10
Claude Haiku 5.5، با انتخاب‌گر 10 10 10 9
Qwen3 4B، بدون انتخاب‌گر 5 6 5 5
Qwen3 4B، با انتخاب‌گر 1 1 1 1
Qwen3 4B، انتخاب‌گر همراه با فهرست 3 2 4 2
Qwen3 8B، بدون انتخاب‌گر 5 اجرا نشد 0 اجرا نشد
Qwen3 8B، با انتخاب‌گر 2 اجرا نشد 2 اجرا نشد
Qwen3 8B، انتخاب‌گر همراه با فهرست 3 اجرا نشد 3 اجرا نشد

با 10 اجرا در هر خانه، فاصله‌ی اطمینان 95% ویلسون (Wilson interval) گسترده است؛ برای 5 از 10، از 0.24 تا 0.76، و برای 1 از 10، از 0.02 تا 0.40 را پوشش می‌دهد. بنابراین مقیاس‌ها را با هم بخوانید. در مجموعِ چهار مقیاس، مدل Qwen3 4B بدون انتخاب‌گر در 21 مورد از 40 تا و با انتخاب‌گر در 4 مورد از 40 تا قبول شد. فواصل اطمینان به ترتیب 0.37 تا 0.67 و 0.04 تا 0.23 هستند.

یک خانه نتیجه‌ی برعکس داد: مدل Qwen3 8B در 50 ابزار بدون انتخاب‌گر به 0 از 10 رسید و با انتخاب‌گر به 2. بدون انتخاب‌گر، این مدل در آن 10 اجرا، 31 بار ابزارهای انحرافی را فراخوانی کرده بود.

انتخاب‌گر حتی در 5 ابزار هم که چیزی برای حذف کردن نداشت، کار را خراب کرد. مدل Qwen3 8B با انتخاب‌گر، در 7 مورد از 10 اجرا هرگز get_item_info را صدا نزد. بدون انتخاب‌گر در تک‌تک اجراها آن را فراخواند؛ بنابراین انتخاب‌گر به احتمال زیاد آن را کنار گذاشته است.

انتخاب‌گر چه چیزی می‌فرستد؟

میان‌افزار LLMToolSelectorMiddleware درون wrap_model_call و پیش از هر فراخوانی مدل توسط ایجنت اجرا می‌شود. این میان‌افزار درخواستی با دو پیام می‌سازد: پرامپت سیستمی‌اش همراه با توضیحی درباره‌ی max_tools، و آخرین پیام کاربر {{code libs/langchain_v1/langchain/agents/middleware/tool_selection.py:402-405}}. سپس یک خروجی ساختاریافته (Structured Output) می‌خواهد که اسکیمای آن، نام هر ابزار را به‌صورت یک مقدار تحت‌اللفظی (literal) و توضیحات ابزار را به‌صورت فیلد توضیحات می‌آورد {{code libs/langchain_v1/langchain/agents/middleware/tool_selection.py:63-94}}.

بنابراین پیام‌ها هیچ فهرستی از ابزارها ندارند. این ماژول تابعی دارد که هر نام را با توضیحاتش رندر می‌کند، اما در نسخه‌ی 1.5.0 هیچ کدی آن را صدا نمی‌زند {{code libs/langchain_v1/langchain/agents/middleware/tool_selection.py:109-118}}. توضیحات فقط زمانی به مدل می‌رسند که ارائه‌دهنده، فیلدهای توضیحات اسکیما را به مدل نشان دهد.

دو ارائه‌دهنده این کار را متفاوت انجام می‌دهند. ChatAnthropic به‌طور پیش‌فرض اسکیما را به یک ابزار تبدیل می‌کند {{code libs/partners/anthropic/langchain_anthropic/chat_models.py:2880-2890}}، بنابراین Claude توضیحات را به‌عنوان بخشی از تعریف ابزار (Tool Definition) می‌خواند. اما ChatOllama اسکیما را در قالب format درخواست می‌فرستد {{code libs/partners/ollama/langchain_ollama/chat_models.py}}. در نتیجه روی Qwen3، فرآیند انتخاب شبیه گزینش صرفاً از روی نام‌ها بود:

  • در 20 ابزار، مدل Qwen3 4B در 8 مورد از 10 اجرا اصلاً get_item_info را صدا نزد و به‌جای آن ابزارهایی مانند search_catalog و get_item_price_history را فراخواند.
  • با پرامپت سیستمی حاوی فهرست ما، در 10 اجرای مقیاس 20 ابزار هیچ ابزار انحرافی‌ای فراخوانی نشد. با این حال باز هم فقط 2 مورد قبول شدند؛ پنج پاسخ اشتباه بودند و در سه اجرا نیز فراخوانی ابزار به‌صورت متن ساده نوشته شد.

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

انتخابی که اجرا را متوقف می‌کند

وقتی انتخاب‌گر ابزاری را نام ببرد که وجود ندارد، میان‌افزار خطای ValueError ایجاد می‌کند {{code libs/langchain_v1/langchain/agents/middleware/tool_selection.py:311-328}}. پارامتر on_parsing_failure در اینجا اثری ندارد؛ چون این پارامتر پاسخی را مدیریت می‌کند که فهرستی از نام‌ها نباشد، در حالی که یک نام ناشناخته همچنان یک فهرست معتبر است {{code libs/langchain_v1/langchain/agents/middleware/tool_selection.py:346-372}}.

مدل Claude Haiku 5.5 در 100 ابزار پاسخ درست را ثبت کرده بود که انتخاب بعدی، ابزاری را نام برد که ایجنت نداشت:

اجرایی که پاسخ را پیدا کرد، اما سپس در انتخاب‌گر دچار خطا شد capture/lab/bench/runs/toolscale.jsonl
{"run_id": "e08495cc", "tag": "toolscale", "ts": "2026-11-15T12:04:50", "task_id": "chain17", …"n_tools": 101, "passed": false, …"checks": {"get_item_info(trail lantern)": true, "get_item_info(camp stove)": true, "answer_submitted": true, "answer_correct": true}, "category": "harness_error", "detail": "ValueError: Model selected invalid tools: ['get_item_weight']", "answer": "camp stove", …"tool_seq": ["get_item_info", "get_item_info", "get_exchange_rate", "submit_answer"], …}

یک سطر، خلاصه شده به بررسی‌ها، خطا، پاسخ و فراخوانی‌های ابزار.

این استثنا اجرا را متوقف کرد، در نتیجه فراخواننده‌ی آن به‌جای یک وظیفه‌ی تکمیل‌شده، خطا دریافت کرد. مدل Qwen3 4B هم دو بار دقیقاً به همین شکل در 50 و 100 ابزار متوقف شد؛ جایی که نام ابزار را یک رشته‌ی خالی فرستاده بود.

توکن‌ها، زمان و هزینه‌ها

ما این موارد را اندازه گرفتیم: توکن‌های پرامپت تک‌تک اجراها را، با احتساب فراخوانی‌های انتخاب‌گر، ثبت کردیم. تصویر هر اجرا را نشان می‌دهد.

توکن‌های پرامپت هر اجرا در برابر تعداد ابزارهاتوکن‌های پرامپت از 5 به 100 ابزار در Claude شش برابر شد؛ انتخاب‌گر آن‌ها را کاهش داد اما در عین حال تعداد فراخوانی‌ها و با وجود کش، هزینه دلاری را دو برابر کرد.
توکن‌های پرامپت هر اجرا در برابر تعداد ابزارها دو نمودار نقطه‌ای از توکن‌های پرامپت هر اجرا در مقیاس لگاریتمی در 5، 20، 50 و 100 ابزار؛ بدون انتخاب‌گر با رنگ آبی و با LLMToolSelectorMiddleware با رنگ ارغوانی. در Claude Haiku 5.5، میانه اجراها بدون انتخاب‌گر به ترتیب 7381، 12959، 25767 و 44645 توکن و با آن 10941، 14391، 20722 و 33277 توکن در قالب 5، 4.5، 4.5، 4.5 و 9، 9، 9، 10 فراخوانی مدل ارسال کرد. با کش کردن پرامپت، ده اجرا در 100 ابزار بدون انتخاب‌گر 0.016 دلار و با آن 0.033 دلار هزینه داشت. در Qwen3 4B، انتخاب‌گر توکن‌ها را کاهش داد اما در عوض اجراها با شکست مواجه شدند. الف. CLAUDE HAIKU 5.5 0.1k 1k 10k 100k 5 20 50 100 ابزارهای متصل به ایجنت توکن‌های پرامپت در هر اجرا ب. QWEN3 4B، روی MAC 0.1k 1k 10k 100k 5 20 50 100 ابزارهای متصل به ایجنت توکن‌های پرامپت در هر اجرا الف. هزینه 10 اجرا، با کش کردن پرامپت 5 20 50 100 بدون انتخاب‌گر $0.005 $0.006 $0.011 $0.016 انتخاب‌گر $0.010 $0.014 $0.025 $0.033 بدون انتخاب‌گر، فراخوانی‌ها 5 4.5 4.5 4.5 انتخاب‌گر، فراخوانی‌ها 9 9 9 10 ب. میانه ثانیه‌ها در هر اجرا 5 20 50 100 هیچ‌کدام 8 10 30 53 انتخاب‌گر 6 15 18 15 + فهرست 5 7 16 13 خط‌چین: انتخاب‌گر + فهرست
هر نقطه نشان‌دهنده یک اجرا در مقیاس لگاریتمی است و هر خط میانه‌ها را به هم متصل می‌کند. رنگ آبی بدون انتخاب‌گر و ارغوانی با انتخاب‌گر است. جدول‌ها هزینه دلاری صورت‌حساب 10 اجرای Claude و میانه زمان (ثانیه) اجراهای Qwen3 4B را نشان می‌دهند. برگرفته از capture/lab/bench/summary-mac.json.

در Claude Haiku 5.5 بدون انتخاب‌گر، میانه‌ی اجرا 7,380 توکن پرامپت در 5 ابزار و 44,645 توکن در 100 ابزار فرستاد. اسکیمای هر ابزار (Tool Schema) به همه‌ی فراخوانی‌ها اضافه می‌شود. انتخاب‌گر این میانه را در 100 ابزار به 33,277 رساند و در 5 ابزار آن را افزایش داد. هر اجرا همراه با آن، 9 یا 10 فراخوانی مدل داشت؛ در حالی که بدون آن 4.5 تا 5 فراخوانی بود.

انتخاب‌گر زمان اجرا را دو برابر کرد: میانه‌ی 10.2 تا 12.6 ثانیه در برابر 5.0 تا 5.9 ثانیه. هزینه را هم دو برابر کرد؛ در 100 ابزار، 10 اجرا بدون انتخاب‌گر $0.016 و با آن $0.033 تمام شد.

کش این هزینه را توجیه می‌کند. بدون انتخاب‌گر، صورت‌حساب 10 اجرا در 100 ابزار 36% قیمت مصوب شد. با انتخاب‌گر، این رقم به 87% رسید. برداشت ما این است که انتخاب‌گر فهرست ابزارها را در هر درخواست تغییر می‌دهد، و ابزارها هم در ابتدای پیشوندی قرار دارند که با کش مطابقت داده می‌شود. بر اساس قیمت مصوب بدون کش، انتخاب‌گر در 100 ابزار 15% صرفه‌جویی می‌کرد و در 5 و 20 ابزار گران‌تر تمام می‌شد.

روی Qwen3 4B، انتخاب‌گر واقعاً در زمان صرفه‌جویی کرد. بدون آن، میانه‌ی هر اجرا در 100 ابزار 53 ثانیه طول کشید؛ در حالی که در 5 ابزار 8 ثانیه بود. Ollama در آن اجرا 29,000 توکن پرامپت خواند. با انتخاب‌گر، زمان اجرا به 6 تا 18 ثانیه رسید، اما 9 بار از 10 بار هم با شکست مواجه شد.

راهکار مناسب برای مواجهه با فهرست طولانی ابزارها

وضعیت این کار را بکنید داده‌های پشت آن
مدل Claude Haiku 5.5، تا 100 ابزار همه‌ی آن‌ها را متصل کنید و کش کردن پرامپت را روشن بگذارید 40 اجرا از 40 مورد، $0.016 برای 10 اجرا در 100 ابزار
مدل محلی کوچک فهرست را نزدیک به ابزارهای مورد نیاز وظیفه نگه دارید مدل Qwen3 8B با 5 ابزار 5 از 10، با 50 ابزار 0 از 10
همچنان می‌خواهید از LLMToolSelectorMiddleware استفاده کنید یک system_prompt بفرستید که نام و توضیحات هر ابزار را فهرست کند، و خطای ValueError را در فرآیند اجرا مدیریت کنید 2 تا 4 از 10 همراه با فهرست، در برابر 1 از 10 بدون آن
نوع وظیفه را پیش از اجرا می‌دانید ابزارها را در کد خودتان انتخاب کنید و فقط همان‌ها را متصل کنید این حالت را اندازه نگرفتیم، و هیچ فراخوانی اضافه‌ای به مدل تحمیل نمی‌کند

منابع: capture/lab/bench/summary-mac.json، capture/lab/bench/summarize.py، capture/lab/bench/runs/toolscale.jsonl، capture/lab/bench/runs/cost-ledger.jsonl، capture/lab/bench/kit/toolscale.py، capture/lab/bench/kit/run.py، capture/lab/bench/kit/harnesses.py؛ libs/langchain_v1/langchain/agents/middleware/tool_selection.py در langchain==1.5.0؛ libs/partners/ollama/langchain_ollama/chat_models.py در langchain-ollama 1.1.0؛ libs/partners/anthropic/langchain_anthropic/chat_models.py در langchain-anthropic 1.7.10.

ترجمه‌ی فارسی Many tools and the tool selector از راهنمای LangChain 101 دوره‌ی AI Engineering from Scratch، نوشته‌ی Rohit Ghumare، تحت مجوز MIT. دستورها، لاگ‌ها و اعداد عیناً از اجراهای ثبت‌شده‌ی متن اصلی‌اند. فهرست راهنما