آموزش ساخت 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

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

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

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

روش سوم، استفاده از Managed Agents است که در آن Anthropic حلقه اجرا را مدیریت می‌کند. به‌صورت پیش‌فرض، ابزارهای عامل در یک sandbox که توسط Anthropic میزبانی می‌شود اجرا می‌گردند، بنابراین فضای کاری عامل به‌جای VPS شما، روی زیرساخت Anthropic قرار دارد. از تاریخ 11 اکتبر 2026، یک گزینه sandbox خود-میزبان (self-hosted) که هنوز در مرحله بتا است، به یک پردازش worker روی سرور شما اجازه می‌دهد تا فراخوانی ابزارها را انجام دهد، در حالی که حلقه اجرا همچنان نزد Anthropic باقی می‌ماند. زمانی که به دنبال کمترین میزان کار عملیاتی هستید و نیازی ندارید که خودِ حلقه اجرا روی ماشین شما باشد، از Managed Agents استفاده کنید. در دو روش دیگر، سرور شما میزبان کل عامل است که موضوع اصلی ادامه این راهنماست.

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

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

انتخاب مدل

مدل‌های Claude در نسخه‌های مختلفی عرضه می‌شوند و انتخاب بین آن‌ها، موازنه‌ای میان توانمندی، سرعت و هزینه است. تا تاریخ 11 اکتبر 2026، مجموعه فعلی شامل Claude Opus 5.5 (claude-opus-5-5) است که Anthropic آن را به عنوان نقطه شروع برای اکثر بار کاری و ساخت پروژه‌های برنامه‌نویسی ایجنتیک (agentic) طولانی‌مدت و کارهای دانشی توصیه می‌کند؛ Claude Sonnet 5.5 (claude-sonnet-5-5) که گزینه‌ای متعادل، ارزان‌تر و سریع‌تر است؛ و Claude Haiku 5.5 (claude-haiku-5-5) که سریع‌ترین و ارزان‌ترین مدل برای مراحل ساده و با حجم بالاست. بالاتر از این‌ها، Claude Fable 5.1 (claude-fable-5-1) قرار دارد که توانمندترین مدل در دسترس برای تمامی مشتریان است و برای استدلال‌های پیچیده و کارهای ایجنتیک با افق طولانی کاربرد دارد. مدل‌های قدیمی‌تر مانند Claude Opus 4.8 و Claude Fable 5 همچنان در دسترس هستند اما اکنون در دسته legacy طبقه‌بندی می‌شوند. در کد خود از شناسه دقیق مدل استفاده کنید و هیچ تاریخی به آن اضافه نکنید.

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

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

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

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

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

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

FAQ

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

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

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

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

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

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

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

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

آیا برای ساخت یک agent با Claude نیاز به self-host کردن مدل دارم؟

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