مقدمه

پیش‌گفتار

نگاه کلی به کالج Agentic AI

قالب کوئرا کالج

سیستم امتیازدهی و گواهی

مبانی Agentic Work و طرز فکر سیستمی

اهداف فصل

تفاوت چهار سطح AI Chat، Copilot، Agent و Multi-Agent

چهار جزء یک Agent: مدل، ابزار، حلقه، حافظه

حلقهٔ کاری: فکر، عمل، مشاهده، تکرار

تشخیص کار مناسب Agent از کار انسان

سناریو: انتخاب اولین کار برای سپردن در پشتیبانی اسنپ

چرا Agentها اشتباه می‌کنند

سناریو: صف کاتالوگ دیجی‌کالا و انتخاب سطح خودمختاری

سناریو: شب طولانی یک agent در تپسی

آزمون فصل ۲: مبانی Agentic Work و طرز فکر سیستمی

انتخاب مدل

خانواده‌های مدل و تفاوت‌هایشان

تعادل هزینه، کیفیت و سرعت

انتخاب مدل بر اساس نوع کار

سناریو: انتخاب خانوادهٔ مدل برای توضیح فیلم در فیلیمو

سناریو: سه‌راهی هزینه، کیفیت و سرعت در اسنپ‌فود

کار با چند مدل و مسیریابی مدل

سناریو: مسیریابی مدل برای بازبینی آگهی در دیوار

آزمون فصل ۳: انتخاب مدل

مدیریت مدل

چرا انتخاب زودهنگام ابزار به شکست می‌انجامد

سناریو: شش هفته ساخت و صفر کاربر در دیجی‌پی

شکستن کار بزرگ به زیرتسک‌های قابل‌واگذاری

نوشتن معیار پذیرش قابل‌سنجش

سناریو: معیار پذیرش برای خلاصهٔ کتاب در فیدیبو

وابستگی‌ها، محدودیت‌ها و ریسک‌ها

ساختار قرارداد کار: ورودی، خروجی، معیار، مرز

سناریو: قرارداد کار برای گزارش قطعی سرویس در شاتل

آزمون فصل ۴: مدیریت مدل

مهندسی پرامپت و دستورِ کار

تفاوت پرامپت چت با دستورِ کارِ Agent

چهار رکن: Role، Goal، Scope و Constraints

خروجی ساختارمند: JSON، جدول، Markdown

سناریو: چهار رکن دستور کار برای بازبینی زیرنویس در نماوا

استدلال گام‌به‌گام پیش از پاسخ

سناریو: خروجی ساختارمند و استدلال گام‌به‌گام در پیندو

System Prompt و ارتفاع درست دستورالعمل

سناریو: از گفت‌وگوی موفق تا دستور کار شکست‌خورده در ایرانسل

آزمون فصل ۵: مهندسی پرامپت و دستورِ کار

Claude Code: محیط، نشست و ابزارها

آشنایی با Claude Code و جایگاهش میان رقبا

نصب، احراز هویت و اولین نشست Claude Code

آناتومی یک نشست: turn، tool call، چرخه

فضای کاری و مسیرهای کاری در Claude Code

سناریو: فضای کاری اشتباه در مخزن بزرگ کافه‌بازار

فایل CLAUDE.md و دانش پروژه

سناریو: فایل CLAUDE.md که هیچ‌کس رعایتش نمی‌کند در مکتب‌خونه

مدیریت context با clear و compact

سناریو: نشست چهارساعته و افت کیفیت در ورزش‌سه

خواندن، نوشتن، ویرایش فایل و جست‌وجو با Glob و Grep

اجرا، رهگیری و ایمنی: Bash، TodoWrite و Plan Mode

آزمون فصل ۶: Claude Code: محیط، نشست و ابزارها

مهندسی Skill: بسته‌بندی تخصص

مفهوم Skill و Progressive Disclosure

سناریو: قواعد ویرایش که در هر نشست هزینه می‌دهند در طاقچه

ساختار پوشهٔ Skill و فایل SKILL.md

نوشتن name و description مؤثر

