ساخت ابزار برای ایجنت در smolagents؛ دکوراتور، کلاس و MCP

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

در این قسمت از مجموعه‌ی «از پرامپت تا دستیار هوش مصنوعی» دو روش ساخت ابزار در smolagents را با مثال می‌بینیم. بعد جعبه‌ابزار پیش‌فرض کتابخانه را مرور می‌کنیم و یاد می‌گیریم ابزار را منتشر کنیم یا از Hub، Spaces، LangChain و سرورهای MCP ابزار آماده وارد کنیم.

رابط ابزار؛ آنچه مدل باید بداند

برای اینکه مدل بتواند از ابزاری استفاده کند، به یک توضیح رابط نیاز دارد. این توضیح چهار جزء دارد:

• نام: ابزار چه نامیده می‌شود؛ مثلاً web_search.
• توضیح: ابزار چه کاری انجام می‌دهد؛ مثلاً «جستجو در وب برای یک پرسش مشخص».
• ورودی‌ها: چه آرگومان‌هایی با چه نوعی می‌گیرد؛ مثلاً query از نوع رشته.
• نوع خروجی: چه چیزی برمی‌گرداند؛ مثلاً رشته‌ای شامل نتایج جستجو.

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

دو روش ساخت ابزار برای ایجنت در smolagents

در smolagents ابزار را به دو شکل می‌توان تعریف کرد. روش اول دکوراتور @tool برای ابزارهای ساده و مبتنی بر تابع است. روش دوم ساخت زیرکلاسی از Tool برای ابزارهایی با منطق پیچیده‌تر.

روش اول؛ دکوراتور tool

دکوراتور @tool روش پیشنهادی برای ابزارهای ساده است. smolagents اطلاعات تابع را خودش از کد پایتون استخراج می‌کند. پس اگر تابع را خوب نام‌گذاری کنید و docstring دقیقی بنویسید، مدل راحت‌تر از آن استفاده می‌کند.

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

آلفرد منوی مهمانی را انتخاب کرده و حالا یک شرکت پذیرایی خوب می‌خواهد. ابزار زیر بهترین شرکت را بر اساس امتیاز برمی‌گرداند:

from smolagents import CodeAgent, InferenceClientModel, tool

@tool
def catering_service_tool(query: str) -> str:
    """
    This tool returns the highest-rated catering service in Gotham City.
    Args:
        query: A search term for finding catering services.
    """
    services = {"Gotham Catering Co.": 4.9, "Wayne Manor Catering": 4.8, "Gotham City Events": 4.7}
    return max(services, key=services.get)

agent = CodeAgent(tools=[catering_service_tool], model=InferenceClientModel())
print(agent.run("Can you give me the name of the highest-rated catering service in Gotham City?"))

ایجنت ابزار را صدا می‌زند و پاسخ می‌دهد: Gotham Catering Co. در پروژه‌ی واقعی، دیکشنری ثابت جای خودش را به یک API یا پایگاه داده می‌دهد.

روش دوم؛ زیرکلاس Tool

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

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

from smolagents import Tool, CodeAgent, InferenceClientModel

class SuperheroPartyThemeTool(Tool):
    name = "superhero_party_theme_generator"
    description = "Suggests a creative superhero-themed party idea based on a category."
    inputs = {"category": {"type": "string", "description": "e.g. 'classic heroes', 'villain masquerade', 'futuristic Gotham'"}}
    output_type = "string"

    def forward(self, category: str):
        themes = {
            "classic heroes": "Justice League Gala",
            "villain masquerade": "Gotham Rogues' Ball",
            "futuristic gotham": "Neo-Gotham Night",
        }
        return themes.get(category.lower(), "Theme not found. Try 'classic heroes' or 'villain masquerade'.")

agent = CodeAgent(tools=[SuperheroPartyThemeTool()], model=InferenceClientModel())
agent.run("What would be a good superhero party idea for a 'villain masquerade' theme?")

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

جعبه‌ابزار پیش‌فرض smolagents

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

آلفرد با همین ابزارها می‌تواند کل مهمانی را برنامه‌ریزی کند. جدول زیر ابزارها و کاربرد هر کدام در کار آلفرد را نشان می‌دهد.

اشتراک و وارد کردن ابزار

