Agent Orchestrator는 병렬 AI 코딩 에이전트들을 위한 오케스트레이션 계층으로, 개발자가 단일 대시보드를 통해 여러 에이전트의 작업을 감독할 수 있도록 설계되었습니다. 이 시스템은 CI 실패 수정, 코드 리뷰 코멘트 처리, PR(Pull Request) 생성 등 AI 에이전트가 자율적으로 수행하는 코딩 작업을 관리하여, 수십 개의 에이전트를 동시에 운영할 때 발생하는 복잡한 조정(coordination) 문제를 해결하는 것을 목표로 합니다.

핵심 방법론 (Core Methodology)

Agent Orchestrator의 핵심은 플러그인 기반의 모듈식 아키텍처와 자동화된 워크플로우 관리에 있습니다.

1. 에이전트 스폰 및 작업 흐름 (How It Works):
   • $ao spawn <project> [issue]$: 사용자가 특정 프로젝트 및 이슈(예: GitHub 이슈, Linear 티켓)에 대해 에이전트 생성을 요청하면 작업이 시작됩니다.
   • Workspace: 시스템은 격리된 git worktree를 생성하고, 에이전트가 작업할 새로운 기능 브랜치를 만듭니다. 이를 통해 각 에이전트의 작업이 다른 작업에 영향을 미치지 않도록 보장합니다.
   • Runtime: 에이전트는 tmux 세션(기본값) 또는 Docker 컨테이너와 같은 지정된 런타임 환경에서 실행됩니다. 이는 에이전트 실행의 격리성과 이식성을 제공합니다.
   • Agent Launch: 구성된 AI 에이전트(예: Claude Code, Codex, Aider)가 특정 이슈 컨텍스트를 가지고 시작됩니다.
   • Autonomy: 에이전트는 코드를 읽고, 테스트를 작성하며, 필요한 경우 PR을 생성하는 등 자율적으로 작업을 수행합니다.
   • Reactions: 시스템은 작업 진행 중 발생하는 주요 이벤트에 자동으로 반응합니다.
     • ci-failed: CI(Continuous Integration) 실패 시, 에이전트에게 해당 로그가 전송되어 문제 수정을 시도합니다. 이는 설정에 따라 재시도 횟수를 가질 수 있습니다.
     • changes-requested: 코드 리뷰어가 변경을 요청하면, 에이전트가 이를 인식하고 요청된 사항을 처리합니다. 이는 일정 시간 내에 에스컬레이션(escalateAfter)될 수 있습니다.
     • approved-and-green: PR이 승인되고 CI가 성공적으로 완료되면 사용자에게 알림을 보냅니다. auto 설정을 true로 변경하면 자동으로 PR을 병합할 수도 있습니다.

2. 플러그인 아키텍처 (Plugin Architecture):
   • Agent Orchestrator는 '슬롯(slots)' 개념을 사용하여 모든 추상화 계층을 교체 가능하도록 설계되었습니다. 이는 높은 확장성과 유연성을 제공합니다.
   • 총 8개의 슬롯이 존재하며, 각 슬롯은 특정 기능 영역을 담당합니다.
     • Runtime: 에이전트 실행 환경. 기본값은 tmux이며, docker, k8s, process 등으로 교체 가능합니다.
     • Agent: 사용되는 AI 코딩 에이전트. 기본값은 claude-code이며, codex, aider, opencode 등으로 교체 가능합니다.
     • Workspace: 에이전트 작업 공간 관리. 기본값은 worktree이며, clone 등으로 교체 가능합니다.
     • Tracker: 이슈 및 작업 추적 시스템. 기본값은 github이며, linear 등으로 교체 가능합니다.
     • SCM: 소스 코드 관리 시스템. 현재는 github만 지원됩니다.
     • Notifier: 알림 채널. 기본값은 desktop이며, slack, composio, webhook 등으로 교체 가능합니다.
     • Terminal: 터미널 인터페이스. iterm2, web 등이 있습니다.
     • Lifecycle: 에이전트 생명 주기 관리의 핵심 로직.
   • 모든 인터페이스는 packages/core/src/types.ts에 정의되어 있으며, 플러그인은 이 인터페이스 중 하나를 구현하고 PluginModule을 내보내는 방식으로 추가됩니다.

3. 설정 (Configuration):
   • agent-orchestrator.yaml 파일을 통해 시스템 전반을 구성합니다.
   • port: 대시보드 웹 서버 포트를 지정합니다.
   • defaults: 모든 프로젝트에 적용될 기본 runtime, agent, workspace, notifiers 설정을 정의합니다.
   • projects: 각 프로젝트의 repo, path, defaultBranch, sessionPrefix 등을 상세히 구성할 수 있습니다.
   • reactions: ci-failed, changes-requested, approved-and-green과 같은 자동 반응의 동작 방식을 세밀하게 조정합니다.

4. CLI (Command Line Interface):
   • ao status: 모든 세션의 개요를 확인합니다.
   • $ao spawn <project> [issue]$: 새 에이전트를 생성합니다.
   • $ao send <session> "Fix the tests"$: 특정 세션에 직접 명령을 전달합니다.
   • ao session ls: 활성 세션 목록을 조회합니다.
   • $ao session kill <session>$: 특정 세션을 종료합니다.
   • $ao session restore <session>$: 충돌한 에이전트 세션을 복구합니다.
   • ao dashboard: 웹 대시보드를 엽니다.

주요 기능 및 이점

• 병렬 에이전트 관리: 여러 AI 에이전트를 동시에 실행하고 관리합니다.
• 작업 격리: 각 에이전트는 전용 git worktree에서 작업하여 충돌을 방지합니다.
• 자동화된 피드백 루프: CI 실패, 코드 리뷰 코멘트 등에 에이전트가 자동으로 반응하여 수정 작업을 수행합니다.
• 중앙 집중식 모니터링: 단일 대시보드 또는 CLI를 통해 모든 에이전트의 상태를 한눈에 파악합니다.
• 에이전트/런타임/추적기 독립성: 다양한 AI 에이전트, 런타임 환경, 이슈 추적 시스템을 플러그인 형태로 지원합니다.
• 인간 개입 최소화: 에이전트가 자율적으로 대부분의 코딩 작업을 처리하고, 인간의 판단이 필요한 경우에만 알림을 보냅니다.

선수 조건 (Prerequisites)

• Node.js 20+
• Git 2.25+
• tmux (기본 런타임 사용 시)
• gh CLI (GitHub 통합 시)

Agent Orchestrator는 AI 코딩 에이전트의 효율적인 배포, 관리 및 협업을 가능하게 하여, 개발 팀이 수동적인 조정 작업 대신 핵심적인 코드 리뷰와 의사 결정에 집중할 수 있도록 지원합니다.