Agent 角色定义系统：Posture、模型路由与委托权限

Agent 角色定义系统：Posture、模型路由与委托权限

学习目标

读完本章后，你将能够：

• 设计多维度的 Agent 角色定义接口
• 理解三种 posture 覆盖层如何塑造 Agent 行为
• 实现模型路由层次（exactModel → frontier → standard → fast）
• 设计 Agent 的委托权限边界，防止无限递归

前置知识

• 多 Agent 路由与隔离

---

核心概念

1. Agent 角色定义接口

Agent 角色不是简单的”名称 + 描述”，而是多维度的结构化定义：

伪代码：
interface AgentDefinition {
  name: string              // 唯一标识
  description: string       // 角色职责描述
  reasoningEffort: "low" | "medium" | "high"  // 推理强度
  posture: "frontier-orchestrator" | "deep-worker" | "fast-lane"  // 行为覆盖层
  modelClass: "frontier" | "standard" | "fast"  // 模型层级
  routingRole: "leader" | "specialist" | "executor"  // 路由角色
  tools: "read-only" | "analysis" | "execution" | "data"  // 工具访问模式
  category: "build" | "review" | "domain" | "product" | "coordination"  // 功能分类
  exactModel?: string       // 精确模型钉扎（可选）
  nativeSubagentDelegation?: { allowed: boolean }  // 子代理委托权限
}

为什么需要多维度定义：

维度	解决的问题	示例
posture	Agent 的行为倾向	编排者优先路由 vs 执行者优先行动
modelClass	成本与能力的权衡	复杂推理用强模型，快速查询用弱模型
routingRole	委托链路的权限	领导者可委托，执行者不可委托
tools	安全边界	只读角色不应有写权限

2. 三种 Posture 覆盖层

Posture 是在 Agent 系统提示之上叠加的行为指导层，不修改 Agent 的核心职责，但改变其工作倾向。

Posture 叠加层的注入时机：

每个 posture 对应一段标准化的系统提示追加文本，在生成 Agent 的 TOML 配置时注入到 developer_instructions 中。这意味着 posture 是编译时叠加的，不是运行时动态切换的。

三种 posture 的行为对比：

场景	frontier-orchestrator	deep-worker	fast-lane
收到任务	先判断应该自己做还是委托	先探索代码库再实现	快速分类搜索，深度工作升级
遇到难题	委托给领域专家	尝试替代方案后升级	直接升级给其他角色
模型选择	使用配置的 frontier 模型	使用配置的 standard 模型	使用配置的 fast 模型
推理强度	high	medium/low	low
适用角色	架构师、规划师、批评者	执行者、调试者、验证者	探索者、研究者

3. 模型路由层次

模型解析遵循优先级递减的链式决策：

模型路由的优先级：

优先级	条件	解析结果
1	exactModel 存在	直接使用该模型，跳过所有层级
2	routingRole == "executor"	使用 frontier 模型（执行者需要最强能力）
3	modelClass == "frontier"	使用根模型配置（用户指定的主模型）
4	modelClass == "fast"	使用 spark 默认模型（低成本、低延迟）
5	modelClass == "standard"	使用 standard 默认模型

为什么 executor 特例使用 frontier 模型：执行者是实际编写/修改代码的角色，需要最强的代码理解和生成能力。即使其 modelClass 被配置为 standard，执行者仍然使用 frontier 模型——这是一个安全默认值。

4. 委托权限与叶子代理守卫

Agent 的委托权限决定了它是否可以生成子代理：

叶子代理守卫：

对于 nativeSubagentDelegation 未标记为 allowed 的 Agent，系统在其指令中注入 NATIVE_SUBAGENT_LEAF_GUARD，禁止其生成子代理调用。

为什么需要叶子代理守卫：

• 防止无限递归（executor 生成 executor 生成 executor…）
• 控制成本（每个子代理调用都会产生额外的模型调用费用）
• 保持角色纯度（执行者应该执行，不应该调度其他执行者）

5. Agent 角色分类与典型配置

分类	典型角色	posture	modelClass	reasoningEffort
build	explore、analyst、planner、architect、executor、verifier	各异	各异	各异
review	code-reviewer、security-reviewer、performance-reviewer	deep-worker	standard	high
domain	dependency-expert、test-engineer、git-master	deep-worker	standard	medium
product	product-manager、ux-researcher	frontier-orchestrator	frontier	high
coordination	critic、scholastic、vision	frontier-orchestrator	frontier	high

6. 别名与合并机制

为了向后兼容，系统支持 Agent 别名和合并：

状态	说明	示例
active	正常安装的 Agent	architect、executor
internal	内部使用，不直接安装	team-orchestrator
alias	指向规范 Agent 的别名	planner → analyst
merged	已合并到另一个 Agent	style-reviewer → code-reviewer
deprecated	已废弃	swarm

别名验证确保所有 alias/merged 状态的目标指向有效的规范 Agent。

陷阱与对策

陷阱	后果	对策
Posture 与 modelClass 不匹配	行为期望与实际能力不符	在定义时强制 posture-modelClass 一致性检查
委托链路过深	延迟累积、成本指数增长	叶子代理守卫 + 最大委托深度限制
exactModel 钉扎过时模型	模型更新后 Agent 停留在旧版本	定期审计 exactModel 钉扎，迁移到 modelClass
别名链循环	A → B → A 无限循环	别名验证时的循环检测（图遍历）
routingRole 与 tools 冲突	leader 角色被限制为只读工具	定义时验证 routingRole-tools 兼容性

参考来源

• OpenAI Codex CLI — Agent configuration and native agent TOML generation
• Agent role definition patterns — 多 Agent 系统最佳实践