代理設定

本參考列出代理實體上的每個欄位，以及它所用的列舉與旗標。若要在應用程式中逐步了解如何建立或編輯代理，請參見建立並設定代理。

代理實體欄位

欄位	類型	必填	說明
`id`	`String`	是	唯一的代理識別碼
`name`	`String`	是	用於 @ 提及的簡短識別碼
`title`	`String`	是	人類可讀的職位名稱
`agentMdPath`	`String`	是	代理 `.md` 定義檔案的絕對路徑
`workspaceId`	`String`	是	所屬工作區（不可為 null）
`reportsTo`	`String?`	否	上級代理 id
`skills`	`AgentSkills`	是	技能識別碼的集合
`persona`	`String?`	否	自由文字的行為指示
`systemPrompt`	`String?`	否	覆寫預設的系統提示
`adapterId`	`String?`	否	推理配接器 id
`modelId`	`String?`	否	該配接器內的模型 id
`strictMode`	`bool`	否	預設 `false`。會寫入該資料列，以及代理的 `AGENTS.md`
`effort`	`String?`	否	推理等級 id（例如 `'low'`、`'xhigh'`），取自所選模型的 `thinkingLevels`
`contextSize`	`int?`	否	上下文窗口的大小上限
`role`	`AgentRole?`	否	代理的角色
`monthlyBudgetCents`	`int`	否	以分為單位的每月支出上限（預設 `0`，即不限）
`silenceTimeoutMinutes`	`int?`	否	靜默逾時的覆寫值，以分鐘計；必須為 null 或落於 1–240 之間（由建構函式斷言）
`maxConcurrentTasks`	`int`	否	預設 `1`。線上狀態模型所報告的容量數值（執行中與已排隊的計數都會與它比較）
`visibility`	`AgentVisibility`	否	預設 `workspace`
`lifecycleStatus`	`AgentLifecycleStatus`	否	治理狀態（預設 `active`）。由預算硬性停止寫入，並渲染在組織圖與線上狀態名冊上。派發仍會接受來自 `paused` 代理的工作
`budgetPolicyId`	`String?`	否	共享預算政策 id；為 null 時直接套用 `monthlyBudgetCents`
`runtimeProfileId`	`String?`	否	自訂執行階段設定檔 id
`createdAt`	`DateTime`	是	建立時間戳

name 與 title 都必須非空（由建構函式斷言）。monthlyBudgetCents 的預設值 0 代表不限。要寫入上限，請使用 agents.upsert。

AgentRole 列舉

角色	標籤	說明
`ceo`	CEO	協調與委派
`coder`	Coder	程式碼實作
`reviewer`	Reviewer	PR 審查與分析
`qa`	QA	測試與質素保證
`designer`	Designer	UI/UX 實作
`security`	Security	保安審查與稽核
`devops`	DevOps	基礎設施與部署
`pm`	PM	產品管理
`general`	General	靈活、多用途

AgentVisibility 列舉

值	說明
`workspace`	預設值；未知以及為 null 的已儲存值都解析為它
`private`	僅對建立它的用戶可見

AgentLifecycleStatus 列舉

值	說明
`active`	預設值。`isDispatchable` 只有在此值下才為 true
`paused`	由預算硬性停止設定。會顯示在線上狀態名冊上；派發仍會接受工作
`archived`	已退役，並從活動名冊中隱藏

權限

代理不帶任何權限旗標。推送、開啟與發佈 pull request、寫入追蹤器以及網絡對外連線都是動作類別（gitPush、prCreate、prPublish、vendorSyncWrite、networkEgress），由護欄在工作區、代理或空間範圍內解析。執行的 GitHub 權杖一律是唯讀範圍；推送經過代理執行閘道，閘道在轉送前會詢問 gitPush 規則。

AgentSkills

一個不可變、不區分大小寫的技能識別碼集合。派發時，這些 slug 會同步為代理覆蓋層中的技能連結；隨後執行框架會把已連結技能的前置資料自動載入提示中。

{'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。