آموزش ساخت AI Agent با Claude روی VPS

ساخت یک عامل (Agent) با Claude به چه معناست

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

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

Claude مغز متفکر است: Messages API

هر فراخوانی به Claude از طریق یک endpoint واحد به نام Messages API انجام می‌شود. شما کل تاریخچه گفتگو تا آن لحظه و فهرستی از ابزارهایی که عامل (agent) ممکن است استفاده کند را ارسال می‌کنید؛ Claude پیام بعدی خود را بازمی‌گرداند. آن پیام یا یک پاسخ نهایی است و یا درخواستی برای فراخوانی یک ابزار. برای مسیر ساخت‌وساز شخصی، هیچ "API عامل" مجزایی وجود ندارد: استفاده از ابزار، قابلیتی از همین یک endpoint است و مدیریت حلقه (loop) پیرامون آن بر عهده شماست.

Claude بین فراخوانی‌ها فاقد وضعیت (stateless) است، به این معنی که به‌تنهایی چیزی را به خاطر نمی‌سپارد. هر درخواست شامل کل گفتگو است. کد شما تاریخچه را نگه می‌دارد و در هر نوبت آن را ارسال می‌کند، که این دلیل افزایش هزینه توکن‌ها در هر نوبت از یک نشست طولانی است. این موضوع بیش از آنکه یک محدودیت باشد، یک انتخاب طراحی است: از آنجا که وضعیت (state) روی سرور شما قرار دارد، شما دقیقاً تصمیم می‌گیرید که Claude چه چیزی را ببیند و هیچ بخشی از وظیفه در جایی که تحت کنترل شما نیست، ذخیره نمی‌شود. این موضوع به این معنی است که prompt مدام بزرگ‌تر می‌شود و اگرچه پنجره کانتکست Claude به‌راحتی آن را می‌پذیرد، یک مدل محلی در همان حلقه این کار را نخواهد کرد؛ به همین دلیل است که Ollama پیش از آنکه promptهای طولانی را قطع کند، نیاز به افزایش num_ctx دارد.

استفاده از ابزار، همان حلقهٔ عامل (agent loop) است

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

شما می‌توانید این حلقه را به‌صورت دستی در چند خط بنویسید و بسیاری از افراد نیز همین کار را انجام می‌دهند، زیرا مشاهده و کنترل آن آسان است. SDKهای رسمی نیز یک اجراکنندهٔ ابزار (tool runner) ارائه می‌دهند که این حلقه را برای شما هدایت می‌کند: شما توابع ابزار را ارائه می‌دهید و SDK رفت‌وبرگشتِ فراخوانی Claude، اجرای ابزارها و بازگرداندن نتایج تا زمان پایان کار Claude را مدیریت می‌کند. در هر دو حالت، ساختار یکسان است. اجراکننده فقط شما را از نوشتن دستی حلقه بی‌نیاز می‌کند. اگر این حلقه هنوز برایتان انتزاعی به نظر می‌رسد، راه حل این است که پیش از استفاده از یک اجراکننده، یک نمونهٔ حداقلی از آن را بنویسید؛ این همان گامی است که همهٔ موارد دیگر در این مسیر مرحله‌بندی‌شده برای یادگیری عامل‌های هوش مصنوعی از صفر به آن وابسته هستند.

سه روش برای ساخت، و تناسب آن‌ها با VPS

سه روش برای ساخت یک agent مبتنی بر Claude وجود دارد که تفاوت آن‌ها در میزان زیرساختی است که شما مدیریت می‌کنید.

روش اول، استفاده از کد شخصی برای فراخوانی Claude API با ابزارهای اختصاصی خودتان است. شما حلقه (loop) را می‌نویسید یا از tool runner موجود در SDK استفاده می‌کنید و کل برنامه را روی VPS خود میزبانی می‌کنید. این روش انتخاب رایجی است، زیرا کنترل کاملی بر ابزارها، داده‌ها و امنیت به شما می‌دهد و به عنوان یک برنامه معمولی روی سرور اجرا می‌شود. بخش عمده‌ای از این راهنما بر پایه همین مسیر است.

روش دوم، استفاده از Claude Agent SDK است. این در واقع Claude Code، یعنی همان agent کدنویسی است که به صورت یک کتابخانه برای توسعه ارائه شده است. این SDK شامل یک حلقه کامل agent و ابزارهای داخلی برای خواندن و نوشتن فایل‌ها، اجرای دستورات shell و جستجو است، بنابراین نیازی نیست آن‌ها را از صفر بسازید. این ابزار نیز روی سرور شخصی شما اجرا می‌شود و زمانی که به یک agent توانمند برای کار با فایل و shell نیاز دارید و نمی‌خواهید زیرساخت آن را خودتان پیاده‌سازی کنید، گزینه‌ای بسیار مناسب برای VPS است. agentای که فایل‌ها را می‌خواند و دستورات shell را اجرا می‌کند، پیش از آنکه بتواند بدون نظارت کار کند، به محدودسازی نیاز دارد و اجرای ایمن Claude Code روی سرور سیستم مجوزها، sandbox و گزینه‌های ایزوله‌سازی را پوشش می‌دهد.

