ساخت AI agent با Claude روی VPS

مفهوم ساخت یک agent با Claude

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

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

Claude مغز است: Messages API

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

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

استفاده از ابزار، حلقه agent است

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

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

سه روش برای ساخت، و کدام برای VPS مناسب است

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

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

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

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

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

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

انتخاب یک مدل

Claude در مدل‌های مختلفی عرضه می‌شود و انتخاب یکی از آن‌ها معامله‌ای بین توانایی، سرعت و هزینه است. در زمان نگارش این متن، انتخاب‌های اصلی عبارتند از: Claude Opus 4.8 (claude-opus-4-8)، گزینه پیش‌فرض و توانمند برای استدلال‌های سخت و اجراهای طولانی agent؛ 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، هر دوی این موارد از اجرای agent به عنوان یک سرویس سیستمی امن‌شده حاصل می‌شود، نه به عنوان برنامه‌ای که خودتان به صورت دستی در یک ترمینال اجرا کرده‌اید. به عنوان یک سرویس، در هنگام بوت شدن اجرا می‌شود، در صورت کرش کردن دوباره شروع به کار می‌کند و در journal لاگ می‌گیرد. در حالت امن‌شده، به عنوان یک کاربر بدون امتیاز (unprivileged user) با تنها دسترسی‌های مورد نیاز اجرا می‌شود، بنابراین یک باگ یا دستور اشتباه، سقف محدودی خواهد داشت.

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

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

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

FAQ

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

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

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

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

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

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

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

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

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

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