CodeAgent چیست؟ ساخت ایجنت کدنویس با smolagents

CodeAgent نوع پیش‌فرض ایجنت در smolagents است و شاید مهم‌ترین دلیل محبوبیت این کتابخانه. در قسمت‌های قبل، ایجنت ما هر اقدام را به شکل یک JSON می‌نوشت؛ نام ابزار و ورودی‌هایش. CodeAgent همین کار را با کد پایتون انجام می‌دهد و همین تفاوت ساده، ایجنت را سریع‌تر و توانمندتر می‌کند.

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

CodeAgent چیست و چرا کد به‌جای JSON؟

در ایجنت‌های چندمرحله‌ای، مدل اقدام‌ها را می‌نویسد و سیستم آن‌ها را اجرا می‌کند. روش سنتی استفاده از JSON است. سیستم باید رشته‌ی JSON را تجزیه کند تا بفهمد کدام ابزار با چه ورودی‌ای اجرا شود.

اما پژوهش‌ها نشان داده‌اند مدل‌های زبانی وقتی مستقیم با کد کار می‌کنند، عملکرد بهتری دارند. این یافته در مقاله‌ی Executable Code Actions Elicit Better LLM Agents منتشر شد و اصل بنیادی smolagents شد. کل هسته‌ی این کتابخانه برای ساخت ایجنت کدنویس، حدود هزار خط کد است.

چهار مزیت نوشتن اقدام با کد

نوشتن اقدام به شکل کد چهار مزیت کلیدی دارد:

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

مثال مقاله گویاست. قرار است ارزان‌ترین کشور برای خرید یک گوشی از میان چهار کشور پیدا شود. ایجنت JSON باید برای هر کشور چند فراخوانی جداگانه انجام دهد. CodeAgent همه را در یک حلقه‌ی for می‌نویسد و با تابع min پایتون نتیجه را پیدا می‌کند.

CodeAgent پشت صحنه چطور کار می‌کند؟

CodeAgent همان چارچوب ReAct را دنبال می‌کند که در قسمت دهم دیدیم. در smolagents، پایه‌ی همه‌ی ایجنت‌ها کلاسی به نام MultiStepAgent است و CodeAgent نوع خاصی از آن است.

گام‌های اجرای run

وقتی agent.run() را صدا می‌زنید، ایجنت همه‌ی اطلاعات را در یک گزارش اجرا نگه می‌دارد. ابتدا پیام سیستمی در یک SystemPromptStep و درخواست کاربر در یک TaskStep ثبت می‌شود. بعد یک حلقه اجرا می‌شود که تا فراخوانی ابزار final_answer ادامه دارد.

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

وقتی ابزار final_answer فراخوانی شد، run() مقدار آن را برمی‌گرداند. کل این چرخه را در طرح زیر می‌بینید.

چرا گزارش اجرا مهم است؟

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

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

مثال عملی؛ آلفرد مهمانی را آماده می‌کند

آلفرد قرار است در عمارت خانواده‌ی وین یک مهمانی برگزار کند و از ما کمک می‌خواهد. با چهار مثال، توانایی‌های CodeAgent را قدم‌به‌قدم می‌بینیم. اول smolagents را نصب کنید و با huggingface_hub.login() وارد حساب Hugging Face شوید.

انتخاب موسیقی با جستجوی وب

موسیقی بخش مهمی از هر مهمانی است. ایجنتی می‌سازیم که با ابزار DuckDuckGo در وب جستجو کند. مدل پیش‌فرض InferenceClientModel یعنی Qwen2.5-Coder-32B است که از طریق Serverless API در دسترس است:

from smolagents import CodeAgent, DuckDuckGoSearchTool, InferenceClientModel

agent = CodeAgent(tools=[DuckDuckGoSearchTool()], model=InferenceClientModel())
agent.run("Search for the best music recommendations for a party at the Wayne's mansion.")

هنگام اجرا، ایجنت قدم‌به‌قدم کدی را که نوشته نمایش می‌دهد؛ مثلاً results = web_search(query="best music for a Batman party"). بعد از چند قدم، فهرست پخش پیشنهادی آماده است.

منوی مهمانی با ابزار اختصاصی

حالا منو را آماده می‌کنیم. با دکوراتور @tool یک ابزار اختصاصی می‌سازیم که بر اساس نوع مهمانی، منو پیشنهاد می‌دهد:

from smolagents import CodeAgent, tool, InferenceClientModel

