代理設定

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

代理實體欄位

欄位	類型	必填	說明
`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 會以技能連結的形式同步到代理的覆蓋層中；執行環境接著會把已連結技能的 frontmatter 自動載入提示中。

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