CodeAgent نوع پیشفرض ایجنت در smolagents است و شاید مهمترین دلیل محبوبیت این کتابخانه. در قسمتهای قبل، ایجنت ما هر اقدام را به شکل یک JSON مینوشت؛ نام ابزار و ورودیهایش. CodeAgent همین کار را با کد پایتون انجام میدهد و همین تفاوت ساده، ایجنت را سریعتر و توانمندتر میکند.
در این قسمت از مجموعهی «از پرامپت تا دستیار هوش مصنوعی» میبینیم چرا کد از JSON بهتر است، CodeAgent پشت صحنه چه مراحلی را طی میکند و بعد با آلفرد، پیشخدمت آشنای این مجموعه، یک مهمانی را با چهار مثال عملی آماده میکنیم.
CodeAgent چیست و چرا کد بهجای JSON؟
در ایجنتهای چندمرحلهای، ابتدا مدل اقدامها را مینویسد و سیستم آنها را اجرا میکند. روش سنتی استفاده از JSON است. در نتیجه سیستم باید رشتهی JSON را تجزیه کند تا بفهمد کدام ابزار با چه ورودیای اجرا شود.
فرق این دو روش را با یک مثال بانکی ببینید. ایجنت JSON مثل مشتریای است که برای هر کار یک فرم جدا پر میکند و هر بار در صف میایستد. در مقابل، CodeAgent یک نامهی کامل به کارمند مینویسد: «موجودی هر چهار حساب را ببین و کمترینش را بگو.» البته این تشبیه یک حد دارد؛ کارمند واقعی خودش قضاوت میکند، اما مفسر پایتون فقط همان کد را اجرا میکند.
اما پژوهشها نشان دادهاند مدلهای زبانی وقتی مستقیم با کد کار میکنند، عملکرد بهتری دارند. این یافته در مقالهی 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() مقدار آن را برمیگرداند. کل این چرخه را در طرح زیر میبینید.

