آموزش گام‌به‌گام ساخت AI Agents از صفر

مسیر شش‌مرحله‌ای

برای یادگیری عامل‌های هوش مصنوعی (AI agents) از صفر، شش مرحله را به ترتیب طی کنید: مفاهیم، اولین حلقه، ابزارها، حافظه، طراحی حلقه و ایمنی. در هر مرحله، یک پروژه کوچک را با دستان خود می‌سازید. پریدن از روی مراحل، رایج‌ترین دلیل توقف یادگیری است، زیرا فریم‌ورک‌ها دقیقاً همان بخشی را که باید درک کنید، از دید شما پنهان می‌کنند.

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

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

آنچه پیش از مرحله 1 واقعاً نیاز دارید

فهرست پیش‌نیازهای واقعی کوتاه است و از آنچه اکثر صفحات آموزشی پیشنهاد می‌دهند، مختصرتر است.

• شما می‌توانید کدهای Python یا TypeScript را در سطح یک اسکریپت 50 خطی بخوانید و بنویسید.
• در محیط Linux shell راحت هستید: نصب یک پکیج، ویرایش یک فایل، خواندن یک لاگ.
• شما یک API key برای یک مدل میزبانی‌شده دارید، یا ماشینی در اختیار دارید که می‌تواند یک مدل محلی را اجرا کند.

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

آنچه افراد دست‌کم می‌گیرند، بخش مربوط به shell است. Agentها به دلیل مشکلات مجوزها (permissions)، مسیرها (paths)، متغیرهای محیطی (environment variables) و پردازش‌هایی که بی‌سروصدا متوقف می‌شوند، شکست می‌خورند. اگر یک stack trace درباره PATH یا حالت یک فایل باعث می‌شود ترمینال را ببندید، ابتدا یک آخر هفته را صرف یادگیری مبانی Linux کنید. این کار بعداً یک ماه در زمان شما صرفه‌جویی خواهد کرد.

مرحله 1: عامل (Agent) چیست و چه چیزی نیست

با یک فراخوانی API و بدون حلقه شروع کنید. یک prompt ارسال کنید، پاسخ را چاپ کنید و تعداد توکن‌های موجود در پاسخ را بررسی کنید. اکنون واحد هزینه و واحد تأخیر را درک کرده‌اید.

سپس استفاده از ابزار (tool use) را بیاموزید که تنها ایده واقعاً جدید در کل این حوزه است. شما یک تابع را برای مدل به عنوان یک نام، یک توضیحات و یک طرح JSON (JavaScript object notation) برای ورودی‌هایش توصیف می‌کنید. مدل هیچ چیزی را اجرا نمی‌کند. مدل با یک درخواست ساختاریافته پاسخ می‌دهد: فراخوانی run_command با این آرگومان‌ها. کد شما تابع را اجرا می‌کند، خروجی را به عنوان یک پیام بازمی‌گرداند و دوباره از مدل سؤال می‌کند. مدل یک برنامه‌ریز است که متن را می‌خواند و متن می‌نویسد. کد شما همان چیزی است که دست به کار می‌شود.

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

مرحله 2: حلقه را خودتان بنویسید، یک بار

با یک فریم‌ورک شروع نکنید. حدود 30 خط کد Python بنویسید تا ساختار کلی کار در کنترل خودتان باشد.

sudo apt update && sudo apt install -y python3-venv
python3 -m venv ~/agent
source ~/agent/bin/activate
pip install anthropic
export ANTHROPIC_API_KEY=your-key-here

import subprocess
import anthropic

client = anthropic.Anthropic()

tools = [{
    "name": "run_command",
    "description": "Run a read only shell command and return its output.",
    "input_schema": {
        "type": "object",
        "properties": {"command": {"type": "string"}},
        "required": ["command"],
    },
}]

messages = [{"role": "user", "content": "How much disk space is free here?"}]

while True:
    response = client.messages.create(
        model="claude-opus-5",
        max_tokens=4096,
        tools=tools,
        messages=messages,
    )
    if response.stop_reason != "tool_use":
        break
    messages.append({"role": "assistant", "content": response.content})
    results = []
    for block in response.content:
        if block.type == "tool_use":
            done = subprocess.run(
                block.input["command"], shell=True,
                capture_output=True, text=True, timeout=10,
            )
            results.append({
                "type": "tool_result",
                "tool_use_id": block.id,
                "content": done.stdout or done.stderr,
            })
    messages.append({"role": "user", "content": results})

print(next(b.text for b in response.content if b.type == "text"))

