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

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

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

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

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

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

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

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

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

آنچه افراد دست‌کم می‌گیرند، بخش مربوط به shell است. عامل‌ها به دلیل مجوزها، مسیرها، متغیرهای محیطی و فرآیندهایی که بی‌سروصدا متوقف می‌شوند، شکست می‌خورند. اگر یک stack trace مربوط به PATH یا یک file mode باعث می‌شود ترمینال را ببندید، ابتدا یک آخر هفته را صرف یادگیری اصول Linux کنید. این کار بعداً یک ماه در وقت شما صرفه‌جویی خواهد کرد.

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

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

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

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

مرحله 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 به شل می‌فرستد، که در یک ماشین آزمایشی که قابل بازسازی است قابل قبول است، اما در هر جای دیگری اشتباه است. مرحله 6 این مشکل را برطرف می‌کند. مفاهیم زیربنایی این حلقه در ساخت ایجنت هوش مصنوعی شخصی روی VPS با جزئیات بیشتری پوشش داده شده‌اند.

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

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

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

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 مربوط به زمانی است که می‌خواهید عامل بدون نظارت شما کار کند.

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

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

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

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

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

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

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

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

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

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

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

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

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

FAQ

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

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

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

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

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

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

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

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