فراخوانی و مسیریابی اسکیل‌ها در ایجنت‌های هوش مصنوعی

وقتی تعداد ابزارها و اسکیل‌ها (Skills) در یک سیستم ایجنتی افزایش پیدا می‌کند، یکی از بزرگ‌ترین چالش‌ها فعال‌سازی بی‌مورد یا تداخل آن‌هاست؛ مثلاً کاربری یک سؤال ساده‌ی تئوری درباره‌ی دیتابیس می‌پرسد، اما مدل به‌اشتباه اسکیل پرریسک مهاجرت پایگاه داده را انتخاب و اجرا می‌کند. این خطا معمولاً ناشی از یک فرضیه‌ی اشتباه است: تقلیل دادن سطح دسترسی و نحوهٔ فراخوانی به یک متغیر بولی ساده.

در سیستم‌های استاندارد، «دسترسی مستقیم کاربر»، «انتخاب خودکار توسط مدل» و «فعال‌سازی از طریق کد برنامه» ابعاد کاملاً مستقلی از خط‌مشی (Policy) هستند. برای جلوگیری از رفتارهای پیش‌بینی‌نشده، باید فرآیند را به تفکیک مراحل اهلیت، رتبه‌بندی و اجرا مدل‌سازی کرد و توصیف اسکیل‌ها را به مرزهای منفی مجهز ساخت تا در زمان‌های نامربوط برانگیخته نشوند.

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

فراخوانی ابتدا تصمیمی درباره‌ی صلاحیت (Authority) و سپس تصمیمی درباره‌ی ارتباط موضوعی (Relevance) است. توصیفِ خوب به مدل در انتخاب کمک می‌کند؛ خط‌مشیِ خوب مشخص می‌کند که آیا این انتخاب مجاز است یا نه.

اهداف یادگیری

• تفکیک فراخوانی صریح از سوی کاربر، فراخوانی ضمنی توسط مدل، فراخوانی توسط برنامه و فراخوانی اسکیل به اسکیل (Skill-to-skill).
• مدل‌سازی «قابلیت مشاهده برای انسان» و «واجد شرایط بودن برای مدل» به‌صورت ابعاد مستقل خط‌مشی.
• نوشتن توصیف‌های مسیریابی به همراه محرک‌های مثبت (Positive triggers) و مرزهای نمونه‌های منفی دشوار (Near-miss boundaries).
• تفکیک مراحلِ واجد شرایط بودن، انتخاب، فعال‌سازی، مقیدسازی آرگومان و اجرا در ردگیری‌ها (Traces) و آزمون‌ها.
• تطبیق فیلدهای فراخوانیِ وابسته به محیط اجرا بدون ارائه‌ی آن‌ها در قالب فرانت‌متر (Frontmatter) پرتابل.

صورت مسئله

اسکیلی به نام database-migration نصب می‌کنید. کاربر می‌تواند نام آن را مستقیماً صدا بزند، اما مدل هم توصیف اسکیل را می‌بیند و وقتی کسی سؤالی عمومی درباره‌ی پایگاه داده بپرسد، آن را انتخاب می‌کند. در نتیجه، اسکیل برای کاری که فقط به یک توضیح ساده نیاز داشته، تغییر اسکیما (Schema) پیشنهاد می‌دهد.

فیلد user-invocable: false را اضافه می‌کنید به این امید که جلوی اجرای دستیِ کاربران را بگیرید؛ اما یک محیط اجرای دیگر این فیلد را نادیده می‌گیرد. بعد disable-model-invocation: true را قرار می‌دهید و انتظار دارید اسکیل کاملاً ناپدید شود؛ اما در محیطی که این فیلد را می‌فهمد، کاربر هنوز می‌تواند آن را مستقیماً فراخوانی کند.

مشکل از نام فیلدها نیست؛ مدل ذهنی اشتباه است. «کاربر بتواند آن را ببیند»، «مدل بتواند آن را انتخاب کند»، «برنامه بتواند آن را پیش‌بارگذاری کند» و «ابزارهای درون آن بتوانند اجرا شوند»، واقعیت‌هایی کاملاً مستقل از یکدیگرند. یک متغیر بولیِ ساده به نام invocable نمی‌تواند این تفاوت‌ها را بیان کند.