سناریو: Skillی که هیچ‌وقت فعال نمی‌شود در نوار

نوشتن بدنهٔ SKILL.md: دستور، مثال، محدودیت

فیلد allowed-tools و فایل‌های همراه

فراخوانی، دستور اسلش و توزیع Skill

سناریو: بدنهٔ Skill و مرز ابزارها در ابرآروان

آزمون فصل ۸: مهندسی Skill: بسته‌بندی تخصص

Subagentها و ایزولاسیون Context

چرا یک Agent کافی نیست و ارزش context جدا

تعریف Subagent در .claude/agents

نوشتن description مؤثر برای فعال‌شدن خودکار

مدیریت Subagentها با agents و عامل‌های آماده

واگذاری و انتقال نتیجه بین Agentها

سناریو: یک نشست شلوغ در تیم جست‌وجوی علی‌بابا

سناریو: تعریف عامل بازبین اقامتگاه در جاباما

موازی‌سازی، اولویت scope و دام‌ها

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

آزمون فصل ۹: Subagentها و ایزولاسیون Context

الگوهای طراحی Agent

Workflow در برابر Agent: مسیر ثابت یا تصمیم پویا

الگوی Prompt Chaining با Gate کیفیت

سناریو: زنجیرهٔ سه‌مرحله‌ای توصیف کالا در ایمالز

الگوهای Routing و Parallelization

سناریو: workflow یا agent برای دسته‌بندی کالا در ترب

الگوی Orchestrator-Workers

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

الگوی Evaluator-Optimizer و ReAct/Reflection

آزمون فصل ۱۰: الگوهای طراحی Agent

مهندسی Context و حافظه

پنجرهٔ محدود و بودجهٔ token

جداکردن سیگنال از نویز در context

فشرده‌سازی تاریخچه با خلاصه و Compaction

بازیابی به‌موقع به‌جای انباشت

سناریو: پنجرهٔ پر از لاگ در تیم پخش تلوبیون

حافظهٔ کوتاه‌مدت و بلندمدت با فایل‌های حافظه

سناریو: حافظه‌ای که هر روز از صفر شروع می‌شود در روبیکا

افت کیفیت در context طولانی و مدیریت آن

سناریو: بودجهٔ token برای بازبینی مقالهٔ بلند در ویرگول

آزمون فصل ۱۲: مهندسی Context و حافظه

کار با داده‌ی چندرسانه‌ای

چطور agent تصویر و PDF را می‌فهمد

استخراج داده از PDF و اسناد اسکن‌شده

سناریو: سه نوع فاکتور و یک مسیر استخراج در زرین‌پال

تحلیل تصویر و screenshot در workflow

سناریو: بازبینی شبانهٔ اسکرین‌شات‌ها در آسان‌پرداخت

تولید خروجی چندرسانه‌ای: نمودار، جدول، گزارش

سناریو: گزارش ماهانه برای هیئت‌مدیره در توسن

آزمون فصل ۱۳: کار با داده‌ی چندرسانه‌ای

Workflow، Orchestration و Hooks

تبدیل کار به Pipeline: ترتیبی، موازی، شرطی

سناریو: شکل درست خط لوله برای گزارش هفتگی در بله

دروازهٔ Approval برای نگه‌داشتن انسان در حلقه

سناریو: دروازهٔ تأیید برای پیام همگانی در ایتا

خودکارسازی با Hooks در چرخهٔ حیات

انتخاب لایهٔ درست: Hook، Skill، Subagent یا Prompt

مدیریت خطا: Retry، Fallback و Idempotency

سناریو: ارسال دوبارهٔ اعلان و انتخاب لایه در سروش

زمان‌بندی، اجرای پس‌زمینه و مستندسازی

آزمون فصل ۱۴: Workflow، Orchestration و Hooks

MCP: استفاده و ساخت سرور

مشکلی که MCP حل می‌کند

معماری MCP: server، client، tools، resources

سناریو: سرور MCP که بالا نمی‌آید در پارس‌آنلاین

اتصال و پیکربندی MCP‌های پرکاربرد