چرا گزارش اجرا مهم است؟
در واقع گزارش اجرا حافظهی ایجنت است. هر متغیر و هر نتیجهای که در قدمهای قبل به دست آمده، در قدم بعدی در دسترس است. به همین دلیل ایجنت میتواند روی کار قبلیاش بنا کند.
علاوه بر این، گزارش برای شما هم ارزشمند است. وقتی ایجنت خطا میکند، با خواندن گزارش دقیقاً میبینید کدام کد نوشته شد، چه خروجیای داد و کجا اشتباه شد. در بخش آخر همین مقاله این گزارش را به یک ابزار ردیابی حرفهای وصل میکنیم.
بیشتر بخوانید: اگر هنوز اولین ایجنت smolagents را نساختهاید، آموزش smolagents را ببینید؛ از کپی قالب تا انتشار ایجنت در Spaces.
مثال عملی؛ آلفرد مهمانی را آماده میکند
آلفرد قرار است در عمارت خانوادهی وین یک مهمانی برگزار کند و از ما کمک میخواهد. با چهار مثال، تواناییهای 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"). بعد از چند قدم، فهرست پخش پیشنهادی آماده است.
با این حال، مدل پیشفرض در نسخههای تازهی smolagents عوض شده است و ممکن است باز هم عوض شود. بنابراین برای نتیجهی قابلتکرار، مدل را صریح بدهید؛ مثلاً InferenceClientModel(model_id="Qwen/Qwen2.5-Coder-32B-Instruct").
منوی مهمانی با ابزار اختصاصی
حالا منو را آماده میکنیم. با دکوراتور @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 را بیدلیل مجاز نکنید.
محیط اجرای محدود را مثل زمین بازی حصارکشیشدهی کودکان در پارک تصور کنید. کودک آزادانه بازی میکند، اما به خیابان نمیرسد. سندباکس (sandbox) حصار محکمتری است؛ کد در یک ماشین یا کانتینر جدا اجرا میشود تا حتی اگر از حصار اول رد شد، به سیستم اصلی شما نرسد.
برای محیط تولید، اجرای کد را به سندباکسهای جداگانه بسپارید. 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 میتوانید همهی قدمها را ثبت و بررسی کنید. ردیابی (tracing) مثل جعبهی سیاه هواپیماست؛ هر لحظهی پرواز را ثبت میکند تا بعد از هر حادثه بفهمید چه شد.
پیش از هر چیز، بستههای لازم را نصب کنید و کلیدهای Langfuse را در متغیرهای محیطی بگذارید. سپس ابزارگذاری را فعال کنید:
pip install opentelemetry-sdk opentelemetry-exporter-otlp openinference-instrumentation-smolagents langfusefrom openinference.instrumentation.smolagents import SmolagentsInstrumentor
SmolagentsInstrumentor().instrument()از این به بعد هر اجرای ایجنت، با همهی کدها، خروجیها و خطاها، در داشبورد Langfuse دیده میشود. در قسمت نوزدهم از همین دادهها برای ارزیابی ایجنت استفاده میکنیم.
تمرین عملی؛ CodeAgent برای دستیار دورهها
دستیار دورهها را به CodeAgent تبدیل کنید و قدرت کد را آزمایش کنید:
- ابزارهای
search_coursesوcheck_capacityرا با docstring کامل و مقدارهای مجاز تعریف کنید. - از ایجنت بپرسید «از بین همهی دورههای مبتدی، کدام بیشترین ظرفیت خالی را دارد؟».
- کد تولیدشده را بخوانید؛ آیا ایجنت با یک حلقه همهی دورهها را بررسی کرد یا قدمبهقدم؟
در پایان تعداد قدمها را با نسخهی JSON قسمت یازدهم مقایسه کنید. اگر SmolagentsInstrumentor را فعال کنید، این مقایسه را با جزئیات کامل در Langfuse هم میبینید. به نظر شما در کدام نوع پرسش، فرق تعداد قدمها بیشتر میشود؟
سخن پایانی
CodeAgent با یک ایدهی ساده کار میکند: مدل اقدام را با کد پایتون بنویسد، نه با JSON. نتیجه قدمهای کمتر، ترکیب راحتتر ابزارها و توانایی محاسبهی مستقیم است. smolagents این ایده را با محیط اجرای محدود، اشتراک در Hub و ردیابی OpenTelemetry کامل کرده است. فقط امنیت اجرای کد را هیچوقت فراموش نکنید.
در قسمت چهاردهم سراغ ساخت ابزار اختصاصی در smolagents میرویم؛ با دکوراتور، با کلاس و با ابزارهای آمادهی Hub.
این آموزش بر پایهی بخش Building Agents That Use Code از دورهی آزاد Agents Course در Hugging Face (مجوز Apache-2.0) به فارسی بازنویسی و تکمیل شده است.
برای مطالعه بیشتر
برای دنبال کردن عمیقتر این بحث، منابع زیر را به ترتیب از ساده به تخصصی بخوانید.
- آموزش smolagents؛ ساخت اولین ایجنت عملی: قسمت قبلی همین مجموعه به فارسی؛ برای کسی که هنوز ایجنتی با smolagents اجرا نکرده است.
- Building Agents That Use Code در Agents Course (انگلیسی): متن و نوتبوک اصلی همین درس با هر چهار مثال آلفرد؛ برای سطح متوسط.
- چارچوب ReAct در مستندات smolagents (انگلیسی): توضیح رسمی حلقهی MultiStepAgent و گامهای اجرا؛ برای سطح متوسط.
- راهنمای اجرای امن کد در smolagents (انگلیسی): سندباکسها و محدودیتهای مفسر پایتون؛ لازم پیش از هر استقرار واقعی.
- مقالهی Executable Code Actions Elicit Better LLM Agents (انگلیسی): پژوهشی که برتری اقدام با کد را نشان داد؛ برای سطح پیشرفته.
پرسشهای پرتکرار
CodeAgent چه فرقی با ایجنت JSON دارد؟
ایجنت JSON در هر قدم فقط یک فراخوانی ابزار را به شکل متن ساختاریافته مینویسد. CodeAgent یک قطعهکد پایتون مینویسد که میتواند چند ابزار، حلقه و متغیر را یکجا ترکیب کند؛ برای همین با قدمهای کمتری به نتیجه میرسد.
اجرای کد تولیدشده توسط مدل امن است؟
smolagents کد را در محیطی محدود اجرا میکند و بهطور پیشفرض فقط importهای فهرست امن را اجازه میدهد. برای ماژولهای دیگر باید آنها را صریحاً در additional_authorized_imports بیاورید. برای محیط تولید، اجرای کد در سندباکس جداگانه توصیه میشود.
چرا در docstring ابزار مقدارهای مجاز را مینویسیم؟
وقتی مقدارهای مجاز یک آرگومان را در docstring فهرست کنید، مدل فقط از همان مقدارها استفاده میکند و احتمال ساختن مقدار نامعتبر کم میشود.
چطور اجرای CodeAgent را ردیابی کنیم؟
smolagents از استاندارد OpenTelemetry پشتیبانی میکند. با نصب SmolagentsInstrumentor و اتصال به ابزاری مثل Langfuse، همهی قدمها، کدها و خطاهای ایجنت ثبت و قابل بررسی میشوند.







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