مسیریابی یک حالت شکست دیگر هم دارد: اگر توصیف‌ها مبهم باشند، چندین اسکیل محتمل به نظر می‌رسند. اگر توصیف‌ها انباشته از کلمات کلیدی باشند، وظایف نامربوط هم آن‌ها را فعال می‌کنند. کاتالوگ اسکیل‌ها یک رابط احتمالاتی است: باید آن‌قدر جمع‌وجور باشد که در کانتکست بگنجد و آن‌قدر مشخص و دقیق باشد که مسیریابی درستی انجام دهد.

مفاهیم پایه

پنج کانال می‌توانند چرخه‌ی حیات را آغاز کنند

مشخصات پرتابل Agent Skills صرفاً بسته را تعریف می‌کند؛ این مشخصات رابط کاربری خطوط مورب (Slash commands)، پرچمِ مسیریابی ضمنی، API برنامه یا چرخه‌ی حیات ساب‌ایجنت را یکسان و استاندارد نمی‌کند.

پنج مرحله‌ی فراخوانی

این واژه‌ها را دقیق به کار ببرید:

• واجد شرایط (Eligible): یعنی خط‌مشی به این کنش‌گر اجازه‌ی درخواست اسکیل را می‌دهد.
• انتخاب‌شده (Selected): یعنی کاربر نام آن را آورده یا یک مسیریاب آن را مرتبط تشخیص داده است.
• فعال‌شده (Activated): یعنی دستورالعمل‌های آن وارد کانتکست کاری شده‌اند.
• در حال اجرا (Executing): یعنی ایجنت، کار با مدل یا ابزارها را تحت آن دستورالعمل‌ها آغاز کرده است.
• تکمیل‌شده (Completed): یعنی خروجی نهایی معیار بررسی موفقیتِ مستقل را برآورده کرده است.

ردگیری‌ای که فقط skill_used=true را ثبت کند، مرز نقطه‌ی وقوع خرابی را پنهان می‌سازد.

فراخوانی توسط انسان و مدل یک ماتریس 2x2 می‌سازد

این ماتریس یک مدل خط‌مشی است، نه یک ساختار استاندارد در YAML.

یکی از میزبان‌های فعلی از disable-model-invocation: true برای سطر «فقط انسان» و از user-invocable: false برای سطر «فقط مدل» استفاده می‌کند. حالت پیش‌فرض، فعال بودن هر دو است. میزبانی دیگر در فایل agents/openai.yaml از allow_implicit_invocation: false استفاده می‌کند تا فراخوانی صریح را حفظ کند اما انتخاب ضمنی را غیرفعال سازد. این موارد تطبیق‌دهنده‌های محیط اجرا هستند و میزبان‌های ناشناخته ممکن است آن‌ها را نادیده بگیرند.

این جزئیاتِ گمراه‌کننده اهمیت زیادی دارند: user-invocable: false به این معنی نیست که «مدل نمی‌تواند از این استفاده کند»؛ بلکه صرفاً فراخوانی مستقیم توسط کاربر را در میزبانی که آن را تعریف کرده حذف می‌کند. همچنین disable-model-invocation: true به این معنی نیست که «اسکیل کلاً غیرفعال شده»؛ بلکه انتخاب توسط مدل را حذف می‌کند و دسترسی صریح کاربر را باز نگه می‌دارد.

فراخوانی صریح مبتنی بر شناسه‌ی اسکیل است

در فراخوانی صریح، شناسه مستقیماً مشخص می‌شود:

/release-readiness v2.4.0

یا:

release-readiness check v2.4.0 without publishing

رابط‌های فعلی Codex گزینه‌ی /skills را برای انتخاب و نام ساده‌ی اسکیل در درخواست‌ها را برای فراخوانی صریح مستند کرده‌اند. Claude Code از دستور /skill-name و بسط آرگومان‌های وابسته به میزبان استفاده می‌کند. سینتکس دقیق، قابلیت مشاهده در منو، قواعد نقل‌قول و جای‌گذاری متغیرها همگی متعلق به میزبان است.

یک درخواست صریح باز هم باید از سد خط‌مشی بگذرد. بردن نام یک اسکیل نباید مجوزهای ناموجود، محدودیت‌های ورک‌اسپیس، گیت‌های تایید یا ایزولاسیون محیط اجرا را دور بزند.

فراخوانی ضمنی مبتنی بر توصیف اسکیل است

در مسیریابی ضمنی، مدل ابتدا متادیتای کاتالوگ را می‌بیند نه بدنه‌ی کامل اسکیل را؛ بنابراین، توصیف اسکیل همان رابط مسیریابی آن محسوب می‌شود.

ضعیف:

description: Helps with releases.

