راهنمای عملی Prime Agent به زبان ساده: نصب روی مک و لینوکس، ورود به ارائه‌دهنده مدل، فایل AGENTS.md، زیرایجنت‌ها، کارهای پس‌زمینه، MCP و اتصال به مدلی روی سرور خودتان.
Prime Agent ایجنت متن‌باز شرکت Prime Intellect برای برنامه‌نویسی و پژوهش است و برای کارهای طولانی طراحی شده است. در ترمینال اجرا می‌شود، در پوشه پروژه شما فایل می‌خواند و می‌نویسد و فرمان اجرا می‌کند. فرقش با ایجنت‌های آشنا این است که مدل به‌جای فهرستی از ابزارهای جدا، فقط یک ابزار دارد: یک محیط پایتون که بین نوبت‌ها باقی می‌ماند. مدل در همین محیط کد می‌نویسد تا فایل‌ها را بخواند، فرمان اجرا کند، نتیجه‌های بزرگ را در متغیر نگه دارد و کار را میان زیرایجنت‌ها تقسیم کند.
این راهنما از صفر شروع می‌کند: پیش‌نیازها و حساب لازم، نصب، اولین جلسه، فایل دستورکار پروژه، ایمنی، دستورهای روزانه، زیرایجنت‌ها، کارهای پس‌زمینه، اتصال ابزارهای بیرونی و اجرای خودکار. همه فرمان‌ها و نام‌ها در ۶ مهر ۱۴۰۵ (۲۸ سپتامبر ۲۰۲۶) با مخزن رسمی Prime Agent و مقاله معرفی آن در وبلاگ Prime Intellect تطبیق داده شده‌اند. پروژه تازه است و سریع تغییر می‌کند؛ اگر فرمانی رفتار دیگری داشت، صفحه مستندات پیوندشده را ببینید.
تصویر رسمی معرفی Prime Agent
تصویر رسمی Prime Intellect. عددهای مقاله معرفی درباره همان آزمون‌هاست، نه تضمینی برای پروژه و مدل شما.
بیشتر ایجنت‌های برنامه‌نویسی چند ابزار جدا به مدل می‌دهند: یکی برای خواندن فایل، یکی برای ویرایش، یکی برای اجرای فرمان. در Prime Agent مدل فقط ابزار ipython را دارد؛ یک محیط پایتون ماندگار که متغیرهایش بین نوبت‌ها از بین نمی‌رود. همه کارها، از خواندن و ویرایش فایل تا اجرای فرمان پروژه و مدیریت حافظه کاری، با کد پایتون انجام می‌شود. نتیجه عملی این است که مدل می‌تواند یک گزارش خطای بزرگ یا فهرست فایل‌های یک مخزن بزرگ را در یک متغیر نگه دارد، رویش جست‌وجو کند و فقط تکه مرتبط را بخواند، به‌جای اینکه همه‌اش را در گفت‌وگو کپی کند.
دو ایده اصلی پروژه این‌هاست:
rlm.spawn(...) زیرایجنت واقعی می‌سازد. هر زیرایجنت جلسه خودش را دارد، کار مستقلی انجام می‌دهد و نتیجه را به‌صورت پیام برای ایجنت اصلی می‌فرستد یا در فایل می‌نویسد./refine مسیر کار جلسه را مرور می‌کند و می‌تواند درس‌های کوچک و مستند را به دستورکار تکمیلی، حافظه یا شرح مهارت‌ها اضافه کند. طبق مستندات، دستورکار پایه سیستم هرگز بازنویسی نمی‌شود و از هر تغییر نسخه‌ای ثبت می‌شود که می‌شود به آن برگشت.Prime Agent برای کارهای طولانی مناسب است: بررسی یک مخزن بزرگ، پژوهش چندمرحله‌ای، اجرای ارزیابی مدل‌ها، یا کاری که باید بعد از بستن ترمینال هم ادامه پیدا کند. برای اصلاح کوتاه یک فایل، ابزارهای ساده‌تری مثل Claude Code، Codex یا OpenCode معمولاً سریع‌تر به نتیجه می‌رسند. پروژه با مجوز MIT منتشر شده و بر پایه ابزار متن‌باز pi ساخته شده است.
طبق راهنمای شروع سریع و صفحه ارائه‌دهنده‌ها:
فرمان نصب رسمی، آخرین نسخه پایدار را نصب می‌کند:
curl --proto '=https' --proto-redir '=https' -fsSL https://app.primeintellect.ai/prime-agent/install.sh | sh
گزینه‌های --proto کاری می‌کنند که دریافت و هر تغییر مسیر فقط از راه HTTPS انجام شود. برای امتحان آخرین نسخه آزمایشی که از شاخه اصلی ساخته می‌شود، به انتهای همین فرمان -s -- beta اضافه می‌شود. هر دو فرمان نسخه‌های منتشرشده را دریافت می‌کنند و دستور prime-agent را نصب می‌کنند. پیش از اجرای اسکریپتی که مستقیم به شل داده می‌شود، محتوایش را ببینید.
مستندات راه دومی هم برای اجرا از روی کد منبع دارد که به Node.js نسخه 22.8.0 یا بالاتر نیاز دارد:
git clone https://github.com/PrimeIntellect-ai/prime-agent
cd prime-agent
npm ci
./prime-agent.sh
بعد از نصب، یک پنجره ترمینال تازه باز کنید و نصب را بررسی کنید:
prime-agent --version
prime-agent status
prime-agent doctor
فرمان اول شماره نسخه را چاپ می‌کند، دومی وضعیت سرویس‌های پس‌زمینه را نشان می‌دهد و سومی مشکلات آن‌ها را پیدا می‌کند. prime-agent doctor --fix مشکلات را تعمیر هم می‌کند؛ اول بدون --fix ببینید چه چیزی را می‌خواهد عوض کند. برای به‌روزرسانی، فرمان prime-agent update را بزنید.
به پوشه پروژه بروید و Prime Agent را اجرا کنید:
cd /path/to/project
prime-agent
داخل برنامه دستور /login را بزنید و ارائه‌دهنده را انتخاب کنید. اگر کلید API دارید، می‌توانید پیش از اجرا آن را در متغیر محیطی بگذارید؛ مثلاً ANTHROPIC_API_KEY. کلیدها و توکن‌های ورود در فایل ~/.prime/agent/auth.json ذخیره می‌شوند که فقط کاربر خودتان اجازه خواندنش را دارد. مستندات راهی هم برای نگه نداشتن کلید به‌صورت متن ساده دارد: مقدار کلید در این فایل می‌تواند فرمانی باشد که با ! شروع می‌شود و کلید را از جاکلیدی سیستم یا مدیر رمز می‌خواند.
رابط ترمینالی رسمی Prime Agent
نمای رسمی رابط ترمینالی از مقاله معرفی Prime Agent.
در شروع فقط سؤال بپرسید و هنوز چیزی را تغییر ندهید. چند نمونه خوب برای جلسه اول:
Prime Agent در پوشه‌ای که از آن اجرا شده کار می‌کند و می‌تواند فایل‌هایش را تغییر دهد. پیش از اولین تغییر واقعی، مطمئن شوید پروژه زیر کنترل git است و git status تغییر ذخیره‌نشده‌ای نشان نمی‌دهد؛ بهتر از آن، یک کپی جدا یا یک شاخه کاری تمیز با git worktree برای کار ایجنت بسازید. با تایپ @ در ویرایشگر می‌توانید فایلی را به درخواست پیوست کنید. دستور !npm run lint فرمانی را اجرا می‌کند و خروجی‌اش را به مدل می‌دهد و !! همین کار را بدون فرستادن خروجی به مدل انجام می‌دهد. جلسه‌ها خودکار در ~/.prime/agent/sessions/ ذخیره می‌شوند؛ prime-agent -c آخرین جلسه را ادامه می‌دهد و prime-agent -r فهرست جلسه‌ها را باز می‌کند.
Prime Agent در شروع هر جلسه فایل‌های دستورکار را می‌خواند. طبق صفحه استفاده روزانه، این فایل‌ها از سه جا بارگذاری می‌شوند:
~/.prime/agent/AGENTS.md برای دستورهای شخصی شما در همه پروژه‌ها؛در پوشه فعلی و پوشه‌های بالاتر، فایل AGENTS.md یا CLAUDE.md خوانده می‌شود؛ پس اگر پروژه از قبل برای ابزار دیگری دستورکار دارد، Prime Agent هم از آن استفاده می‌کند. یک نمونه کوتاه:
# Project instructions
- Run npm run check after every code change
- Do not run production migrations locally
- Never edit generated files under src/generated/; run npm run generate
- Persian UI strings live in locales/fa.json; keep Persian digits
- Done means: checks pass and the git diff has been reviewed
بعد از تغییر این فایل، برنامه را دوباره باز کنید یا دستور /reload را بزنید. گزینه --no-context-files خواندن این فایل‌ها را خاموش می‌کند. اگر بخواهید دستورکار پایه سیستم را کامل عوض کنید، فایل SYSTEM.md در .prime/agent/ پروژه یا در ~/.prime/agent/ این کار را می‌کند و APPEND_SYSTEM.md فقط چیزی به آن اضافه می‌کند. یادتان باشد که دستورکار راهنماست، نه قفل؛ مدل معمولاً رعایتش می‌کند، اما جلوی هیچ فرمانی را به‌طور قطعی نمی‌گیرد. رمز، توکن و کلید API را هم هرگز در این فایل ننویسید.
مهم‌ترین نکته عملی این بخش را از همین ابتدا بدانید: در مستنداتی که بررسی کردیم، Prime Agent هیچ حالت مجوزی شبیه ابزارهایی که پیش از ویرایش یا اجرای فرمان از شما اجازه می‌گیرند ندارد. طبق صفحه مدل برنامه‌نویسی RLM، محیط پایتون ایجنت کد تولیدشده مدل و فرمان‌های پروژه را با همان دسترسی‌های حساب کاربری شما اجرا می‌کند. فرایندهای جدای پس‌زمینه برای پایداری و بازیابی کار ساخته شده‌اند و مستندات صریحاً می‌گوید محیط ایزوله امنیتی نیستند.
نمودار معماری رسمی Prime Agent
نمودار رسمی معماری. جدا بودن فرایندها به ادامه و بازیابی کار کمک می‌کند، اما جلوی کد مخرب را نمی‌گیرد.
پس کنترل را باید از بیرون و با این روش‌ها در دست بگیرید:
--no-extensions، --no-skills و --no-context-files بارگذاری افزونه‌ها، مهارت‌ها و فایل‌های دستورکار را خاموش می‌کنند و --no-tools همه ابزارها را می‌بندد.permission-gate.ts برای مسدود کردن فرمان‌های خطرناک، protected-paths.ts برای جلوگیری از نوشتن در مسیرهای مشخص و dirty-repo-guard.ts برای هشدار درباره مخزنی که تغییر ذخیره‌نشده دارد آورده است.خود افزونه‌ها، مهارت‌ها و بسته‌ها هم با دسترسی کامل حساب شما اجرا می‌شوند. فقط از منبعی نصبشان کنید که کدش را خوانده‌اید. هر دستوری که ایجنت در یک تیکت، مستند، گزارش خطا یا صفحه وب می‌خواند، ممکن است دستور مخرب باشد؛ خوانده شدن یک دستور به معنای مجاز بودنش نیست. برای بحث عمیق‌تر، مقاله امنیت مجوز ابزارهای هوش مصنوعی را ببینید.
داخل برنامه، پیامی که با / شروع شود دستور است. بیرون از برنامه هم چند فرمان خط فرمان برای مدیریت ایجنت‌ها هست. همه این‌ها در صفحه استفاده روزانه آمده‌اند:
| دستور | کاربرد |
|---|---|
/login و /logout | مدیریت ورود و کلیدها |
/model | عوض کردن مدل |
/effort | تعیین سطح استدلال مدل |
/new | شروع جلسه تازه |
/resume | ادامه یک جلسه قبلی |
/tree و /fork | پرش به نقطه قبلی جلسه یا ساختن جلسه تازه از آن |
/compact | خلاصه کردن گفت‌وگو تا حافظه کاری آزاد شود |
/usage | دیدن مصرف توکن، هزینه و حافظه کاری، به تفکیک زیرایجنت‌ها |
/refine | اصلاح یا برگرداندن دستورکار تکمیلی |
/reload | بارگذاری دوباره دستورکار، مهارت‌ها و افزونه‌ها |
prime-agent agents | دیدن ایجنت‌های در حال اجرا و ذخیره‌شده |
prime-agent attach <agent> | وصل شدن دوباره به ایجنتی که در پس‌زمینه کار می‌کند |
prime-agent stop <agent> | متوقف کردن یک ایجنت |
prime-agent shutdown | متوقف کردن همه ایجنت‌ها و سرویس‌های پس‌زمینه |
prime-agent model list | فهرست مدل‌های در دسترس |
وقتی گفت‌وگو طولانی می‌شود و کیفیت پاسخ‌ها پایین می‌آید، /compact یا شروع دوباره با /new معمولاً بهتر از ادامه دادن است. بعد از خلاصه شدن گفت‌وگو، قیدهای مهم کار را یک بار دیگر یادآوری کنید؛ خلاصه ممکن است جزئیات را جا بیندازد.
با ایجنتی که می‌تواند کار را میان چند زیرایجنت پخش کند، دقت درخواست اهمیت بیشتری دارد. در درخواست بنویسید کار چیست، کدام بخش‌ها فقط خوانده می‌شوند و کدام تغییر می‌کنند، چه چیزی نباید دست بخورد، و کار با چه نشانه‌ای تمام‌شده حساب می‌شود. این دو درخواست را کنار هم بگذارید:
درخواست دوم هم کار را میان زیرایجنت‌ها تقسیم می‌کند و هم مرز خواندن و نوشتن را روشن می‌گذارد. چون Prime Agent به‌طور پیش‌فرض حالت برنامه‌ریزی جداگانه ندارد و مخزن فقط یک افزونه نمونه برای آن آورده است، همین مرز را باید در خود درخواست بنویسید. برای کارهای بزرگ‌تر این ترتیب جواب می‌دهد:
git diff مرور کنید؛ درست مثل کد یک همکار تازه‌وارد./tree و /fork را ابزار جابه‌جایی در تاریخچه گفت‌وگو معرفی می‌کند، نه برگرداندن فایل‌ها. بعد درخواست را دقیق‌تر بنویسید.زیرایجنت‌ها را فقط برای کارهای واقعاً مستقل به کار ببرید. اگر چند زیرایجنت هم‌زمان روی همان فایل‌ها بنویسند، کار یکدیگر را خراب می‌کنند؛ یا فقط بخوانند، یا هرکدام شاخه کاری جدا داشته باشند. زیرایجنت‌ها هزینه و زمان هم دارند و دستور /usage سهم هرکدام را نشان می‌دهد.
نمای رسمی ایجنت‌ها در Prime Agent
نمای رسمی مدیریت ایجنت‌ها و جلسه‌های ماندگار.
جلسه‌های Prime Agent در فرایندهای پس‌زمینه اجرا می‌شوند؛ پس بستن ترمینال ایجنت را متوقف نمی‌کند و فقط شما را از آن جدا می‌کند. طبق صفحه ایجنت‌های طولانی و پس‌زمینه، چهار امکان برای کارهای طولانی هست:
/goal یک هدف را بین نوبت‌ها فعال نگه می‌دارد تا کامل، متوقف یا پاک شود؛ مثلاً /goal --budget 200000 Complete the repository migration با سقف توکن. /goal status، /goal pause و /goal clear وضعیتش را مدیریت می‌کنند./heartbeat every 10m Check the deployment and report meaningful changes هر ده دقیقه یک دستور تکراری به جلسه می‌فرستد.prime-agent schedule add worker "in 30m" -- "Check the benchmark result" یک بار، و فرمان prime-agent schedule add worker "0 9 * * 1-5" -- "Review open work" هر روز کاری ساعت ۹ صبح، درخواستی برای ایجنتی به نام worker می‌فرستد./autonomous on --gate "npm run check" --gate-retries 2 ایجنت را بدون دخالت شما جلو می‌برد تا فرمان بررسی قبول شود یا یکی از سقف‌ها برسد.سقف‌های پیش‌فرض حالت خودکار این‌هاست: سه ادامه خودکار، دوازده پاسخ، ۸۰٬۰۰۰ توکن و سی دقیقه. اگر هیچ سقفی را نام نبرید، همین پیش‌فرض‌ها اعمال می‌شوند؛ اما اگر فقط بعضی سقف‌ها را تعیین کنید، بقیه نامحدود می‌شوند. نکته مهم مستندات را جدی بگیرید: رسیدن به سقف به معنای موفقیت نیست، و قبول شدن یک فرمان بررسی فقط همان چیزی را ثابت می‌کند که آن فرمان واقعاً بررسی می‌کند. اگر همه سقف‌ها را unlimited کنید و هیچ فرمان بررسی ندهید، ایجنت نقطه توقف خودکار ندارد. کاری که دیگر لازم نیست را با prime-agent stop <agent> متوقف کنید.
Prime Agent سرورهای MCP را به ابزار جدیدی برای مدل تبدیل نمی‌کند. طبق صفحه اتصال MCP، همه سرویس‌ها از راه یک ماژول پایتون به نام mcp در دسترس‌اند. دستور /plugins یا /mcp صفحه‌ای باز می‌کند که در آن سرویسی مثل Linear یا Notion را جست‌وجو و با ورود در مرورگر وصل می‌کنید. اعتبارنامه‌ها روی سیستم خودتان در auth.json می‌مانند و ایجنت تا وقتی دست‌دادن واقعی با سرور موفق نشود، سرویس را «وصل» نشان نمی‌دهد. مدل بعد از اتصال این‌طور از آن استفاده می‌کند:
# Discover the server's tools first, then call one
tools = await mcp.list_tools("linear")
result = await mcp.call_tool("linear", "list_issues", {"team": "Engineering"})
مهارت‌ها بسته‌هایی از دستورالعمل و کد کمکی برای یک کار مشخص‌اند. طبق صفحه مهارت‌ها، از ~/.prime/agent/skills/ و .prime/agent/skills/ پروژه بارگذاری می‌شوند و با /skill:name صدا زده می‌شوند. سه مهارت آماده هم همراه برنامه است: prime-intellect برای کار با محصولات همین شرکت، skill-creator برای ساختن مهارت تازه، و websearch برای جست‌وجوی وب با سرویس Serper. بسته‌ها مجموعه‌ای از افزونه، مهارت و قالب‌اند و با فرمانی مثل prime-agent package install git:github.com/user/repo@v1 نصب می‌شوند. مستندات صریحاً می‌گوید بسته‌ها با دسترسی کامل سیستم اجرا می‌شوند؛ پیش از نصب کدشان را بخوانید و نسخه مشخصی را نصب کنید. جزئیات طراحی امن این اتصال‌ها را در راهنمای معماری اتصال MCP نوشته‌ایم.
وقتی یک کار را چند بار در حالت تعاملی با موفقیت انجام دادید، می‌توانید آن را در اسکریپت یا خط لوله CI هم اجرا کنید. گزینه -p درخواست را اجرا می‌کند، پاسخ را چاپ می‌کند و خارج می‌شود:
# One-off question
prime-agent -p "Summarize this codebase"
# Pipe text in
cat README.md | prime-agent -p "Summarize this text"
# Bounded unattended run that must pass the project check
prime-agent -p \
--autonomous \
--autonomous-gate "npm run check" \
--autonomous-max-continuations 3 \
--autonomous-max-turns 12 \
--autonomous-max-tokens 80000 \
--autonomous-timeout-ms 1800000 \
"Fix the failing check and report the verified result."
برای اتصال به برنامه‌های دیگر، --mode json همه رویدادهای جلسه را به‌صورت خطوط JSON چاپ می‌کند و --mode rpc ارتباط از راه ورودی و خروجی استاندارد را فراهم می‌کند. گزینه --no-session جلسه را ذخیره نمی‌کند و --offline فقط کارهای شبکه‌ای هنگام شروع، مثل بررسی به‌روزرسانی را خاموش می‌کند؛ مدل را آفلاین نمی‌کند. در اجرای خودکار کسی نیست که کار را متوقف کند؛ پس اجرا را داخل کانتینر انجام دهید، هیچ کلید یا دسترسی به محیط عملیاتی به آن ندهید و خروجی را پیش از ادغام بازبینی کنید.
اگر نمی‌خواهید کد و درخواست‌هایتان به سرویس ابری برود، یا می‌خواهید هزینه و انتخاب مدل در دست خودتان باشد، Prime Agent می‌تواند به مدلی روی سرور خود شما وصل شود. طبق صفحه مدل‌های سفارشی، برای Ollama، LM Studio یا vLLM کافی است در فایل ~/.prime/agent/models.json چنین چیزی بنویسید:
{
"providers": {
"ollama": {
"baseUrl": "http://localhost:11434/v1",
"api": "openai-completions",
"apiKey": "ollama",
"models": [
{ "id": "llama3.1:8b" },
{ "id": "qwen2.5-coder:7b" }
]
}
}
}
مقدار apiKey لازم است اما Ollama آن را نادیده می‌گیرد. اگر سرور شما نقش developer یا گزینه reasoning_effort را نمی‌شناسد، مستندات می‌گوید در بخش compat مقدارهای supportsDeveloperRole و supportsReasoningEffort را false کنید. این فایل هر بار که /model را باز می‌کنید دوباره خوانده می‌شود. مدلی که روی سرور خودتان اجرا می‌کنید باید در کار واقعی با زیرایجنت‌ها هم آزموده شود، نه فقط با یک سؤال کوتاه. برای انتخاب مدل، مقایسه Qwen3.8، GLM-5.2 و DeepSeek-V4 برای برنامه‌نویسی را ببینید.
ایجنتی که ساعت‌ها در پس‌زمینه کار می‌کند و زیرایجنت می‌سازد، برای تیم دقت بیشتری می‌خواهد. پیش از اینکه آن را در اختیار همه برنامه‌نویس‌ها بگذارید، این موارد را روشن کنید:
AGENTS.md کوتاه در git، با فرمان‌های ساخت و تست و کارهای ممنوع؛/usage؛اگر می‌خواهید ایجنت‌های برنامه‌نویسی و پژوهش را برای تیم سازمانتان روی مدلی که خودتان انتخاب می‌کنید راه‌اندازی کنید، با محیط اجرای ایزوله و قاعده‌های روشن برای هزینه و بازبینی، با ما صحبت کنید: تماس تلفنی با ۰۹۰۱ ۵۵۵ ۵۶۵۱ یا پیام در واتس‌اپ. جزئیات این خدمت را در صفحه آموزش هوش مصنوعی و ایجنت برنامه‌نویسی برای تیم‌ها هم می‌توانید ببینید.
همه فرمان‌ها و تنظیمات این راهنما در تاریخ بالا با این صفحه‌های رسمی تطبیق داده شد:
راهنمای عملی Hermes Agent از Nous Research به زبان ساده: نصب، انتخاب ارائه‌دهنده مدل، اتصال به مدل باز روی سرور خودتان، فایل AGENTS.md، تأیید فرمان‌ها و MCP.
ادامه مطلب
راهنمای عملی OpenClaw به زبان ساده: نصب گیت‌وی روی سیستم خودتان، فایل‌های پوشه کاری، حالت‌های مجوز، اتصال تلگرام و واتس‌اپ و اتصال به مدلی روی سرور خودتان.
ادامه مطلب
وب‌هوک امضاشده هنوز مجوز اجرای ابزار نیست. ثبت پایدار دریافت، تشخیص پیام تکراری و بررسی اختیار کاربر را جدا کنید تا تحویل دوباره به اقدام تازه تبدیل نشود.
ادامه مطلباگر می‌خواهید ایجنت‌های هوش مصنوعی و اتوماسیون این راهنما را در تیم نرم‌افزار یا فرایندهای سازمانتان به کار بگیرید، از یک آزمایش کوچک شروع کنید که بتوانید نتیجه‌اش را بسنجید.