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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

این دستور به Node نیاز دارد و آرگومان دایرکتوری، تنها مسیری است که سرور به آن دسترسی خواهد داشت. این مدل امنیتی در مقیاس کوچک است: سرور مرزها را تعیین می‌کند، نه مدل. با متصل کردن یک کلاینت به آن، عامل شما قابلیت خواندن و نوشتن فایل‌هایی را به دست می‌آورد که شما برای آن کدی ننوشته‌اید. اجرای صحیح این موارد تحت یک حساب کاربری سرویس (service account) و با در نظر گرفتن گزینه‌های انتقال، در اجرای سرورهای MCP روی یک VPS برای عوامل برنامه‌نویسی هوش مصنوعی توضیح داده شده است. برای سرور دومی که به جای یک دایرکتوری موقت به داده‌های واقعی اشاره می‌کند، میزبانی شخصی openGym، یک ردیاب تمرینات ورزشی یک نسخه فقط‌خواندنی ارائه می‌دهد تا بتوانید پرسش درباره تاریخچه تمرینات خود را تمرین کنید، بدون اینکه به عامل اجازه دهید چیزی را تغییر دهد یا حذف کند.

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

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

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

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

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

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

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

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

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

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

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

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

اگر عامل شما به جای اسکریپتی که خودتان نوشته‌اید، درون یک چارچوب (harness) اجرا می‌شود، بخشی از این مرحله مربوط به پیکربندی است و نه کدنویسی. در پلاگین‌های DeepSeek Harness که ارزش نصب دارند، بسیاری از این موارد شامل سقف بودجه، قوانین دسترسی ابزارها و اسکن تزریق (injection scanning) پوشش داده شده است.

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

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

از کدام نقشه راه باید پیروی کنید؟

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

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

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

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

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

FAQ

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

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

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

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

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

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

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

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