روش سوم، Managed Agents است که در آن Anthropic حلقه اجرا را مدیریت کرده و یک sandbox میزبانی می‌کند که ابزارهای agent در آن اجرا می‌شوند. این گزینه‌ای است که نیاز به دخالت کمتری دارد: عملیات اجرایی بسیار کمتری بر عهده شماست، اما فضای کاری agent به جای VPS شما، روی زیرساخت Anthropic قرار دارد. زمانی از این روش استفاده کنید که می‌خواهید کمترین کار عملیاتی را داشته باشید و نیازی ندارید که ابزارها روی ماشین شخصی شما اجرا شوند. در دو روش دیگر، سرور شما میزبان agent است که موضوع اصلی ادامه این راهنماست.

اتصال ابزارها با MCP

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

انتخاب مدل

مدل Claude در نسخه‌های متعددی عرضه می‌شود و انتخاب هر یک، موازنه‌ای میان توانمندی، سرعت و هزینه است. تا زمان نگارش این متن، گزینه‌های اصلی عبارتند از: Claude Opus 4.8 (claude-opus-4-8) که گزینه پیش‌فرض و توانمند برای استدلال‌های پیچیده و اجرای طولانی‌مدت عامل‌ها (agent runs) است؛ Claude Sonnet 5 (claude-sonnet-5) که گزینه‌ای متعادل بوده و در عین ارزان‌تر و سریع‌تر بودن، در بسیاری از وظایف عملکردی نزدیک به Opus دارد؛ و Claude Haiku 4.5 (claude-haiku-4-5) که سریع‌ترین و ارزان‌ترین مدل برای مراحل ساده و با حجم بالاست. بالاتر از این‌ها، Claude Fable 5 (claude-fable-5) قرار دارد که توانمندترین مدل برای سخت‌گیرانه‌ترین کارهاست. از شناسه دقیق مدل در کد خود استفاده کنید و هیچ تاریخی به آن اضافه نکنید.

یک الگوی کاربردی، ترکیب این مدل‌هاست. اجازه دهید یک مدل ارزان‌تر، فراخوانی‌های معمول ابزارها را مدیریت کند و یک مدل قوی‌تر، تصمیمات دشوار را بر عهده بگیرد. از آنجا که مدل در درخواست شما صرفاً یک رشته متنی (string) است، تغییر آن تنها با یک خط کد انجام می‌شود؛ بنابراین با یک مدل پیش‌فرض توانمند شروع کنید و در مواردی که سرعت یا هزینه اهمیت بیشتری نسبت به جزئیات نهایی کیفیت دارند، به سمت مدل‌های سبک‌تر بروید.

اجرای آن به عنوان یک سرویس امن‌سازی‌شده روی VPS

یک عامل (agent) تنها زمانی مفید است که به‌طور مداوم در حال اجرا باشد و تنها زمانی ایمن است که محدود شده باشد. روی یک VPS، هر دوی این موارد با اجرای عامل به عنوان یک سرویس سیستمی امن‌سازی‌شده (hardened system service) محقق می‌شود، نه به عنوان برنامه‌ای که به‌صورت دستی در ترمینال اجرا کرده‌اید. به عنوان یک سرویس، برنامه هنگام بوت سیستم شروع به کار می‌کند، در صورت کرش کردن دوباره راه‌اندازی می‌شود و لاگ‌های خود را در journal ثبت می‌کند. در حالت امن‌سازی‌شده، برنامه با یک کاربر بدون امتیاز (unprivileged user) و تنها با دسترسی‌های مورد نیاز اجرا می‌شود؛ بنابراین یک باگ یا دستور مخرب، سقف دسترسی محدودی خواهد داشت. یک unit سرویس تنها می‌تواند محدود کند که پردازش به چه چیزی دسترسی داشته باشد، بنابراین باقی موارد باید درون خودِ harness عامل مدیریت شود؛ کاری که افزونه‌های DeepSeek Harness که ارزش نصب دارند در پشته‌ای متفاوت انجام می‌دهند: تعیین سقف هزینه، قوانین دسترسی برای هر ابزار و اسکن برای جلوگیری از prompt-injection.

مهم‌ترین قانون این است که کلید API مربوط به Claude را در سمت سرور نگه دارید. این کلید هزینه هر فراخوانی را پرداخت کرده و آن را مجاز می‌کند، بنابراین باید در فایلی قرار بگیرد که فقط توسط کاربرِ عامل قابل خواندن باشد، به عنوان یک متغیر محیطی (environment variable) در سرویس بارگذاری شود و هرگز در کد، مخزن (repository) یا هر جایی که مرورگر به آن دسترسی دارد، قرار نگیرد. یک unit سرویس کامل و امن‌سازی‌شده برای عامل خود را در اینجا ایجاد کنید:

