CLI Agent Orchestrator (CAO)
1. 개요
**CLI Agent Orchestrator(CAO)**는 여러 AI CLI 에이전트를 독립적인 터미널 환경에서 실행하고, 에이전트 간 작업 위임과 협업을 관리하는 오픈소스 멀티에이전트 오케스트레이션 프레임워크다.
AWS Labs에서 공개한 프로젝트이며, Claude Code, OpenAI Codex 등 기존 CLI 에이전트를 활용한다.
핵심 기능
| 기능 | 설명 |
|---|---|
| Multi-Agent Orchestration | 여러 에이전트의 협업 및 작업 분배 |
| Supervisor-Worker | 감독 에이전트가 작업 에이전트를 관리 |
| Multi-Provider | Codex, Claude Code 등 서로 다른 CLI 지원 |
| Agent Isolation | tmux 기반 독립 실행 환경 |
| MCP Integration | MCP를 통한 에이전트 간 통신 |
| Web UI | 브라우저에서 에이전트 실행 및 상태 확인 |
| Scheduled Flows | Cron 기반 정기 작업 실행 |
| Agent Profiles | 에이전트별 역할, 모델, 도구, 지침 정의 |
| Session Management | 에이전트 세션 생성, 메시지 전달, 종료 |
2. 아키텍처
CAO는 Supervisor-Worker 패턴을 기반으로 한다.
User
|
CLI / Web UI
|
CAO Server
|
Supervisor Agent
|
+----------+----------+
| | |
Worker A Worker B Worker C
| | |
Codex Codex Claude
| | |
tmux tmux tmux구성 요소
| 구성 요소 | 역할 |
|---|---|
| cao-server | 세션 및 에이전트 실행 관리 |
| Supervisor | 작업 분해, 위임, 결과 취합 |
| Worker | 개별 작업 수행 |
| tmux | 에이전트별 독립 터미널 유지 |
| MCP Server | 에이전트 간 작업 위임 및 메시지 전달 |
| Web UI | 실행 상태 모니터링 및 대화 |
| Profile | 에이전트 설정 및 역할 정의 |
| Flow | 정기 실행 워크플로 정의 |
각 에이전트는 별도의 tmux window에서 독립적인 CLI 프로세스로 실행된다.
따라서 에이전트마다 대화 컨텍스트가 분리되며, 서로 다른 CLI Provider를 사용할 수 있다.
3. 에이전트 간 통신
CAO는 MCP 기반으로 세 가지 주요 협업 방식을 제공한다.
| 방식 | 실행 방식 | 설명 |
|---|---|---|
handoff | 동기 | 작업을 위임하고 완료까지 대기 |
assign | 비동기 | 작업을 위임하고 다른 작업을 계속 수행 |
send_message | 메시지 전달 | 기존 에이전트에 직접 메시지 전송 |
활용 예시
Supervisor
|
|-- assign --> Agent A: 기술적 타당성 분석
|
|-- assign --> Agent B: 위험 요소 분석
|
|<-- Agent A 결과
|<-- Agent B 결과
|
|-- handoff --> Agent C: 결과 검증
|
+-- 최종 결론 작성에이전트 간 토론도 구현할 수 있다.
다만 CAO가 토론 자체를 자동으로 수행하는 것은 아니다. Supervisor의 작업 지침에 토론 절차를 명시해야 한다.
예를 들어 다음과 같은 작업을 정의할 수 있다.
-
Agent A와 Agent B가 독립적으로 분석한다.
-
각 에이전트의 분석 결과를 교환한다.
-
상대 분석 결과에 대한 반론을 작성한다.
-
Supervisor가 최종 결론을 도출한다.
4. 지원 CLI Provider
대표적인 지원 Provider는 다음과 같다.
| Provider | 식별자 |
|---|---|
| OpenAI Codex | codex |
| Claude Code | claude_code |
| Kiro CLI | kiro_cli |
| GitHub Copilot CLI | copilot_cli |
| OpenCode | opencode_cli |
| Cursor CLI | cursor_cli |
| Kimi CLI | kimi_cli |
| Hermes | hermes |
| Oh My Pi | omp |
| Antigravity CLI | antigravity_cli |
서로 다른 Provider를 하나의 Supervisor-Worker 구조에서 혼합할 수 있다.
CAO는 별도의 LLM 추론 엔진을 제공하는 것이 아니라, 기존 CLI 에이전트 프로세스를 실행하고 조정하는 역할을 수행한다.
따라서 각 Provider의 인증 및 사용량 제한은 해당 CLI의 정책을 따른다.
5. Agent Profile
Agent Profile은 개별 에이전트의 역할과 실행 설정을 정의하는 Markdown 파일이다.
YAML Frontmatter와 Markdown 본문으로 구성된다.
예시: Reviewer Agent
---
name: reviewer
description: Code Review Agent
role: reviewer
provider: codex
---
# Reviewer
You are responsible for reviewing code.
Responsibilities:
- Identify potential bugs.
- Review architectural decisions.
- Check test coverage.
- Report findings to the supervisor.주요 설정
| 설정 | 설명 |
|---|---|
name | 에이전트 식별자 |
description | 에이전트 설명 |
role | supervisor, developer, reviewer 등 |
provider | 실행할 CLI Provider |
model | 사용할 모델 |
allowedTools | 허용할 CAO 도구 |
mcpServers | 추가 MCP 서버 설정 |
codexConfig | Codex 설정 재정의 |
Profile을 분리하면 에이전트마다 서로 다른 역할과 도구 사용 정책을 적용할 수 있다.
6. Web UI
CAO는 별도의 Web UI를 제공한다.
기본 접속 주소:
http://localhost:9889
주요 기능
| 기능 | 지원 |
|---|---|
| Agent Session 생성 | O |
| Agent Profile 생성 및 수정 | O |
| 에이전트 터미널 출력 확인 | O |
| 에이전트 상태 확인 | O |
| 웹 터미널 직접 조작 | O |
| 에이전트 메시지 확인 | O |
| Scheduled Flow 관리 | O |
| Session 종료 | O |
Web UI는 React/TypeScript 기반이며, 배포용 프런트엔드가 Python 패키지에 포함되어 있다.
따라서 일반적인 실행에는 별도의 Node.js 서버가 필요하지 않다.
Web UI에서 Supervisor 세션을 실행하고 메시지를 전달하면, Supervisor가 MCP 도구를 통해 Worker를 생성하고 작업을 위임할 수 있다.
주의: Web UI가 독립적으로 모든 멀티에이전트 협업 절차를 설계·실행하는 것은 아니다. 실제 오케스트레이션 로직은 Supervisor의 지침과 도구 호출에 의해 수행된다.
7. Scheduled Flows
Scheduled Flow는 정해진 시간에 에이전트 작업을 자동으로 실행하는 기능이다.
Cron 표현식을 사용하며 Markdown 파일로 정의한다.
Flow 예시
---
name: daily-review
schedule: "0 9 * * *"
agent_profile: code_supervisor
provider: codex
---
Review recent Git commits.
1. Identify potential defects.
2. Delegate code review tasks.
3. Collect findings.
4. Generate a summary report.Flow 실행 구조
Cron Scheduler
|
v
Flow Trigger
|
v
New CAO Session
|
v
Supervisor Agent
|
+--> Worker A
|
+--> Worker B
|
v
Result Aggregation주요 명령어
# Flow 등록
cao schedule add daily-review.md
# 등록된 Flow 조회
cao schedule list
# 즉시 실행
cao schedule run daily-review
# 비활성화
cao schedule disable daily-review
# 활성화
cao schedule enable daily-review
# 삭제
cao schedule remove daily-review중요한 동작 특성
-
Scheduler는
cao-server내부에서 실행된다. -
서버가 실행 중이어야 예약 작업이 동작한다.
-
예약 시간이 도래하면 새로운 CAO 세션이 생성된다.
-
기존에 실행 중인 Supervisor 세션에 작업을 전달하는 방식이 아니다.
-
조건부 실행을 위한 Gating Script를 추가할 수 있다.
따라서 동일한 에이전트 세션을 장기간 재사용하려는 구조와는 구분해야 한다.
8. 설치 및 실행
요구사항
-
Python 3.10 이상
-
tmux 3.3 이상
-
uv
-
지원되는 AI CLI
-
해당 CLI의 사전 인증
설치
uv tool install \
git+https://github.com/awslabs/cli-agent-orchestrator.git@main \
--upgradeSupervisor 설치
cao install code_supervisor서버 실행
cao-serverCodex 기반 Supervisor 실행
cao launch \
--agents code_supervisor \
--provider codex \
--session-name main기존 Supervisor에 작업 전달
cao session send cao-main \
"Review the current repository"상태 확인
cao session status cao-main --workers종료
cao shutdown --session cao-mainCAO가 생성한 세션에는 일반적으로 cao- 접두사가 붙는다.
9. Docker 및 VPS 운영
CAO는 Docker 기반으로도 운영할 수 있다.
다만 컨테이너에 다음 구성 요소가 필요하다.
-
CAO
-
tmux
-
Codex 또는 Claude Code CLI
-
CLI 인증 정보
-
작업할 Git Repository
-
필요한 개발 및 테스트 도구
권장 구성
Browser
|
Cloudflare Tunnel
|
CAO Web UI
|
cao-server
|
tmux
|
Supervisor
|
+-----+-----+
| |
Worker A Worker B
| |
Codex Codex
| |
+-----+-----+
|
Git Repository운영 시 고려사항
1. 파일시스템 권한
에이전트가 수정할 Git Repository에는 쓰기 권한이 필요하다.
특히 .git 디렉터리가 읽기 전용이면 Git commit이 실패할 수 있다.
2. 에이전트 작업 충돌
여러 Worker가 동일한 작업 디렉터리를 수정하면 충돌할 수 있다.
독립적인 Git Worktree 또는 별도의 작업 디렉터리를 제공하는 구성을 검토할 필요가 있다.
3. 컨테이너 격리
CAO의 tmux 기반 에이전트 분리는 보안 샌드박스와 동일하지 않다.
CLI 에이전트별 파일시스템 접근, 명령 실행 권한, 컨테이너 권한은 별도로 관리해야 한다.
4. Web UI 보안
Web UI는 원격 터미널 조작 기능을 제공한다.
기본 구성에서 터미널 WebSocket 엔드포인트에 인증이 적용되지 않을 수 있으므로, 외부 공개 시 반드시 인증 및 접근 제어가 필요하다.
Cloudflare Tunnel을 사용한다면 Cloudflare Access와 같은 인증 계층을 적용하는 구성을 권장한다.
10. 활용 사례
사례 A. 오픈소스 기여 자동화
User
|
v
Supervisor
|
+--> Agent A: Issue 분석
|
+--> Agent B: 관련 코드 탐색
|
v
Supervisor: 수정 방향 결정
|
+--> Agent C: 코드 수정
|
+--> Agent D: 테스트 및 리뷰
|
v
Supervisor: 결과 취합
|
v
Git Commit / PR 검토Apache Airflow 등 대규모 오픈소스 프로젝트의 Issue 해결에 활용할 수 있다.
사례 B. 멀티에이전트 의사결정
정량적 조건으로 후보 추출
|
v
Supervisor
|
+----+----+
| |
Agent A Agent B
긍정 분석 부정 분석
| |
+----+----+
|
결과 교환
|
상호 검토
|
Supervisor
|
최종 판단서로 다른 관점의 분석 결과를 비교하고 반론을 수행하는 구조다.
사례 C. 정기적 코드 품질 검사
Scheduled Flow
|
v
Repository 검사
|
v
Supervisor
|
+--> 정적 분석 Agent
|
+--> 테스트 Agent
|
+--> 보안 검토 Agent
|
v
검사 결과 취합
|
v
보고서 생성Cron 기반으로 정기 실행할 수 있다.
11. 장점과 제약
| 구분 | 내용 |
|---|---|
| 장점 | 기존 CLI 에이전트를 그대로 활용 |
| 장점 | 서로 다른 LLM Provider 혼합 가능 |
| 장점 | Supervisor-Worker 구조 지원 |
| 장점 | 웹 기반 모니터링 및 조작 |
| 장점 | Cron 기반 자동화 |
| 장점 | MCP 기반 에이전트 통신 |
| 제약 | 각 CLI Provider의 인증 필요 |
| 제약 | 에이전트별 사용량 제한 적용 |
| 제약 | tmux 및 지속 실행 서버 필요 |
| 제약 | 작업 충돌 방지를 위한 별도 설계 필요 |
| 제약 | 고급 토론 절차는 Supervisor 지침으로 구현 필요 |
| 제약 | 보안 격리 및 접근 제어는 별도 구성 필요 |
12. 결론
CLI Agent Orchestrator는 기존 CLI 기반 AI 에이전트들을 하나의 Supervisor-Worker 구조로 통합하기 위한 오케스트레이션 솔루션이다.
핵심적인 특징은 다음과 같다.
-
Codex, Claude Code 등의 기존 CLI 활용
-
tmux 기반 개별 에이전트 실행
-
MCP를 통한 작업 위임 및 메시지 전달
-
Supervisor 중심의 멀티에이전트 협업
-
Web UI 기반 세션 관리
-
Scheduled Flow 기반 정기 실행
특히 VPS 환경에서 Codex를 활용해 오픈소스 코드베이스를 분석하고, 여러 에이전트가 검토·수정·테스트 작업을 분담하도록 구성하는 용도에 적합하다.
다만 CAO 자체가 코드 변경의 정확성, 에이전트 간 합의 품질, Git 작업 충돌 방지, 실행 환경의 보안성을 자동으로 보장하지는 않는다.
이러한 요구사항은 별도의 Supervisor 지침, 작업 디렉터리 격리, 테스트 파이프라인 및 접근 제어를 통해 해결해야 한다.
13. 참고 자료
-
GitHub Repository
https://github.com/awslabs/cli-agent-orchestrator -
Architecture
https://awslabs.github.io/cli-agent-orchestrator/docs/core-concepts/architecture/ -
Agent Profiles
https://awslabs.github.io/cli-agent-orchestrator/docs/features/profiles/ -
Web UI
https://awslabs.github.io/cli-agent-orchestrator/docs/features/web-ui/ -
Scheduled Flows
https://awslabs.github.io/cli-agent-orchestrator/docs/features/scheduled-flows/ -
CLI Commands
https://awslabs.github.io/cli-agent-orchestrator/docs/reference/cli-commands/