آموزش هوش مصنوعی

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

متوسط مطالعه در ۱۱ دقیقه بخش ۱۴ از ۵۰ در مسیر عملی هوش مصنوعی؛ از پرامپت تا ایجنت
mahdyar
· به‌روزرسانی
ساخت ابزار برای ایجنت در smolagents؛ دکوراتور، کلاس و MCP

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

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

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

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

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

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

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

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

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

سه راه ساخت ابزار برای ایجنت در smolagents؛ دکوراتور tool، زیرکلاس Tool و ابزار آماده

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

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

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

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

python
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 یا پایگاه داده می‌دهد.

ساخت ابزار برای ایجنت؛ ابزار پیدا کردن بهترین شرکت پذیرایی بر اساس امتیاز در smolagents

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

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

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

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

python
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?")

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

بیشتر بخوانید: اصول نظری طراحی ابزار، از توضیح دقیق تا نقش پیام سیستمی، در ابزار ایجنت هوش مصنوعی چیست؟ آمده است.

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

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

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

ابزارکاربرداستفاده‌ی آلفرد
PythonInterpreterToolاجرای کد پایتونمحاسبه‌ی چیدمان صندلی‌ها
FinalAnswerToolاعلام پاسخ نهاییجمع‌بندی برنامه‌ی مهمانی
UserInputToolپرسیدن سؤال از کاربرگرفتن تأیید برای بودجه
DuckDuckGoSearchToolجستجوی وبپیدا کردن ایده‌های موضوعی
GoogleSearchToolجستجوی گوگلیافتن بهترین خدمات پذیرایی
VisitWebpageToolخواندن محتوای یک صفحهبررسی جزئیات پیشنهادها

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

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

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

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

python
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 انجام می‌شود:

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

در این حالت کد Space روی سرورهای Hugging Face اجرا می‌شود و فقط نتیجه برمی‌گردد. بنابراین ریسکش با load_tool فرق دارد؛ اما هنوز هم داده‌ای که می‌فرستید به سرویس دیگری می‌رود.

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

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

از سرورهای MCP (پروتکل زمینه‌ی مدل) هم می‌توان مجموعه‌ای از ابزارها را یک‌جا وارد کرد. MCP مثل پریز برق استاندارد است: هر وسیله‌ای که دوشاخه‌ی استاندارد داشته باشد، به هر پریزی وصل می‌شود. پس از نصب smolagents[mcp]، کلاس ToolCollection.from_mcp همه‌ی ابزارهای یک سرور را بارگذاری می‌کند:

python
from mcp import StdioServerParameters
from smolagents import CodeAgent, InferenceClientModel, ToolCollection

server_parameters = StdioServerParameters(command="uvx", args=["--quiet", "pubmedmcp@0.1.3"])

with ToolCollection.from_mcp(server_parameters, trust_remote_code=True) as tool_collection:
    agent = CodeAgent(tools=[*tool_collection.tools], model=InferenceClientModel())
    agent.run("Please find a remedy for hangover.")

صدها سرور MCP آماده در فهرست‌هایی مثل glama.ai و smithery.ai در دسترس است. این همان استانداردی است که در قسمت نهم معرفی کردیم. نام سرور pubmedmcp در کد بالا فقط یک نمونه است؛ آن را با سروری که واقعاً لازم دارید عوض کنید.

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

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

  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) به فارسی بازنویسی و تکمیل شده است.

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

برای دنبال کردن عمیق‌تر این بحث، منابع زیر را به ترتیب از ساده به تخصصی بخوانید.

پرسش‌های پرتکرار

کی از دکوراتور tool و کی از کلاس Tool استفاده کنیم؟

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

جعبه‌ابزار پیش‌فرض smolagents شامل چه ابزارهایی است؟

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

می‌توانم ابزارهای LangChain را در smolagents استفاده کنم؟

بله. با متد Tool.from_langchain هر ابزار LangChain به ابزار smolagents تبدیل می‌شود. به همین شکل Tool.from_space یک Space در Hugging Face را به ابزار تبدیل می‌کند.

وارد کردن ابزار از Hub یا MCP چه ریسکی دارد؟

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

دیدگاه‌ها

هنوز دیدگاهی ثبت نشده است. شروع‌کننده باشید — پرسش و اصلاح را با آغوش باز می‌پذیریم.

دیدگاه بگذارید

برای **پررنگ**، *مورب*، `کد` و لینک از Markdown استفاده کنید. لینک‌ها nofollow هستند.

پنج رقم داخل تصویر را وارد کنید. اعداد فارسی و انگلیسی پذیرفته می‌شوند.

تصویر کد امنیتی پنج‌رقمی

در حال دریافت کد امنیتی…

مهلت کد تمام شد. روی «کد جدید» بزنید.