smolagents: کتابخانه‌ای ساده برای ساخت Agent‌ها

Agent‌ها چیستند؟

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

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

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

توجه داشته باشید که با این تعریف، Agent یک تعریف گسسته، صفر یا یک نیست: در عوض، عاملیت (agency) به اندازه ای که شما قدرت بیشتر یا کمتری به LLM در جریان کار خود می‌دهید در یک طیف پیوسته تکامل می‌یابد.

جدول زیر نشان می‌دهد چگونه عاملیت در سیستم‌های مختلف متفاوت است:

Agent چندمرحله‌ای (multi-step agent) این ساختار کد را دارد:

memory = [user_defined_task]
while llm_should_continue(memory): # this loop is the multi-step part
    action = llm_get_next_action(memory) # this is the tool-calling part
    observations = execute_action(action)
    memory += [action, observations]

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

✅ چه زمانی از Agent‌ها استفاده کنیم / ⛔ چه زمانی از آنها اجتناب کنیم

Agent‌ها زمانی مفید هستند که نیاز دارید یک LLM جریان کار یک برنامه را تعیین کند. اما اغلب استفاده از آنها زیاده‌روی است. سؤال این است: آیا واقعاً برای حل کارآمد وظیفه مورد نظر به انعطاف‌پذیری در جریان کار نیاز دارم؟ اگر جریان کار از پیش تعیین‌شده خیلی اوقات کافی نیست، به این معناست که به انعطاف‌پذیری بیشتری نیاز دارید. بیایید مثالی بزنیم: فرض کنید در حال ساخت برنامه‌ای هستید که درخواست‌های مشتری را در یک وب‌سایت سفرهای موج‌سواری مدیریت می‌کند.

شما می‌توانید از قبل بدانید که درخواست‌ها به یکی از این ۲ دسته تعلق خواهند داشت (بر اساس انتخاب کاربر)، و برای هر یک از این ۲ مورد یک جریان کار از پیش تعیین‌شده دارید:

• می‌خواهد اطلاعاتی درباره سفرها بداند؟ ⇐ به او دسترسی به یک نوار جستجو برای جستجو در پایگاه دانش خود بدهید
• می‌خواهد با فروش صحبت کند؟ ⇐ به او اجازه دهید در یک فرم تماس تایپ کند.

به عنوان مثال، کاربری می‌خواهد بپرسد: “من می‌توانم دوشنبه بیایم، اما پاسپورتم را فراموش کرده‌ام، پس ممکن است تا چهارشنبه تأخیر داشته باشم. آیا امکان دارد من و وسایلم را سه‌شنبه صبح برای موج‌سواری ببرید، با بیمه لغو؟” این سؤال به عوامل زیادی بستگی دارد و احتمالاً هیچ‌کدام از معیارهای از پیش تعیین‌شده بالا برای این درخواست کافی نخواهد بود.

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

اینجاست که یک راه‌اندازی Agentic کمک می‌کند.

در مثال بالا، می‌توانید یک Agent چندمرحله‌ای بسازید که به API آب و هوا برای پیش‌بینی آب و هوا، API گوگل مپس برای محاسبه فاصله سفر، داشبورد دسترسی کارمندان و یک سیستم RAG روی پایگاه دانش خود دسترسی داشته باشد.

کاربر می‌خواهد من بخش “Code agents” را ترجمه کنم. این بخش درباره روش‌های مختلف برای نوشتن اقدامات توسط LLM در Agent‌های چندمرحله‌ای است و مقایسه‌ای بین استفاده از JSON و کد برای بیان این اقدامات ارائه می‌دهد.

Code Agent‌ها

در یک Agent چندمرحله‌ای، در هر مرحله، LLM می‌تواند یک عمل را با فراخوانی ابزارهای خارجی انجام دهد. یک روش رایج (که توسط شرکت‌هایی مثل Anthropic و OpenAI و خیلی‌های دیگر استفاده می‌شود) برای نوشتن این اعمال، معمولاً به این شکل است: “اعمال را به صورت JSON بنویسید که شامل نام ابزارها و آرگومان‌هایی است که باید استفاده شوند، سپس شما آن را parse می‌کنید تا بفهمید کدام ابزار را با چه آرگومان‌هایی اجرا کنید.”

from typing import Optional
from smolagents import CodeAgent, HfApiModel, tool

@tool
def get_travel_duration(start_location: str, destination_location: str, transportation_mode: Optional[str] = None) -> str:
    """Gets the travel time between two places.

    Args:
        start_location: the place from which you start your ride
        destination_location: the place of arrival
        transportation_mode: The transportation mode, in 'driving', 'walking', 'bicycling', or 'transit'. Defaults to 'driving'.
    """
    import os   # All imports are placed within the function, to allow for sharing to Hub.
    import googlemaps
    from datetime import datetime

    gmaps = googlemaps.Client(os.getenv("GMAPS_API_KEY"))

    if transportation_mode is None:
        transportation_mode = "driving"
    try:
        directions_result = gmaps.directions(
            start_location,
            destination_location,
            mode=transportation_mode,
            departure_time=datetime(2025, 6, 6, 11, 0), # At 11, date far in the future
        )
        if len(directions_result) == 0:
            return "No way found between these places with the required transportation mode."
        return directions_result[0]["legs"][0]["duration"]["text"]
    except Exception as e:
        print(e)
        return e

agent = CodeAgent(tools=[get_travel_duration], model=HfApiModel(), additional_authorized_imports=["datetime"])

agent.run("Can you give me a nice one-day trip around Paris with a few locations and the times? Could be in the city or outside, but should fit in one day. I'm travelling only with a rented bicycle.")

می‌توانید نتیجه را در این فضا ببینید. منطق ابزار را می‌توانید در فایل tool.py در این فضا بررسی کنید.

منبع: https://huggingface.co/blog/smolagents