智能体配置

本参考列出智能体实体上的每个字段，以及它使用的枚举和标志。关于在应用中创建或编辑智能体的分步讲解，见创建并配置智能体。

智能体实体字段

字段	类型	必填	说明
`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。