آن را با python3 agent.py اجرا کنید. یک اجرای سالم، یک پاراگراف شامل نام فایل‌سیستم‌ها و فضای آزاد آن‌ها چاپ می‌کند؛ زیرا مدل درخواست df -h کرده است، کد شما آن را اجرا کرده و در مرحله دوم، آن جدول به یک جمله تبدیل شده است. اگر خروجی چاپ نشد، یعنی حلقه پیش از رسیدن بلوک متنی پایان یافته است. دستور print(response.stop_reason) را داخل حلقه اضافه کنید و تغییر مقادیر را مشاهده کنید.

حالا عمداً آن را خراب کنید. خط tool_use_id را حذف کنید و خطا را بخوانید؛ زیرا نتیجه ابزاری که شناسه (id) منطبق نداشته باشد توسط API رد می‌شود و این رایج‌ترین باگ برای مبتدیان است. سوالی بپرسید که به دو دستور نیاز دارد و اجرای دو مرحله‌ای حلقه را ببینید. سوالی غیرممکن بپرسید و ببینید که آیا مدل تسلیم می‌شود یا در یک حلقه بی‌نهایت گیر می‌کند.

یک هشدار درباره این مثال: این کد خروجی مدل را مستقیماً با shell=True به shell می‌فرستد. این کار در یک ماشین آزمایشی که می‌توانید آن را دوباره بسازید قابل‌قبول است، اما در هر جای دیگری اشتباه است. مرحله 6 این مشکل را برطرف می‌کند. مفاهیم زیربنایی این حلقه در ساخت ایجنت هوش مصنوعی خود روی یک VPS با جزئیات بیشتری پوشش داده شده‌اند.

مرحله 3: ابزارهایی که ایجنت از قبل در اختیار نداشت

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

پروتکل Model Context Protocol (MCP) پاسخی است که صنعت بر سر آن به توافق رسیده است. یک سرور MCP مجموعه‌ای از ابزارها را از طریق یک پروتکل انتقال استاندارد ارائه می‌دهد و هر ایجنت سازگار با MCP می‌تواند بدون نیاز به کد واسط (glue code) سفارشی، از آن استفاده کند. سرور مرجع فایل‌سیستم تنها با یک دستور اجرا می‌شود:

npx -y @modelcontextprotocol/server-filesystem /home/you/projects

این دستور به Node نیاز دارد و آرگومان دایرکتوری، تنها مسیری است که سرور به آن دسترسی خواهد داشت. این مدل امنیتی در مقیاس کوچک است: سرور مرز دسترسی را تعیین می‌کند، نه مدل. با متصل کردن یک کلاینت به آن، ایجنت شما قابلیت خواندن و نوشتن فایل را به دست می‌آورد، بدون اینکه شما خودتان آن را پیاده‌سازی کرده باشید. اجرای صحیح این موارد تحت یک اکانت سرویس و با در نظر گرفتن گزینه‌های انتقال، در اجرای سرورهای MCP روی VPS برای ایجنت‌های برنامه‌نویسی هوش مصنوعی توضیح داده شده است.

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

مرحله 4: حافظه، که عمدتاً فقط شامل فایل‌هاست

مبتدیان در این مرحله به سراغ پایگاه‌داده‌های برداری (vector database) می‌روند. این کار را نکنید، حداقل نه در حال حاضر.

یک عامل (agent) بین فراخوانی‌ها هیچ حافظه‌ای ندارد. شما هر بار کل گفتگو را دوباره ارسال می‌کنید، و به همین دلیل است که هزینه هر نوبت در یک نشست طولانی، بیشتر از یک نشست کوتاه است. بنابراین حافظه به دو مشکل تقسیم می‌شود. مشکل اول، آن چیزی است که در حال حاضر در پنجره کانتکست (context window) جا می‌شود؛ شما این مورد را با خلاصه‌سازی، حذف خروجی‌های قدیمی ابزارها و کش کردن پیشوند ثابت پرامپت مدیریت می‌کنید تا هزینه کمتری برای آن بپردازید. مشکل دوم، آن چیزی است که پس از راه‌اندازی مجدد باقی می‌ماند، که همان ذخیره‌سازی است.

برای مشکل دوم، یک فایل markdown ساده که عامل بتواند آن را بخواند و بنویسد، برای تقریباً تمام پروژه‌های اولیه بهتر از پایگاه‌داده برداری عمل می‌کند. یک فایل به آن بدهید، فرمت را مشخص کنید، و به آن بگویید که پیش از شروع، فایل را بخواند و هنگام یادگیری مطلب جدید، آن را به‌روزرسانی کند. شما بیشترین بهره را می‌برید و می‌توانید فایل را باز کنید و ببینید عامل شما چه چیزی را باور دارد. زمانی که یادداشت‌ها دیگر در پنجره کانتکست جا نشدند، به سراغ embeddings و بازیابی (retrieval) بروید، نه پیش از آن.

مرحله 5: حلقه، خودِ محصول است