بیش از حد گسترده:

description: Use for release, version, package, build, deploy, publish, tag, changelog, GitHub, CI, or software tasks.

دارای مرزبندی مشخص:

description: Inspect an already prepared release candidate and produce a readiness report. Use when the user asks whether a version, tag, package, or image is ready to publish; do not use for ordinary build failures or feature development.

نسخه‌ی مرزبندی‌شده شامل این موارد است:

1. توانمندی (Capability): بررسی یک کاندیدای آماده‌شده.
2. خروجی (Output): گزارش آمادگی.
3. مرز مثبت (Positive boundary): زمانی که درباره‌ی آماده بودن آرتیفکت انتشار سؤال می‌شود.
4. مرز منفی (Negative boundary): بیلدها و فرایند عادی توسعه خارج از دامنه‌ی این اسکیل هستند.

مرزهای منفی زمانی کاربرد دارند که دو اسکیلِ نزدیک، واژگان مشترکی داشته باشند. البته این مرزها جایگزین ارزیابی‌های مربوط به نمونه‌های منفی دشوار نمی‌شوند.

مسیریابی نوعی دسته‌بندی با گزینه‌ی امتناع است

برای یک اسکیل s و درخواست x، امتیاز مسیریاب را این‌طور در نظر بگیرید:

score(s, x) = capability_match + trigger_match + context_match - exclusion_match - ambiguity_penalty

امتیازدهی دقیق ممکن است به تصمیم یک مدل زبانی وابسته باشد تا یک فرمول ریاضی؛ با این حال، اصل مهندسی تغییر نمی‌کند: برای انتخاب، امتیاز باید از یک آستانه و از اسکیل رقیب بیشتر باشد. وقتی شواهد ضعیف است، باید امتناع کرد.

برای اسکیل‌های با اثرگذاری بالا، حتی با داشتن توصیفی قوی هم ممکن است مسیریابی ضمنی نامناسب باشد. وقتی هزینه‌ی مثبت کاذب از راحتیِ انتخاب خودکار بیشتر است، خط‌مشی «فقط انسان» را به کار ببرید.

واجد شرایط بودن باید بر رتبه‌بندی مقدم باشد

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

برای مسیریابی ضمنی از این ترتیب استفاده کنید:

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

فرض کنید incident-triage امتیاز 0.80 می‌آورد اما افزونه‌ی میزبان فراخوانی مدل را برای آن غیرفعال کرده است. از طرفی incident-review امتیاز 0.55 دارد و فراخوانی مدل را مجاز می‌داند. مسیریاب باید incident-review را به‌عنوان بهترین کاندیدای واجد شرایط ارزیابی کند؛ نه اینکه incident-triage را برگزیند، آن را رد کند و متوقف شود.

این ترتیب همچنین مانع از آن می‌شود که تغییرات خط‌مشی، معنای امتیاز ارتباط موضوعی را عوض کند. واجد شرایط بودن، مجموعه‌ی انتخاب را مشخص می‌کند و ارتباط موضوعی، آن مجموعه را رتبه‌بندی می‌کند.

ارزیابی‌های مسیریابی به نمونه‌های منفی دشوار نیاز دارند

نمونه‌های مثبت، بازخوانی (Recall) را نشان می‌دهند:

{"prompt":"Is version 2.4.0 ready to publish?","expected":"release-readiness"}

منفی‌های کاملاً واضح، دقت (Precision) پایه را اثبات می‌کنند:

{"prompt":"Explain rotary position embeddings.","expected":null}

نمونه‌های منفی دشوار، کیفیت مرزبندی را آشکار می‌کنند:

{"prompt":"Why did today's package build fail?","expected":"build-diagnostics"}

نمونه‌ی منفی دشوار واژه‌هایی مثل package و build را با اسکیل انتشار به اشتراک دارد، اما متعلق به جای دیگری است. مجموعه‌ی ارزیابی مسیریابی اگر فقط از مثبت‌های بدیهی و منفی‌های نامربوط تشکیل شده باشد، کیفیت را بیش از واقعیت نشان خواهد داد.

آرگومان‌ها سه شیوه‌ی نمایش دارند

یک آرگومان فراخوانی از چندین مرز عبور می‌کند:

در هر مرز، نیت را حفظ کنید بدون اینکه با متن مانند کد برخورد شود.

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