سپس پیکربندی سرور را تکمیل کنید. SSH را فقط روی کلیدها تنظیم کنید و حسابی که با آن مدیریت می‌کنید را طبق امن‌سازی SSH روی VPS محدود کنید. اگر ترجیح می‌دهید در حین ساخت عامل، آن را از یک نشست تعاملی کنترل کنید، اجرای Claude Code روی VPS با tmux گزینه مناسبی است. هنگامی که نشست دوم را روی همان سیستم باز کردید، این دو می‌توانند کارها را بین خود رد و بدل کنند تا نیازی نباشد شما هر دستور را از یک پنجره به پنجره دیگر منتقل کنید. و اگر به دنبال مفاهیم پشت این موارد هستید، بدون اینکه به یک مدل خاص وابسته باشید، راهنمای مکمل ساخت عامل هوش مصنوعی شخصی روی VPS مبانی آن را تشریح می‌کند.

اگر به دنبال یک دستیار کدنویسی ترمینالی هستید، اجرای یک عامل هوش مصنوعی کدنویسی روی VPS ابزارهای Aider و Goose را پوشش می‌دهد.

FAQ

برای ساخت یک عامل (agent) از کدام مدل Claude استفاده کنم؟

با Claude Opus 4.8 (claude-opus-4-8) که گزینه پیش‌فرض و توانمند است شروع کنید و سپس بر اساس نیاز تغییر دهید. مدل Claude Sonnet 5 (claude-sonnet-5) برای اکثر کارها ارزان‌تر و سریع‌تر است، Claude Haiku 4.5 (claude-haiku-4-5) برای مراحل ساده با حجم بالا بهترین گزینه است و Claude Fable 5 (claude-fable-5) برای دشوارترین وظایف بیشترین توانایی را دارد. یک الگوی رایج این است که برای مراحل روتین از مدل ارزان‌تر و برای تصمیمات پیچیده از مدل قوی‌تر استفاده کنید، چرا که تغییر مدل تنها با یک خط کد انجام می‌شود.

آیا کل عامل را روی VPS خودم اجرا کنم یا Anthropic آن را میزبانی می‌کند؟

این موضوع به رویکرد شما بستگی دارد. اگر حلقه (loop) اختصاصی خود را برای کار با Claude API بنویسید یا از Claude Agent SDK استفاده کنید، عامل کاملاً روی VPS شما اجرا می‌شود و فقط فراخوانی‌های مدل به سمت Anthropic ارسال می‌گردد. اگر از Managed Agents استفاده کنید، Anthropic حلقه را اجرا کرده و sandboxای که ابزارها در آن اجرا می‌شوند را میزبانی می‌کند، بنابراین بخش کمتری از آن روی سرور شما قرار می‌گیرد. برای عاملی که روی ماشین خودتان اجرا می‌شود، از یکی از دو روش اول استفاده کنید.

تفاوت Claude API با Claude Agent SDK چیست؟

Claude API همان endpoint خام Messages است: شما یک گفتگو و ابزارها را ارسال می‌کنید و خودتان حلقه عامل را می‌نویسید یا از ابزار اجرای ابزار (tool runner) موجود در SDK برای هدایت آن استفاده می‌کنید. Claude Agent SDK یک کتابخانه سطح بالاتر است، یعنی همان Claude Code که برای توسعه بسته‌بندی شده و شامل یک حلقه کامل به همراه ابزارهای داخلی فایل، shell و جستجو است. زمانی که می‌خواهید همه چیز را خودتان تعریف کنید از API استفاده کنید و زمانی که می‌خواهید بدون سرهم‌بندی زیرساخت، یک عامل توانمند داشته باشید، از Agent SDK استفاده کنید.

چگونه کلید Claude API خود را روی سرور امن نگه دارم؟

آن را سمت سرور و خارج از کد خود نگه دارید. کلید را در فایلی ذخیره کنید که فقط توسط حسابی که عامل با آن اجرا می‌شود قابل خواندن باشد، آن را به عنوان یک متغیر محیطی (environment variable) در سرویس بارگذاری کنید و هرگز آن را در مخزن (repository) commit نکنید یا در مرورگر در معرض دید قرار ندهید. از آنجا که هر درخواست به Claude از سرور شما ارسال می‌شود، کلید هرگز نیازی به رسیدن به دستگاه کاربر ندارد؛ همین موضوع باعث می‌شود امنیت عاملی که روی سرور اجرا می‌شود، نسبت به عاملی که در یک برنامه کلاینت تعبیه شده، ساده‌تر تأمین شود.

آیا برای ساخت عامل با Claude نیاز به میزبانی محلی مدل (self-host) دارم؟

خیر. در Claude، مدل یک سرویس میزبانی‌شده است که از طریق API آن را فراخوانی می‌کنید، بنابراین نیازی به اجرای چیزی روی GPU نیست. VPS شما حلقه عامل، ابزارها و داده‌ها را اجرا می‌کند و فرآیند استدلال در سمت Anthropic انجام می‌شود. این همان چیزی است که به یک سرور معمولی اجازه می‌دهد یک عامل توانمند را اجرا کند. اگر به جای این، یک مدل کاملاً محلی می‌خواهید، آن مسیر همان self-hosted است که در راهنمای مکملِ ساخت عامل هوش مصنوعی شخصی پوشش داده شده است.