AgentDefinition과 Persona의 합병 방식
Sub-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, 기본 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, 부모 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에서 읽히지 않는 이유를 설명하세요.