یکی از قوی‌ترین قابلیت‌های smolagents، اشتراک ابزار در Hub و استفاده از ابزارهای جامعه است. این قابلیت شامل Spaces و ابزارهای LangChain هم می‌شود. به این ترتیب لازم نیست هر ابزاری را خودتان از صفر بسازید.

انتشار ابزار در Hub

اشتراک ابزار با یک خط انجام می‌شود. آلفرد می‌تواند ابزار موضوع مهمانی را برای دیگران منتشر کند:

party_theme_tool.push_to_hub("{your_username}/party_theme_tool", token="<YOUR_HF_TOKEN>")

توکن را از متغیر محیطی بخوانید، نه اینکه مستقیم در کد بنویسید. ابزار منتشرشده در حساب Hugging Face شما قرار می‌گیرد و هر کسی می‌تواند آن را بارگذاری کند.

وارد کردن ابزار از Hub و Spaces

برای استفاده از ابزار دیگران تابع load_tool را دارید. مثلاً آلفرد برای ساخت تصویر تبلیغاتی مهمانی، یک ابزار تولید تصویر آماده را وارد می‌کند. پارامتر trust_remote_code=True لازم است، چون کد آن ابزار روی سیستم شما اجرا می‌شود.

با Tool.from_space هم می‌توانید هر Space در Hugging Face را به ابزار تبدیل کنید. این یعنی دسترسی به هزاران مدل و برنامه، از تولید تصویر تا تحلیل داده. اتصال از طریق gradio_client انجام می‌شود:

image_generation_tool = Tool.from_space(
    "black-forest-labs/FLUX.1-schnell",
    name="image_generator",
    description="Generate an image from a prompt",
)

ابزارهای LangChain و سرورهای MCP

اگر پیش‌تر با LangChain کار کرده‌اید، ابزارهایش را می‌توانید با Tool.from_langchain در smolagents استفاده کنید. مثلاً ابزار جستجوی SerpAPI پس از نصب langchain-community و تنظیم کلید API، با یک خط به ابزار smolagents تبدیل می‌شود.

از سرورهای MCP هم می‌توان مجموعه‌ای از ابزارها را یک‌جا وارد کرد. پس از نصب smolagents[mcp]، کلاس ToolCollection.from_mcp همه‌ی ابزارهای یک سرور را بارگذاری می‌کند. صدها سرور MCP آماده در فهرست‌هایی مثل glama.ai و smithery.ai در دسترس است. این همان استانداردی است که در قسمت نهم معرفی کردیم.

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

ابزارهای دستیار پروژه‌ی مشترک را حرفه‌ای‌تر کنید:

1. search_courses را با دکوراتور @tool بنویسید و مقدارهای مجاز سطح را در docstring فهرست کنید.
2. CourseCatalogTool را به شکل زیرکلاس Tool بسازید که فهرست دوره‌ها را یک بار در سازنده بارگذاری کند.
3. VisitWebpageTool را اضافه کنید تا ایجنت بتواند صفحه‌ی توضیح هر دوره را بخواند.

از ایجنت بپرسید «سرفصل دوره‌ی پایتون مبتدی چیست؟» و ببینید کدام ابزارها را به چه ترتیبی صدا می‌زند. اگر ابزار را منتشر کردید، لینکش را برای همکارانتان بفرستید تا آزمایشش کنند.

سخن پایانی

ساخت ابزار برای ایجنت در smolagents دو مسیر روشن دارد: دکوراتور @tool برای ابزار ساده و زیرکلاس Tool برای ابزار پیچیده. در هر دو مسیر، نام گویا، توضیح دقیق و ورودی نوع‌دار کیفیت کار را تعیین می‌کنند. جعبه‌ابزار پیش‌فرض و امکان وارد کردن ابزار از Hub، Spaces، LangChain و MCP هم باعث می‌شود بیشتر وقتتان صرف ساخت ابزارهای واقعاً اختصاصی شود. فقط یادتان باشد هر ابزار واردشده، کدی است که روی سیستم شما اجرا می‌شود.

در قسمت پانزدهم ایجنت را به جستجوی چندمرحله‌ای در اسناد مجهز می‌کنیم و Agentic RAG می‌سازیم.

این آموزش بر پایه‌ی بخش Tools از دوره‌ی آزاد Agents Course در Hugging Face (مجوز Apache-2.0) به فارسی بازنویسی و تکمیل شده است.