@tool
def suggest_menu(occasion: str) -> str:
    """
    Suggests a menu based on the occasion.
    Args:
        occasion (str): The type of occasion. Allowed values: "casual", "formal", "superhero", "custom".
    """
    menus = {"casual": "Pizza, snacks, and drinks.", "formal": "3-course dinner with wine and dessert.", "superhero": "Buffet with high-energy and healthy food."}
    return menus.get(occasion, "Custom menu for the butler.")

agent = CodeAgent(tools=[suggest_menu], model=InferenceClientModel())
agent.run("Prepare a formal menu for the party.")

به docstring دقت کنید. مقدارهای مجاز آرگومان occasion در آن فهرست شده‌اند. این کار مدل را به استفاده از مقدارهای موجود هدایت می‌کند و احتمال ساختن مقدار نامعتبر را کم می‌کند.

محاسبه‌ی زمان با importهای مجاز

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

agent = CodeAgent(tools=[], model=InferenceClientModel(), additional_authorized_imports=["datetime"])
agent.run("""
Alfred needs to prepare for the party:
1. Prepare the drinks - 30 minutes
2. Decorate the mansion - 60 minutes
3. Set up the menu - 45 minutes
4. Prepare the music and playlist - 45 minutes
If we start right now, at what time will the party be ready?
""")

ایجنت زمان‌ها را جمع می‌زند، با datetime به ساعت فعلی اضافه می‌کند و ساعت دقیق آماده‌شدن را برمی‌گرداند. این همان جایی است که کد واقعاً از JSON جلو می‌زند؛ محاسبه در همان اقدام انجام می‌شود.

امنیت اجرای کد

اجرای کدی که مدل نوشته، ذاتاً ریسک دارد. محدودیت importها اولین خط دفاع smolagents است. فقط ماژول‌هایی را اضافه کنید که واقعاً لازم‌اند و هرگز ماژول‌هایی مثل os یا subprocess را بی‌دلیل مجاز نکنید.

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

اشتراک و ردیابی CodeAgent

ایجنت آماده است. حالا دو قابلیت کاربردی دیگر را می‌بینیم: اشتراک ایجنت با دیگران و ردیابی دقیق اجرای آن.

انتشار ایجنت در Hub

smolagents اجازه می‌دهد کل ایجنت را با یک خط در Hugging Face Hub منتشر کنید و ایجنت دیگران را هم دانلود کنید:

agent.push_to_hub("your-username/AlfredAgent")
alfred_agent = agent.from_hub("your-username/AlfredAgent", trust_remote_code=True)

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

ردیابی اجرا با OpenTelemetry و Langfuse

ایجنت‌ها ذاتاً غیرقابل‌پیش‌بینی‌اند و اشکال‌زدایی‌شان سخت است. smolagents از استاندارد OpenTelemetry پشتیبانی می‌کند و با ابزاری مثل Langfuse می‌توانید همه‌ی قدم‌ها را ثبت و بررسی کنید:

from openinference.instrumentation.smolagents import SmolagentsInstrumentor

SmolagentsInstrumentor().instrument()

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

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

دستیار دوره‌ها را به CodeAgent تبدیل کنید و قدرت کد را آزمایش کنید:

1. ابزارهای search_courses و check_capacity را با docstring کامل و مقدارهای مجاز تعریف کنید.
2. از ایجنت بپرسید «از بین همه‌ی دوره‌های مبتدی، کدام بیشترین ظرفیت خالی را دارد؟».
3. کد تولیدشده را بخوانید؛ آیا ایجنت با یک حلقه همه‌ی دوره‌ها را بررسی کرد یا قدم‌به‌قدم؟

تعداد قدم‌ها را با نسخه‌ی JSON قسمت یازدهم مقایسه کنید. اگر SmolagentsInstrumentor را فعال کنید، این مقایسه را با جزئیات کامل در Langfuse هم می‌بینید.

سخن پایانی

CodeAgent با یک ایده‌ی ساده کار می‌کند: مدل اقدام را با کد پایتون بنویسد، نه با JSON. نتیجه قدم‌های کمتر، ترکیب راحت‌تر ابزارها و توانایی محاسبه‌ی مستقیم است. smolagents این ایده را با محیط اجرای محدود، اشتراک در Hub و ردیابی OpenTelemetry کامل کرده است. فقط امنیت اجرای کد را هیچ‌وقت فراموش نکنید.

در قسمت چهاردهم سراغ ساخت ابزار اختصاصی در smolagents می‌رویم؛ با دکوراتور، با کلاس و با ابزارهای آماده‌ی Hub.

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