دسترسی و امنیت با کمترین‌دسترسی

سناریو: پانزده پل اختصاصی در فناپ

سناریو: کمترین‌دسترسی برای عامل گزارش‌گیری در بانک سامان

ساخت یک MCP server ساده با ابزار سفارشی

آزمون فصل ۱۵: MCP: استفاده و ساخت سرور

الگوهای کاربردی در حوزه‌های مختلف

سناریوی مارکتینگ: از تحقیق تا تقویم محتوا

سناریوی محصول: از بازخورد تا PRD

سناریوی فریلنسر: پروپوزال و پیگیری

سناریوی تحلیل داده: از فایل خام تا گزارش مدیریتی

ترکیب همه‌چیز: یک سیستم زنده

آزمون فصل ۱۷: الگوهای کاربردی در حوزه‌های مختلف

ارزیابی، عیب‌یابی و Observability

چرا ارزیابی خروجی Agent سخت است

ساخت مجموعهٔ تست با موارد لبه Eval Dataset

روبریک و داوری با LLM-as-Judge

عیب‌یابی سیستم‌های Agentic و ردیابی خطا

پایش هزینه و تأخیر با Observability

آزمون فصل ۱۸: ارزیابی، عیب‌یابی و Observability

Production: هزینه، امنیت و استقرار

از Prototype تا Production: چه چیزی سیستم را آماده می‌کند؟

کاهش هزینه: چهار اهرم از Prompt Caching تا مسیریابی مدل

تزریق پرامپت و نشت داده: حمله‌ها و دفاع‌ها Prompt Injection

قفس، قفل و قانون: حاکمیت Agent در Production

استقرار و تحویل سیستم به تیم

آزمون فصل ۱۹: Production: هزینه، امنیت و استقرار

پشت هر *agent*، از یک اسکریپت ۵۰ خطی تا بزرگ‌ترین سیستم تولیدی، فقط چهار قطعه هست: **مدل**، **ابزار**، **حلقه** و **حافظه**. در معماری‌ای که در این دوره بررسی می‌کنیم، با حذف هرکدام از این چهار قطعه، چیزی که می‌ماند دیگر *agent* نیست. با داشتن این نقشه، هر مفهوم تازه‌ای که بعداً ببینید به یک سؤال ساده تبدیل می‌شود: «این کدام قطعه را غنی می‌کند؟».

![کاور درس‌نامه: چهار جزء یک agent](/qbox/download/f0GxjwSs8a/cover.svg)

## چهار قطعه و ترتیب کارشان

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

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

## مدل و ابزار: مغز و دست‌ها

منظور از مدل یک *LLM* مدرن است، مثل `claude-sonnet-5`. مهم‌ترین ویژگی‌اش این است که **بی‌حالت** است: متن می‌گیرد، متن یا درخواست ابزار می‌دهد و بعد **هیچ چیزی به یاد ندارد**. همان درخواست را دوباره بفرستید، همان‌طور پاسخ می‌دهد که انگار برای اولین بار آن را دریافت کرده است؛ مگر خودتان تاریخچه را در ورودی بگنجانید.

![مدل: ورودی، خروجی و آنچه نمی‌تواند بکند](/qbox/download/JWUajDbG28/model-anatomy.svg)

ورودی مدل هرچیزی است که در حافظه قرار دارد: *prompt* سیستمی و قواعد، پیام‌های قبلی، فهرست ابزارها با *schemaشان* و نتایج اجرای ابزارها. خروجی‌اش فقط دو شکل دارد:

- **درخواست ابزار (*tool_use*):** در یک ساختار قراردادی می‌گوید «ابزار `Read` را با این ورودی اجرا کن».
- **پیام متنی نهایی:** نشان‌دهندهٔ این است که کار تمام شده و حلقه باید متوقف شود.

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

فهرست کارهایی که مدل **نمی‌تواند** بکند هم به همان اندازه مهم است. خودش کد اجرا نمی‌کند، وب نمی‌گردد و فایلی را تغییر نمی‌دهد. دیروز را هم به یاد نمی‌آورد و چیزی بیرون از *context window* نمی‌بیند. هر کدام از این کارها که در *agent* شما انجام می‌شود، کار یکی از سه قطعهٔ دیگر است.