تا اینجای کار، شما می‌توانید عاملی (agent) بسازید که در حین نظارت شما کار می‌کند. مرحله 5 مربوط به زمانی است که شما حضور ندارید.

چهار پرسش تعیین می‌کنند که آیا یک عاملِ بدون نظارت برای رها شدن ایمن است یا خیر. چه چیزی آن را فعال می‌کند تا بیهوده اجرا نشود؟ در چه محدوده (boundary) عملیاتی فعالیت می‌کند تا در صورت بروز خطا، آسیب محدود بماند؟ نتیجه چگونه تأیید می‌شود، زیرا عاملی که خودش تکالیفش را تصحیح می‌کند، همیشه نمره قبولی می‌گیرد؟ چه بودجه‌ای آن را متوقف می‌کند، چه از نظر تعداد توکن و چه از نظر زمان واقعی (wall clock time)؟ طراحی آگاهانه این چهار مورد، همان نظمی است که در مهندسی حلقه و آنچه این تعریف پوشش می‌دهد توصیف شده است.

تمرین: عامل مرحله 2 خود را بردارید، وظیفه‌ای به آن بدهید که به 4 یا 5 مرحله نیاز دارد و یک سقف تکرار (iteration cap) سخت برای آن تعیین کنید. سپس آن سقف را بردارید و مشاهده کنید که یک حلقه نامحدود با صورت‌حساب توکن شما چه می‌کند. این کار را یک بار با بودجه کم انجام دهید تا هرگز به طور تصادفی آن را در مقیاس بزرگ تکرار نکنید.

مرحله 6: امنیت، اسرار و هزینه‌ها

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

عامل (agent) را با کاربری بدون امتیاز (unprivileged user) اختصاصی خود اجرا کنید؛ هرگز آن را با کاربر root یا حساب کاربری شخصی خود اجرا نکنید تا شعاع انفجار (blast radius) محدود به یک دایرکتوری باشد، نه کل ماشین. اعتبارنامه‌ها (credentials) را از دسترس مدل دور نگه دارید، زیرا هر چیزی که در پنجره کانتکست (context window) قرار بگیرد، ممکن است از طریق فراخوانی ابزار (tool call) بازگو شود. راه حل این است که توکن‌های کوتاه‌مدت را پشت یک واسط (helper) محدود کنید، همان‌طور که در دور نگه داشتن اسرار از عامل‌های هوش مصنوعی توضیح داده شده است. برای هزینه‌ها سقف مشخصی تعیین کنید، زیرا یک حلقه (loop) بدون نظارت، در هر تکرار هزینه ایجاد می‌کند بدون آنکه کسی آن را کنترل کند. محدودیت‌ها و دسته‌بندی‌هایی که باعث منطقی ماندن هزینه‌ها می‌شوند در کنترل هزینه عامل هوش مصنوعی روی VPS همیشه روشن آمده‌اند.

هزینه نیاز به یک عدد دقیق دارد. تا ژوئیه 2026، مدل Claude Opus 5 به ازای هر یک میلیون توکن ورودی 5 دلار و به ازای هر یک میلیون توکن خروجی 25 دلار هزینه دارد. یک عامل پرحرف که مکالمات در حال رشد را بازنشر می‌کند، می‌تواند در یک وظیفه واحد، چند صد هزار توکن مصرف کند. کش کردن پرامپت (prompt caching) و استفاده از یک مدل کوچک‌تر برای مراحل روتین، بیش از هر تغییر جزئی در پرامپت، محاسبات هزینه را تغییر می‌دهد.

تزریق پرامپت (prompt injection) نیز در این بخش جای می‌گیرد. اگر عامل شما یک صفحه وب، یک سیستم ردیابی خطا یا یک صندوق ورودی را می‌خواند، هر کسی که آن متن را نوشته است، در حال نوشتن دستورالعمل برای عامل شما نیز هست. دفاع در برابر این موضوع، یک پرامپت سیستمی هوشمندانه‌تر نیست؛ بلکه ایجاد مرزبندی است، زیرا عاملی که اجازه حذف یک مخزن (repository) را ندارد، نمی‌تواند متقاعد شود که آن را حذف کند.

کدام نقشه راه را باید دنبال کنید؟

به‌جای امتحان کردن شش برنامه مختلف، یک برنامه آموزشی را انتخاب کرده و آن را به پایان برسانید. مخزن ai-agents-for-beginners مایکروسافت کامل‌ترین منبع رایگان موجود است؛ دوره‌ای هجده‌درسی که تا ژوئیه 2026 بیش از 70,000 ستاره دریافت کرده و به‌طور دقیق با مراحل ذکر شده در بالا مطابقت دارد. فهرست‌های جمع‌آوری‌شده از مخازن ترند شدهٔ عامل‌ها (agent repositories) برای اطلاع از ابزارهای موجود مفیدند، اما به‌عنوان سرفصل آموزشی کارایی کمی دارند؛ زیرا فهرستی که بر اساس تعداد ستاره مرتب شده، نشان‌دهنده محبوبیت است، نه ترتیب آموزشی مناسب.

