13 KiB
Agent Team Design Patterns (Antigravity CLI)
실행 모드: 서브에이전트
Antigravity CLI는 invoke_subagent 도구를 통해 멀티-에이전트 워크플로우를 구현한다. 메인 에이전트가 오케스트레이터 역할을 하며, 각 서브에이전트는 독립적인 컨텍스트와 도구 세트로 작업을 수행한다.
서브에이전트 (Subagents) — 기본 모드
메인 에이전트가 invoke_subagent 도구를 호출하여 서브에이전트를 호출(TypeName 지정)한다. 각 서브에이전트는 별개의 격리된 컨텍스트 윈도우에서 실행되며, 작업 완료 후 최종 상태 및 메시지를 오케스트레이터에게 반환한다.
[메인/오케스트레이터]
├── invoke_subagent(TypeName: "agent-a") → 작업 수행 → 결과 반환
├── invoke_subagent(TypeName: "agent-b") → 작업 수행 → 결과 반환
└── invoke_subagent(TypeName: "agent-c") → 작업 수행 → 결과 반환
핵심 특징:
- 서브에이전트는
.agents/plugins/{plugin-name}/agents/{name}/agent.json파일로 정의한다. invoke_subagent도구 호출을 사용하여 명시적 위임 호출을 수행한다.- 각 서브에이전트는 독립적인 컨텍스트, 도구, MCP 서버를 보유한다.
send_message도구를 통해 실행 중인 서브에이전트와 오케스트레이터 간 추가 정보나 피드백을 전달할 수 있다.- 결과가 메인 컨텍스트로 요약 및 완료 보고 형태로 반환된다.
제약:
- 서브에이전트 간 직접 통신은 불가능하다 (메인을 통해서만 조율).
- 메인이 모든 워크플로우 통제를 담당한다.
- 동일 파일에 대한 동시 쓰기 충돌을 방지해야 한다 (병렬 실행 시).
병렬 서브에이전트
독립적인 여러 작업을 동시에 처리하고자 할 때 유용하다. invoke_subagent 도구를 여러 번 순차적으로 실행하여 백그라운드 태스크로 구동하고, 모든 서브에이전트의 작업 결과가 수집될 때까지 대기 및 취합한다.
[메인]
├── invoke_subagent(TypeName: "agent-a") (병렬 백그라운드)
├── invoke_subagent(TypeName: "agent-b") (병렬 백그라운드)
└── invoke_subagent(TypeName: "agent-c") (병렬 백그라운드)
└── 모든 에이전트 완료 후 결과 통합
적합한 경우: 작업 간의 독립성이 완벽히 보장되고, 최종 결과만 병합(Merge)하면 되는 경우.
주의: 동일 파일에 대한 동시 쓰기 충돌을 방지하기 위해, 각 서브에이전트가 출력할 개별 경로(_workspace/ 하위 등)를 고유하게 분리해야 한다.
직접 실행
단순한 작업은 별도의 서브에이전트 플러그인 생성 없이, 메인 에이전트가 직접 툴(view_file, write_to_file 등)을 사용하여 작업을 즉시 처리한다.
[메인]
└── 직접 실행 (Read/Write/Shell 등)
적합한 경우: 단순 탐색, 소규모 텍스트 편집 등 에이전트 분리 및 전환에 따르는 오버헤드가 더 클 때.
모드 선택 의사결정 트리
전문 영역이 2개 이상인가?
├── Yes → 작업이 독립적으로 실행 가능한가?
│ ├── Yes → 병렬 서브에이전트
│ │ 각 영역별로 독립 실행, 결과만 통합.
│ │
│ └── No → 순차 서브에이전트 (파이프라인)
│ 이전 에이전트의 산출물이 다음 입력으로 필요.
│
└── No (1개) → 직접 실행
단일 작업은 서브에이전트 분리 불필요.
핵심 원칙:
invoke_subagent가 기본이다. 직접 실행을 선택할 때는 "이 작업이 정말 독립된 에이전트 페르소나나 격리된 컨텍스트를 필요로 하지 않는가?"를 자문한다.
팀 아키텍처 유형
1. 파이프라인 (Pipeline)
순차적 작업 흐름. 이전 서브에이전트의 출력이 다음 서브에이전트의 입력으로 전달된다.
[analyst] ─(Output 파일)─→ [designer] ─(Output 파일)─→ [builder] ─→ [verifier]
적합한 경우: 각 단계가 이전 단계의 산출물에 강력하게 의존하는 경우.
예시: 문서/콘텐츠 제작 — 자료 조사 및 분석 → 구성안 디자인 → 원고 집필 → 완성도 검증.
주의: 앞선 에이전트의 병목이나 실패가 파이프라인 전체를 지연시키므로 에러 발생 시 재시도 메커니즘을 명확히 해야 한다.
구현: 파일 기반 데이터 전달 — 각 서브에이전트가 _workspace/에 결과 파일을 저장하고, 다음 서브에이전트 호출 프롬프트에 해당 파일의 절대 경로를 읽도록 지시한다.
2. 팬아웃/팬인 (Fan-out/Fan-in)
독립적인 작업을 동시에 수행한 뒤 결과를 통합한다.
┌→ [expert-a] ─┐
[메인/오케스트레이터] ─┼→ [expert-b] ─┼→ [결과 통합]
└→ [expert-c] ─┘
적합한 경우: 동일 입력에 대해 상이한 전문가 관점의 동시 분석이나 대량 분할 자료 처리가 필요할 때.
예시: 종합 리서치 — 보안성 검토, 성능 모델링, 법적 규제 준수 여부를 각각의 에이전트가 병렬로 진행한 후 단일 보고서로 취합.
주의: 각 서브에이전트의 출력 경로를 중복되지 않게 고유한 파일명(02_expert_a_result.md 등)으로 매핑하여 동시 쓰기 충돌을 방지한다.
3. 전문가 풀 (Expert Pool)
상황이나 조건에 따라 적절한 에이전트를 선택하여 호출한다.
[메인/라우터] ──(분류/조건 판단)──→ { analyst-agent | builder-agent | qa-agent }
적합한 경우: 입력 요청의 성격이나 기술 분야에 따라 서로 다른 지시 및 도구 세트가 필요한 경우. 예시: 코드 검토 — 변경된 파일의 확장자나 코드 속성에 따라 보안 전문가, 성능 최적화 전문가, 데이터베이스 전문가 중 필요한 전문가만 선별적으로 호출.
4. 생성-검증 (Producer-Reviewer)
생성 담당 서브에이전트와 검증 담당 서브에이전트가 쌍(Pair)으로 협업한다.
[producer-agent] ──(생성안)──→ [reviewer-agent] ──(피드백/검증)
▲ │
└─────── (오류 발견 시 재실행) ─────┘
적합한 경우: 산출물의 정확성이나 코드 품질이 대단히 엄격하게 요구되고, 기계적 혹은 정성적 검증 기준이 명확한 경우. 주의: 무한 루프에 빠지는 것을 방지하기 위해 최대 재시도 및 루프 횟수(최대 2~3회)를 반드시 오케스트레이터 수준에서 제한해야 한다.
5. 감독자 (Supervisor)
메인 에이전트가 작업의 총괄 상태와 분배 목록을 관리하며 서브에이전트들에게 유동적으로 작업을 위임한다.
┌→ [worker-a]
[supervisor-agent] ┼→ [worker-b] (작업 진행 속도 및 상태에 따라 유동 분배)
└→ [worker-c]
적합한 경우: 대상 파일이나 작업의 목록이 런타임에 동적으로 변경되거나 처리해야 하는 전체 양이 방대하여 점진적인 분할 처리가 유리할 때.
6. 계층적 위임 (Hierarchical Delegation)
상위 서브에이전트가 하위 서브에이전트에 다시 invoke_subagent 도구 호출로 재귀적 위임을 수행하여 복잡한 전체 문제를 위계적으로 처리한다.
[main] → [team-lead-agent] ──→ [worker-agent-1]
└──→ [worker-agent-2]
주의: 위임의 깊이가 3단계 이상을 넘어가게 되면 중간 컨텍스트가 생략되어 지연 및 컨텍스트 손실이 비약적으로 증가한다. 최대 2단계 이내의 위임을 강력히 권장한다.
서브에이전트 정의 형식 (Antigravity CLI)
Antigravity CLI에서 서브에이전트는 .agents/plugins/{plugin-name}/agents/{agent-name}/agent.json 파일에 JSON 포맷으로 정의된다.
Note
다국어 및 영문 작성 규칙 사용자가 영어로 하네스를 구성하도록 요청했거나 프로젝트의 기본 언어가 영어인 경우,
description및systemPromptSections내의 모든 지침 텍스트(핵심 역할, 작업 원칙, 입출력 프로토콜 등)는 자연스러운 **영문(Technical English)**으로 번역 및 작성되어야 합니다. 한국어 주석이나 텍스트를 남기지 않습니다.
agent.json 정의 구조 예시
{
"name": "agent-name",
"description": "서브에이전트의 역할 요약 및 사용 용도 설명.",
"hidden": false,
"config": {
"customAgent": {
"systemPromptSections": [
{
"title": "Agent System Instructions",
"content": "당신은 [도메인]의 전문 서브에이전트 '[TypeName]'입니다.\n\n## 핵심 역할\n1. [핵심 역할 1]\n2. [핵심 역할 2]\n\n## 작업 원칙\n- [작업 원칙 1]\n- [작업 원칙 2]\n\n## 입력/출력 프로토콜\n- 입력: [오케스트레이터로부터 인계받는 파일 경로 및 컨텍스트]\n- 출력: [작업 완료 후 산출물을 작성할 경로 및 구조]\n\n## 에러 핸들링\n- 도구 실패나 누락 발견 시 1회 자체 복구를 시도하고, 해결 불가능할 경우 원인 메시지를 출력하며 실행을 중단하세요.\n\n## 협업 프로토콜\n- 이전 단계의 결과 파일이 `_workspace/` 하위에 있을 경우 이를 로드하여 활용하고, 지시 피드백이 추가 제공되면 해당 사항을 최우선으로 반영하여 결과 파일을 업데이트하세요."
}
],
"toolNames": [
"send_message",
"find_by_name",
"grep_search",
"view_file",
"list_dir",
"read_url_content",
"search_web",
"schedule",
"multi_replace_file_content",
"replace_file_content",
"write_to_file",
"run_command",
"manage_task",
"define_subagent",
"invoke_subagent",
"manage_subagents",
"call_mcp_tool"
],
"systemPromptConfig": {
"includeSections": [
"user_information",
"mcp_servers",
"skills",
"subagent_reminder",
"messaging",
"artifacts",
"user_rules"
]
}
}
}
}
에이전트 분리 기준
| 기준 | 분리 | 통합 |
|---|---|---|
| 전문성 | 작업 영역의 도메인(예: 기획 vs 빌드 vs QA)이 완전히 상이할 때 분리 | 작업 지식과 프롬프트가 유사하거나 밀접한 연관이 있을 때 통합 |
| 병렬성 | 다수의 독립 파일을 각기 병렬로 가공해야 할 때 분리 | 앞 작업이 끝나야만 뒤 작업을 진행할 수 있는 밀접한 순차 종속 시 통합 고려 |
| 컨텍스트 | 특정 분석을 위해 로딩해야 할 파일 용량이 거대하여 컨텍스트 절약이 요구될 때 분리 | 에이전트 간 컨텍스트가 실시간으로 고도로 결합하여 공유되어야 할 때 통합 |
| 재사용성 | 다양한 시나리오나 다른 플러그인 워크플로우에서도 독립적으로 호출될 여지가 있을 때 분리 | 특정 오케스트레이터의 특수 보조 역할에만 극한될 때 통합 |
스킬(Skill) vs 서브에이전트(Agent) 구분
| 구분 | 스킬 (Skill) | 서브에이전트 (Agent) |
|---|---|---|
| 정의 | 절차적인 지식 및 특정 행동 워크플로우 가이드라인 | 행동 원칙, 성격 및 특정 도구 실행 역량을 지닌 전문가 개체 |
| 위치 | .agents/plugins/{plugin-name}/skills/{skill-name}/SKILL.md |
.agents/plugins/{plugin-name}/agents/{agent-name}/agent.json |
| 트리거 | description 분석 기반의 자동 매칭 및 명시적 스킬 활성화 | invoke_subagent 도구를 통한 명시적 위임 실행 |
| 용도 | "어떻게(How)" 작업을 효율적으로 진행할 것인가에 대한 규약 | "누가(Who)" 해당 전문 작업을 독립된 컨텍스트에서 수행할 것인가 |