هرگز آرگومان‌های خام را مستقیماً درون دستورات شل قرار ندهید. به جای آن از اسکریپتی کمک بگیرید که با یک بردار آرگومان (Argument vector) فراخوانی می‌شود، یا از یک ابزار تایپ‌دار MCP استفاده کنید.

فراخوانی برنامه‌ای همان ارکستراسیون صریح است

یک محصول می‌تواند اسکیلی را فعال کند زیرا جریان کاری آن از قبل نوع وظیفه را می‌داند؛ مثلاً یک سرویس بازبینی پول ریکوئست (PR) می‌تواند پس از کلیک کاربر روی Review، اسکیل pull-request-risk-review را پیش‌بارگذاری کند.

این کار عدم قطعیت در مسیریابی را از بین می‌برد اما به API محیط اجرا وابستگی ایجاد می‌کند. این تطبیق‌دهنده را خارج از بدنه‌ی پرتابل نگه دارید:

اسکیل باید طوری بماند که اگر کلاینت استاندارد دیگری آن را باز کرد، همچنان قابل فهم باشد.

فراخوانی اسکیل به اسکیل ارتباطی شبیه به ابزار است

فرض کنید اسکیل release-readiness در صورت تغییر فایل‌های وابستگی، درخواست اجرای security-change-review را می‌دهد.

فراخوان‌کننده باید این موارد را فراهم کند:

• شناسه‌ی اسکیل مقصد؛
• وظیفه‌ی محدود و مسیر فایل‌ها؛
• قرارداد خروجی مورد انتظار؛
• دلیل فراخوانی؛
• سناریوی بازگشت در صورت در دسترس نبودن؛
• حداکثر عمق یا قاعده‌ای برای پیشگیری از چرخه.

{
  "target_skill": "security-change-review",
  "task": "Review dependency changes in the candidate diff",
  "inputs": ["artifacts/release.diff"],
  "expected": "risk-report.json",
  "max_depth": 2
}

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

چرخه‌ی حیات کانتکست وابسته به میزبان است

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

اسکیلی ننویسید که به فرضیاتی نامرئی درباره‌ی طول عمر وابسته باشد. خروجی‌های پایا را در فایل‌ها یا وضعیت‌های تایپ‌دار ذخیره کنید، ورود مجدد به اسکیل را ایمن بسازید و مشخص کنید چه مواردی پس از وقفه (Interrupt) باید دوباره بارگذاری شوند.

On resume, read `artifacts/release-readiness.json` if it exists.
Revalidate the candidate commit before continuing.
Do not repeat an external write whose idempotency key is already recorded.

پیاده‌سازی از صفر

فایل code/main.py خط‌مشی و مسیریابی را در قالب تطبیق‌دهنده‌هایی جداگانه پیاده‌سازی می‌کند.

این مدل شامل موارد زیر است:

• متغیر Actor برای فراخوانندگانی مانند انسان، مدل، ایجنت خودگردان، برنامه، اسکیل و بستر ارزیابی؛
• متغیر SkillMetadata برای شناسه‌ی مسیریابی؛
• متغیر InvocationPolicy برای ماتریس تعامل انسان و مدل؛
• ساختارهای InvocationRequest و InvocationDecision برای ورودی‌ها و نتایج قابل ردگیری؛
• تطبیق‌دهنده‌ی CorePolicyAdapter برای رفتارهای پرتابل بدون افزونه‌های اختصاصی میزبان؛
• تطبیق‌دهنده‌ی ExtensionPolicyAdapter برای فیلدهای شناخته‌شده‌ی محیط اجرا؛
• تابع build_invocation_matrix(policy) برای ارائه‌ی نمای ماتریس 2x2؛
• تابع route_request(skills, request, adapter) برای فیلتر واجدین شرایط قبل از رتبه‌بندی ارتباط، انتخاب و در نهایت رد درخواست.

اجرای برنامه:

cd phases/13-tools-and-protocols/25-skill-invocation-and-routing
python3 code/main.py
python3 -m unittest discover -s code/tests -v

این دمو یک ماتریس و تصمیمات مربوط به کانال‌های صریح انسانی، ضمنی مدل، ایجنت خودگردان، برنامه، ترکیب اسکیل‌ها و بسترهای ارزیابی را چاپ می‌کند. نتایج تطبیق‌دهنده‌ی افزونه‌ها نشان می‌دهد که یک تطابق واژگانی بالای مسدودشده، پیش از رتبه‌بندی گزینه‌ی واجد شرایط بعدی حذف می‌شود. همچنین شامل لیست‌های مجازِ نام‌های دقیق است. به هیچ API مدلی نیاز نیست؛ این مسیریاب قطعی (Deterministic) ساخته شده تا مرزهای خط‌مشی را قابل بررسی کند، نه اینکه ادعا کند تطابق واژگانی می‌تواند مسیریابی مدل در محیط پروداکشن را بازتولید کند.

