233 lines
13 KiB
Markdown
233 lines
13 KiB
Markdown
# 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` 정의 구조 예시
|
|
|
|
```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)"** 해당 전문 작업을 독립된 컨텍스트에서 수행할 것인가 |
|