AgentDefinition 與 Persona 如何合併
子 Agent 先解析可執行骨架,再把 spawn 參數、role 預設值和 Persona 預設值摺疊為執行時配置。兩套結構在不同階段生效,最終共同決定子會話。
能區分 AgentDefinition、SubagentRole、SubagentPersona 與 EffectiveRuntimeConfig,並按欄位準確判斷合併優先順序。
定義解析與執行時覆蓋是兩條輸入線
圖中型別和函式名來自原始碼,箭頭用於講解資料匯合關係。
AgentDefinition:可版本化的 Agent 合約
從 .grok/agents/*.md 解析,真實欄位包括 prompt_mode、tool_config、capability_mode、permission_mode、tools、isolation、model、hooks 與 MCP 繼承等。專案定義的發現優先順序高於 user 與 bundled。
SubagentRole:按型別命中的執行時預設
role 可給出 capability、model、reasoning effort、prompt file 與預設 isolation。它由 subagent_type 查詢,role prompt 在 spawn 時讀取。
SubagentPersona:按名稱選擇的行為層
Persona 有 inline instructions、instructions file、inputs、outputs、model、reasoning effort 與 default isolation。inline 文字在檔案內容之前合併,再作為 <persona> 塊進入 prompt。
EffectiveRuntimeConfig:已解析結果
真實欄位是 model、reasoning_effort、capability_mode、persona、persona_instructions、role_prompt、role_prompt_warning、role_name、persona_error 與 isolation。原始碼中沒有 temperature、max_tokens 或 tools 欄位。
EffectiveRuntimeConfig 之後還有 definition fallback
shell 收到解析結果後,若 reasoning_effort 仍為空,會讀取 AgentDefinition.effort;若 runtime isolation 為 None 且 definition isolation 為 Worktree,也會升級為 Worktree。model 解析中,已解析的 runtime override 先於 per-agent pin、AgentDefinition.model 與父模型繼承。
失敗關閉:Persona
請求了 Persona 後,找不到、內容為空或讀取檔案失敗都會寫入 persona_error。檔案 I/O 失敗會提前返回預設化結果;spawn 側看到 Persona 錯誤後中止建立。
軟降級:role prompt
role 的 prompt_file 讀取失敗只產生 role_prompt_warning,其餘 model、reasoning、capability 與 isolation 仍繼續解析。
pub struct EffectiveRuntimeConfig {
pub model: Option<String>,
pub reasoning_effort: Option<String>,
pub capability_mode: Option<SubagentCapabilityMode>,
pub persona: Option<String>,
pub persona_instructions: Option<String>,
pub role_prompt: Option<String>,
pub persona_error: Option<String>,
pub isolation: SubagentIsolationMode,
}
快照說明:欄位名與型別來自真實結構體,省略了註釋和兩個觀測欄位。上方合流圖是教學化視覺,不表示原始碼中存在同名的單體管線類。
課堂練習:手算有效配置
spawn 指定 reasoning_effort=high 和 Persona reviewer;role 指定 model=A、capability=read-only、isolation=worktree;Persona 指定 model=B、reasoning=low、isolation=none。寫出四個欄位的最終值,並解釋 capability 為何不會讀取 Persona。