چرا تطبیق‌دهنده‌های هسته و افزونه از هم جدا هستند؟

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

کلاس CorePolicyAdapter فقط از خط‌مشی مشخص‌شده توسط برنامه استفاده می‌کند. کلاس ExtensionPolicyAdapter مجموعه‌ای صریح از فیلدهای میزبان را تشخیص می‌دهد و ثبت می‌کند که کدام فیلد تصمیم را تغییر داده است.

استفاده از ابزارهای واقعی

پیش از انتشار هر اسکیل، قراردادی برای نحوه‌ی فراخوانی آن بنویسید:

actors:
  human: allow
  model: deny
  application: allow
  skill: deny
explicit_name: release-readiness
arguments:
  candidate: required
  publish: fixed_false
ambiguity: ask_user
missing_dependency: stop
context:
  durable_state: artifacts/release-readiness.json
  max_composition_depth: 2

این قرارداد یک مستند طراحی برای تطبیق‌دهنده‌ها و آزمون‌هاست؛ تا زمانی که یک استاندارد رسماً آن را تصویب نکرده باشد، فرانت‌متر پرتابل SKILL.md به شمار نمی‌رود.

خروجی این درس

این درس بسته‌ی skill-invocation-router را ارائه می‌دهد. این بسته شامل مرجع مدل فراخوانی، نمونه‌ای از خط‌مشی میزبان و یک ابزار CLI غیر اجرایی است که درخواستی از طرف انسان، مدل، ایجنت خودگردان، برنامه، ترکیب اسکیل‌ها یا بستر ارزیابی را ارزیابی کرده و یک خروجی JSON از تصمیم نهایی شامل کانال، تطبیق‌دهنده، امتیاز و دلیل برمی‌گرداند.

این ابزار CLI تک‌درخواستی ابزاری برای بررسی خط‌مشی است، نه یک ارزیابی کامل محرک‌ها. از طراحی آزمون‌های برچسب‌دار مثبت و نمونه‌های منفی دشوار در درس 27 برای محاسبه‌ی ماتریس درهم‌ریختگی، دقت، بازخوانی و پایداری در اجراهای مکرر استفاده کنید.

تمرین‌ها

1. هر چهار سطر ماتریس انسان/مدل را بسازید و برای هرکدام یک سناریوی کاربردی معتبر بنویسید.
2. قابلیت فعال‌سازی «فقط برنامه» را به CorePolicyAdapter بیفزایید. نشان دهید که فراخواننده‌های انسانی و مدل همچنان رد می‌شوند.
3. ده نمونه‌ی منفی دشوار برای یک اسکیل استقرار (Deployment) بنویسید. هر پرامپت باید واژگان مشترکی با اسکیل داشته باشد ولی به جریان کاری متفاوتی تعلق بگیرد.
4. یک حاشیه‌ی ابهام (Ambiguity margin) بین دو امتیاز برتر مسیریابی در نظر بگیرید؛ اگر این فاصله خیلی ناچیز بود، پاسخ ask (درخواست برای رفع ابهام) بازگردانید.
5. برای درخواست‌های اسکیل به اسکیل، سقف عمق ترکیب‌پذیری تعیین کنید و چرخه‌ی میان دو اسکیل را تشخیص دهید.
6. یک مجموعه‌ی داده‌ی برچسب‌دارِ یکسان را از تطبیق‌دهنده‌های هسته و افزونه رد کنید. دلیل هر تصمیمی را که دستخوش تغییر شده توضیح دهید.

اصطلاحات کلیدی

برای مطالعه‌ی بیشتر

• بهینه‌سازی توصیف اسکیل‌ها برای محرک‌های مثبت، دقت در توصیف و ارزیابی.
• ارزیابی اسکیل‌ها برای طراحی ارزیابی محرک‌ها و خروجی‌ها.
• OpenAI: ساخت اسکیل‌ها برای کنترل‌های فعلی Codex در فراخوانی صریح و ضمنی.
• اسکیل‌های Claude Code برای بررسی پیاده‌سازی فیلدهای user-invocable، disable-model-invocation، آرگومان‌ها و کانتکست‌های تفویض‌شده در یک میزبان واقعی.