هنگامی که می‌خواهید روی یک پروژه واقعی تمرین کنید، یک عامل کدنویسی (coding agent) بهترین هدف اولیه است: بازخورد آن فوری است، ابزارهایش مشخص هستند و اصلاح اشتباهات هزینه کمی دارد. مقاله اجرای یک عامل هوش مصنوعی کدنویسی روی VPS این فرایند را از ابتدا تا انتها بررسی می‌کند. اگر ترجیح می‌دهید به‌جای ساختن از صفر، سیستم‌های عملیاتی را مطالعه کنید، مقایسه موجود در بهترین عامل‌های هوش مصنوعی self-hosted نشان می‌دهد که چگونه پروژه‌های مختلف، یک حلقه (loop) مشابه را به روش‌های متفاوتی حل می‌کنند.

این فرآیند چقدر زمان می‌برد؟

برای کسی که از قبل برنامه‌نویسی می‌داند، مراحل 1 و 2 در یک عصر انجام می‌شود. مرحله 3 یک آخر هفته زمان می‌برد که بخش عمده آن صرف مطالعه توضیحات ابزارها می‌شود تا خود پروتکل. مراحل 4 و 5 به چند هفته استفاده واقعی نیاز دارند، زیرا شما تنها با مشاهده فراموشی‌های عامل (agent) خود، متوجه می‌شوید که چه چیزی را فراموش می‌کند. مرحله 6 هرگز به پایان نمی‌رسد، چرا که هر قابلیت جدیدی که به آن اضافه می‌کنید، این مرحله را دوباره باز می‌کند.

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

FAQ

آیا برای ساخت یک AI agent نیاز به دانستن یادگیری ماشین دارم؟

خیر. ساخت یک agent به معنای فراخوانی یک مدل از طریق API و متصل کردن درخواست‌های ابزار (tool requests) آن به توابع واقعی است که یک برنامه‌نویسی معمولی محسوب می‌شود. شما هرگز با آموزش (training)، گرادیان‌ها یا مجموعه‌داده‌ها سر و کار ندارید. مهارت‌هایی که تعیین می‌کنند آیا agent شما کار می‌کند یا خیر، عبارتند از طراحی اسکیما برای ابزارها، مدیریت خطا و مجوزهای Linux. نظریه یادگیری ماشین تنها زمانی اهمیت پیدا می‌کند که بخواهید یک مدل را fine-tune کنید، که شغلی متفاوت با پیش‌نیازهای متفاوت است.

آیا باید با فریم‌ورک‌هایی مثل LangChain یا CrewAI شروع کنم؟

ابتدا یک حلقه (loop) خام بنویسید و سپس از فریم‌ورک استفاده کنید. یک فریم‌ورک، سی خط کد مرحله 2 را با یک شیء پیکربندی جایگزین می‌کند؛ این کار زمانی که بدانید چه چیزی جایگزین شده است راحت است، اما پیش از آن باعث سردرگمی می‌شود. وقتی agent شما رفتار نادرستی دارد، باید مستقیماً درباره لیست پیام‌ها و نتایج ابزارها استدلال کنید و اگر قبلاً آن‌ها را ندیده باشید، این کار بسیار دشوارتر است. پس از نوشتن یک حلقه توسط خودتان، فریم‌ورک به جای پنهان کردن مکانیزم، در وقت شما صرفه‌جویی خواهد کرد.

یادگیری AI agent چقدر هزینه دارد؟

اگر هزینه‌ها را محدود کنید، کمتر از آن چیزی است که اکثر مردم تصور می‌کنند. یک API key میزبانی‌شده و یک VPS کوچک، تمام نیازهای این شش مرحله را پوشش می‌دهد. ریسک واقعی، نرخ ساعتی نیست، بلکه یک حلقه نامحدود است که در هنگام خواب شما، برای هر تکرار هزینه می‌تراشد. از همان روز اول یک سقف هزینه سخت‌گیرانه روی حساب API خود تنظیم کنید، برای هر حلقه‌ای که می‌نویسید یک محدودیت تکرار (iteration cap) بگذارید و برای مراحل روتین از مدل‌های ارزان‌تر استفاده کنید. اجرای مدل به صورت محلی (locally)، هزینه توکن را حذف کرده و آن را با نیاز به سخت‌افزار جایگزین می‌کند.

تفاوت بین یک AI agent و یک chatbot چیست؟

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