Agent 配置参考
配置工具、模型候选与推理强度，控制自定义 subagent 是否加载仓库指令。
Profile 由 YAML frontmatter 和 Markdown 正文组成。CLI 的字段与云端、IDE 支持范围可能不同，本页按 CLI 命令参考整理。
核心字段
| 字段 | 默认或要求 | 作用 |
|---|---|---|
description | 必填 | 角色列表和 task 工具中的说明 |
name | 默认 agent ID | 显示名称与可选择名称 |
infer | true | 是否允许主智能体自动委派 |
tools | ["*"] | 可用工具集合 |
mcp-servers | 可选对象 | 使用 MCP 配置 Schema 定义服务器 |
include-custom-instructions | false | subagent 是否读取仓库指令 |
model | 未设时继承外层 | 角色模型 |
models | 可选字符串数组 | 按顺序尝试可访问的模型，优先于 model |
modelPolicy | "preferred" | 模型可覆盖或必须满足 |
reasoningEffort | 未设时继承外层 | 推理强度，例如 low、medium、high |
tools 中只要包含 * 就授予完整工具集合，["view", "*"] 并不是只读。工具可用性与执行批准仍是不同层次。
模型选择与覆盖
一般从高到低解析：显式每次调用值 → 用户 settings.json 中的 subagents 覆盖 → profile 声明 → 父会话值。models 按列表选择用户套餐可以访问的首个模型；全部不可用时通常退回会话模型。
modelPolicy: "preferred" 允许 /subagents 或用户设置覆盖。"required" 要求采用声明的模型之一，拒绝覆盖，并禁用选择器中的 Model 项；无法满足时拒绝派发，不静默换其他模型。
命令参考另列出 Auto 会话模型的特殊规则：服务器选模时，subagent 继承解析后的会话模型，而非普通 model 字段。不要把一般优先级写成不含例外的保证。
仓库指令 opt-in
---
description: Reviews changes against repository conventions.
tools: ["view", "grep", "glob"]
include-custom-instructions: true
---
Check the change against the repository's conventions.| 运行角色 | 是否接收仓库指令 |
|---|---|
| 默认会话或 --agent 选出的顶层角色 | 是 |
| 内置 general-purpose subagent | 是 |
| 内置 explore、task、code-review subagent | 否 |
| 自定义 subagent | 仅在 include-custom-instructions 为 true 时 |
启用后读取仓库自身的 copilot-instructions.md、AGENTS.md、CLAUDE.md，不会继承只给主会话添加的额外指令目录，例如 COPILOT_CUSTOM_INSTRUCTIONS_DIRS 指向的个人目录。
--no-custom-instructions 优先：启动时使用它，任何 agent 都不会收到仓库指令，即使 profile 开启上述选项。需要代码规范的角色适合 opt-in；只做文件搜索的角色可以省略，以减少每次运行需要处理的上下文。