ابزار هم یک تابع برنامه‌نویسی معمولی است. جعبه‌ابزار پیش‌فرض *Claude Code* کوچک و در عمل کافی است: `Read`، `Write`، `Edit`، `Bash`، `Glob` و `Grep`. تعریف هر ابزار سه بخش دارد.

- **نام:** کوتاه و یکتا.
- **توضیح:** یکی‌دو جمله دربارهٔ این‌که ابزار چه کار می‌کند.
- **قالب ورودی:** یک *JSON Schema* که ساختار ورودی و آرگومان‌های ابزار را تعیین می‌کند؛ مثلاً برای `Read` به شکل `{"type": "object", "properties": {"file_path": {"type": "string"}}}` که تنها فیلد اجباری‌اش `file_path` از نوع رشته است.

توضیح، تنها چیزی است که مدل برای تصمیمِ «کِی این ابزار را فراخوانی کنم» می‌بیند. توضیح مبهم باعث می‌شود مدل نتواند ابزار را به‌درستی انتخاب کند: می‌تواند آن را فراخوانی کند، ولی نمی‌داند چه زمانی باید این کار را بکند.

هر ابزار یک **اثر جانبی** هم دارد. ابزار `Read` فقط می‌خواند، ولی `Write` دیسک را عوض می‌کند. ابزار `Bash` هم می‌تواند از ساختن فایل تا پاک کردن پروژه هر کاری بکند. پس اندازهٔ جعبه‌ابزار یک تصمیم طراحی است. گاهی **کاهش تعداد ابزارها** به مدل کمک می‌کند بهتر تصمیم بگیرد. گاهی هم اضافه کردن ابزار تازه از راه *MCP* دامنهٔ کار *agent* را گسترش می‌دهد.

## حلقه و حافظه: موتور و آنچه باقی می‌ماند

تعداد چرخه‌های حلقه به کار بستگی دارد. «اسم فایل اصلی پروژه چیست؟» با یک `Read` تمام می‌شود، ولی «این *bug* را پیدا کن و تست‌ها را سبز کن» ده‌ها چرخه می‌خواهد. دو نکته دربارهٔ حلقه همه‌چیز را روشن می‌کند:

- حلقه **در کد شما** اجرا می‌شود، نه در مدل. پس ثبت *log*، شمارش *token*، اعمال مجوز و گرفتن تأیید برای ابزارهای خطرناک، همه دست شماست.
- حلقه **منطق کار را نمی‌داند**؛ فقط مدل را فراخوانی می‌کند، ابزار را اجرا می‌کند و نتیجه را اضافه می‌کند. همین جداسازی کد شما را ساده نگه می‌دارد.

![لایه‌های حافظه: کوتاه‌مدت در context و بلندمدت در فایل](/qbox/download/Q8U3V7BGx8/memory-layers.svg)

**حافظهٔ کوتاه‌مدت** همان *context window* است: گفت‌وگوی این نشست، نتایج ابزارها و نقشهٔ فعلی کار. هر گام بزرگ‌ترش می‌کند، حدود ۲۰۰ هزار *token* سقف دارد و با بستن نشست یا اجرای `/clear` کامل پاک می‌شود. **حافظهٔ بلندمدت** فایل‌های روی دیسک‌اند:

- فایل `CLAUDE.md` برای قواعد دائمی پروژه که هر نشست بارگذاری می‌شود.
- فایل `MEMORY.md` برای یافته‌هایی که *agent* تصمیم گرفته نگه دارد.
- پوشه‌هایی مثل `notes/` برای خروجی کار.

