پیکربندی عامل

این مرجع هر فیلد روی موجودیت عامل را به‌همراه enumها و پرچم‌هایی که به کار می‌برد فهرست می‌کند. برای یک راهنمای گام‌به‌گام از ساخت یا ویرایش یک عامل در برنامه، ایجاد و پیکربندی یک عامل را ببینید.

فیلدهای موجودیت عامل

فیلد	نوع	الزامی	توضیح
`id`	`String`	بله	شناسهٔ یکتای عامل
`name`	`String`	بله	شناسهٔ کوتاه برای منشن‌های @
`title`	`String`	بله	عنوان نقش خوانا برای انسان
`agentMdPath`	`String`	بله	مسیر مطلق فایل تعریف `.md` عامل
`workspaceId`	`String`	بله	فضای کاری مالک (نه null)
`reportsTo`	`String?`	خیر	شناسهٔ عامل والد
`skills`	`AgentSkills`	بله	مجموعهٔ شناسه‌های مهارت
`persona`	`String?`	خیر	دستورالعمل‌های رفتاری متنی آزاد
`systemPrompt`	`String?`	خیر	جایگزینی پرامپت سیستمی پیش‌فرض
`adapterId`	`String?`	خیر	شناسهٔ آداپتور استنتاج
`modelId`	`String?`	خیر	شناسهٔ مدل در آن آداپتور
`strictMode`	`bool`	خیر	پیش‌فرض `false`. در ردیف و در `AGENTS.md` عامل نوشته می‌شود
`effort`	`String?`	خیر	شناسهٔ سطح استدلال (مثلاً `'low'`، `'xhigh'`)، برگرفته از `thinkingLevels` مدل انتخاب‌شده
`contextSize`	`int?`	خیر	بیشترین اندازهٔ پنجرهٔ زمینه
`role`	`AgentRole?`	خیر	نقش عامل
`monthlyBudgetCents`	`int`	خیر	سقف هزینهٔ ماهانه به سنت (پیش‌فرض `0`، بی‌نهایت)
`silenceTimeoutMinutes`	`int?`	خیر	جایگزین مهلت سکوت به دقیقه؛ باید null باشد یا در بازهٔ 1–240 (با assert در سازنده)
`maxConcurrentTasks`	`int`	خیر	پیش‌فرض `1`. رقم ظرفیتی که مدل حضور گزارش می‌کند (شمارهای در حال اجرا و در صف با آن مقایسه می‌شوند)
`visibility`	`AgentVisibility`	خیر	پیش‌فرض `workspace`
`lifecycleStatus`	`AgentLifecycleStatus`	خیر	وضعیت حاکمیتی (پیش‌فرض `active`). با توقف سخت بودجه نوشته می‌شود و روی نمودار سازمانی و فهرست حضور رندر می‌شود. اعزام هنوز کار را از یک عامل `paused` می‌پذیرد
`budgetPolicyId`	`String?`	خیر	شناسهٔ سیاست بودجهٔ اشتراکی؛ وقتی null باشد `monthlyBudgetCents` مستقیم اعمال می‌شود
`runtimeProfileId`	`String?`	خیر	شناسهٔ پروفایل زمان اجرای سفارشی
`createdAt`	`DateTime`	بله	مُهر زمانی ساخت

name و title هر دو باید ناتهی باشند (با assert در سازنده). پیش‌فرض 0 برای monthlyBudgetCents یعنی بی‌نهایت. سقف را با agents.upsert بنویسید.

enum مربوط به AgentRole

نقش	برچسب	توضیح
`ceo`	CEO	هماهنگی و تفویض
`coder`	Coder	پیاده‌سازی کد
`reviewer`	Reviewer	بازبینی و تحلیل PR
`qa`	QA	تست و تضمین کیفیت
`designer`	Designer	پیاده‌سازی UI/UX
`security`	Security	بازبینی و حسابرسی امنیتی
`devops`	DevOps	زیرساخت و استقرار
`pm`	PM	مدیریت محصول
`general`	General	انعطاف‌پذیر و چندمنظوره

enum مربوط به AgentVisibility

مقدار	توضیح
`workspace`	پیش‌فرض؛ مقادیر ذخیره‌شدهٔ ناشناخته و null به آن تجزیه می‌شوند
`private`	خصوصی برای کاربری که آن را ساخته است

enum مربوط به AgentLifecycleStatus

مقدار	توضیح
`active`	پیش‌فرض. `isDispatchable` فقط برای این مقدار true است
`paused`	با توقف سخت بودجه تعیین می‌شود. در فهرست حضور نشان داده می‌شود؛ اعزام هنوز کار را می‌پذیرد
`archived`	بازنشسته و پنهان از فهرست‌های حضور فعال

مجوزها

عامل‌ها هیچ پرچم مجوزی ندارند. پوش، باز کردن و انتشار pull requestها، نوشتن در ردیاب و خروج شبکه کلاس‌های کنش‌اند (gitPush، prCreate، prPublish، vendorSyncWrite، networkEgress) که گاردریل‌ها در محدودهٔ فضای کاری، عامل یا فضا حل می‌کنند. توکن GitHub یک اجرا همیشه به فقط‌خواندنی محدود است؛ پوش‌ها از دروازهٔ اجرای عامل می‌گذرند که پیش از عبور دادن از قاعدهٔ gitPush می‌پرسد.

AgentSkills

مجموعه‌ای تغییرناپذیر و بدون حساسیت به بزرگی و کوچکی حروف از شناسه‌های مهارت. هنگام اعزام، آن اسلاگ‌ها به‌صورت پیوندهای مهارت در overlay عامل همگام می‌شوند؛ سپس هارنس فرانت‌متر مهارت‌های پیوندشده را به‌طور خودکار در پرامپت بارگذاری می‌کند.

{'flutter', 'dart', 'rest-api'}

AgentLiveState (مشتق‌شده)

ذخیره نمی‌شود. هفت مقدار. ترتیب اعلان همان ترتیب اولویت است (sortPriority، با یک تست سنجاق شده)، و همان ترتیبی است که فهرست حضور بر پایهٔ آن مرتب می‌شود:

وضعیت	`sortPriority`	شرط
`running`	0	هر گزارش اجرایی وضعیت `running` داشته باشد
`blocked`	1	زنده‌بودن آخرین اجرا `blocked`، `stalled` یا `looping` باشد
`failed`	2	وضعیت آخرین اجرا `error` باشد، یا زنده‌بودنش `failed` یا `dead`
`queued`	3	اجرایی اعزام شده اما در حال اجرا نیست — پشت اجرایی دیگر از همان عامل پارک شده، یا نوشته شده اما هنوز آغاز نشده است
`succeeded`	4	اجرا با موفقیت تمام شده است
`idle`	5	عامل قبلاً اجرا شده و کاری در پرواز ندارد
`neverRun`	6	هیچ گزارش اجرایی وجود ندارد

queued و succeeded فقط برای هر اجرا هستند. deriveAgentLiveState که وضعیت فهرست حضور یک عامل را محاسبه می‌کند هرگز هیچ‌یک از این دو را تولید نمی‌کند — neverRun، running، failed، blocked یا idle را برمی‌گرداند.