پل بین این دو، دو طرفه است. فرض کنید *agent* تشخیص می‌دهد فایل `auth.py` فقط روز جمعه خطا می‌دهد. اگر این یافته فقط در *context* بماند، با بستن نشست از بین می‌رود. اگر با `Write` در `notes/findings.md` ذخیره شود، هفتهٔ بعد با یک `Read` برمی‌گردد. **قاعدهٔ عملی:** هر چیزی که ارزش دارد دوباره گفته شود، باید در فایل ذخیره شود نه در گفت‌وگو. یک وجه هزینه‌ای هم دارد. کل تاریخچه در هر فراخوانی دوباره به مدل ارسال می‌شود، بنابراین هرچه حافظهٔ کوتاه‌مدت بزرگ‌تر شود، هر گام گران‌تر و کندتر می‌شود.

## یک نوبت کاری از نزدیک

کاربر می‌گوید «فایل `sales.csv` را خلاصه کن». برای رسیدن به پاسخ، هشت گام طی می‌شود.

![سفر یک درخواست بین چهار جزء](/qbox/download/0iMmPN0owf/interaction-diagram.svg)

پیام کاربر همراه قواعد وارد حافظه می‌شود و کل آن به مدل ارسال می‌شود. مدل تشخیص می‌دهد که ابتدا باید فایل خوانده شود و یک *tool_use* با نام `Read` تولید می‌کند. حلقه تابع واقعی را اجرا می‌کند، ۴۰ ردیف داده برمی‌گردد و نتیجه به انتهای حافظه اضافه می‌شود. سپس مدل برای بار دوم فراخوانی می‌شود؛ این بار داده‌ها در اختیار مدل قرار دارند. حالا خلاصه را به‌صورت متن می‌نویسد؛ حلقه تشخیص می‌دهد خروجی از نوع `text` است نه `tool_use`، پس کار را تمام می‌کند. مدل و حافظه هرکدام **دو بار** ظاهر شدند و تنها گامی که در محیط اجرا انجام شد، اجرای ابزار بود.

![پیاده‌سازی حلقهٔ کمینه به زبان Python](/qbox/download/0WFEhXG4GZ/minimal-loop-code.svg)

همین ساختار در قالب سیزده خط کد پیاده‌سازی می‌شود. سه مورد از این چهار جزء مستقیماً در کد دیده می‌شوند و مدل از راه فراخوانی *API* وارد کار می‌شود:

- **ابزار:** تابع `run_tool`، تنها جایی که *agent* با دنیای بیرون تعامل می‌کند.
- **حافظه:** لیست `messages` که با پایان تابع از بین می‌رود.
- **حلقه:** یک `for` با سقف `range(50)`. این سقف یک مقدار عملی و قابل تنظیم است: هم برای کارهای متوسط کافی است، هم از ادامهٔ بی‌پایان حلقه جلوگیری می‌کند.

در هر گام، اگر مدل درخواست ابزاری نداشت پاسخ نهایی برمی‌گردد. اگر داشت، نتیجه در قالب `tool_result` به حافظه اضافه می‌شود.

این کد آموزشی است، نه آمادهٔ تولید. نسخهٔ واقعی به چهار چیز دیگر هم نیاز دارد: مدیریت خطای ابزار، شمارش *token*، ثبت *log* و گرفتن تأیید پیش از ابزارهای خطرناک مثل `Bash`. برای پروژهٔ واقعی سراغ *Claude Agent SDK* یا چارچوب‌های مشابه بروید. آن‌جا هم همان چهار قطعه سر جایشان هستند و فقط در یک لایهٔ آماده پیاده‌سازی شده‌اند. مفاهیم پیشرفته هم در همین نقشه قرار می‌گیرند و هر کدام یکی از همین چهار قطعه را غنی می‌کنند:

- می‌توان جعبه‌ابزار را با یک پروتکل استاندارد گسترش داد، بدون آن‌که کد *agent* عوض شود؛ این کار **ابزار** را غنی می‌کند.
- می‌توان کارها را بین چند *agent* با حلقه و حافظهٔ مستقل تقسیم کرد؛ این کار **حلقه** را غنی می‌کند.
- می‌توان مجموعه قواعد و دانش تخصصی را در قالب بسته‌های متنی در حافظه بارگذاری کرد؛ این کار **حافظه** را غنی می‌کند.

آموزش عملی Agentic AI