Composio Agent Orchestrator 사용 가이드

여러 AI 코딩 에이전트를 병렬로 돌리고, CI 실패와 리뷰 코멘트까지 다시 에이전트에게 넘기는 오케스트레이션 도구.

이 문서는 Composio Agent Orchestrator를 처음 써보는 사람 기준으로 정리한 실전형 가이드다. 핵심은 단순하다. 에이전트를 많이 쓰는 것보다, 에이전트들을 잘 조율하는 것이 더 중요하다.

한 줄 요약

• 이 도구는 대시보드가 아니라 오케스트레이터 에이전트다.
• 이슈를 받아서 작업으로 쪼개고, 각 작업을 워크트리/세션에 배정하고, PR과 CI를 추적한다.
• CI가 깨지면 실패 로그를 다시 에이전트에게 넣어 자동 수정하게 만든다.
• 리뷰 코멘트가 달리면 해당 세션에 전달해 재수정한다.

이런 상황에서 특히 좋다

• 병렬로 여러 기능을 동시에 밀어야 할 때
• PR 리뷰와 CI 대응에 시간을 너무 많이 쓰고 있을 때
• Claude Code, Aider, Codex 같은 여러 에이전트를 한 흐름으로 묶고 싶을 때
• GitHub/Linear 이슈를 에이전트에게 바로 넘기고 싶을 때

전체 흐름

이슈 수집 → 작업 분해 → 격리된 워크스페이스 생성 → 에이전트 실행 → PR 생성 → CI/리뷰 감시 → 실패 재주입 → 자동 수정 → 머지

즉, 사람이 계속 새로고침하면서 상태를 보는 구조가 아니라, 오케스트레이터가 상태를 대신 추적하는 구조다.

추천 시작 방법

가장 단순한 시작은 다음과 같다.

git clone https://github.com/ComposioHQ/agent-orchestrator.git
cd agent-orchestrator
pnpm install && pnpm build
ao init --tracker github --agent claude-code --runtime tmux
ao start

각 명령의 의미

• git clone — 저장소를 받는다
• pnpm install && pnpm build — 의존성과 빌드를 준비한다
• ao init ... — 추적기/에이전트/런타임을 선택한다
• ao start — 오케스트레이터와 대시보드를 실행한다

처음 설정할 때의 권장값

처음에는 복잡하게 가지 않는 편이 좋다.

1) tracker

• GitHub부터 시작하는 걸 권장
• 이미 이슈/PR 중심으로 일하고 있다면 가장 자연스럽다
• Linear도 가능하지만, 첫 시도는 GitHub가 이해하기 쉽다

2) agent

• Claude Code가 가장 무난하다
• 이미 익숙한 CLI 코딩 에이전트가 있으면 그걸 먼저 연결해도 된다
• 중요한 건 “어떤 에이전트냐”보다 “오케스트레이션이 일관되게 되느냐”다

3) runtime

• tmux가 기본적으로 가장 이해하기 쉽다
• 격리된 세션을 눈으로 보기 좋고, 디버깅이 편하다
• 컨테이너 기반 운영이 필요하면 Docker로 옮길 수 있다

실제 사용 순서

1단계. 작업 단위를 작게 나눈다

한 번에 큰 작업 하나만 넣기보다, 병렬화 가능한 단위로 쪼개는 게 낫다.

예:

• UI 수정
• 테스트 추가
• 문서 보강
• 버그 수정

오케스트레이터가 병렬로 돌릴 수 있게 만들어야 한다.

2단계. 세션이 잘 만들어졌는지 확인한다

대시보드에서 다음을 먼저 본다.

• 어떤 세션이 실행 중인지
• 어떤 세션이 CI 실패 상태인지
• 어떤 세션이 리뷰 대기인지
• 어떤 세션이 멈췄는지

여기서 중요한 건 “모든 것을 사람이 일일이 보는 것”이 아니라, 주의가 필요한 것만 보이는 상태를 만드는 것이다.

3단계. CI 실패를 그냥 방치하지 않는다

이 도구의 핵심은 실패를 에이전트에게 다시 돌려보내는 것이다.

좋은 습관:

• 실패 로그를 수동 복붙하지 말고, reaction으로 연결한다
• 실패 유형이 반복되면 guardrail을 추가한다
• flaky test와 실제 회귀를 분리해서 본다

4단계. 리뷰 코멘트도 자동으로 반영한다

리뷰가 붙으면 사람이 먼저 읽고 복구하는 대신,

• 코멘트를 해당 세션으로 전달하고
• 에이전트가 수정하게 하고
• 다시 CI와 리뷰를 돌리는 흐름이 좋다

이렇게 해야 “PR이 많을수록 사람이 더 바빠지는 문제”를 줄일 수 있다.

설정에서 중요한 포인트

reactions

가장 중요한 자동화 지점이다.

예시:

reactions:
  ci_failed:
    action: spawn_agent
    prompt: "CI failed on this PR. Read the failure logs and fix the issues."
 
  changes_requested:
    action: spawn_agent
    prompt: "Review comments have been posted. Address each comment and push fixes."
 
  approved:
    action: notify
    channel: slack
    message: "PR approved and ready to merge."

이 구조의 장점은 단순하다.

• 실패는 수정으로
• 리뷰는 재작업으로
• 승인만 사람에게 알림으로

workspace

각 에이전트는 서로 분리된 워크스페이스를 가져야 한다.

이유:

• 파일 충돌을 줄일 수 있다
• PR 단위로 추적하기 쉽다
• 어느 에이전트가 무슨 일을 했는지 명확해진다

notifier

알림은 너무 많으면 오히려 망가진다.

권장:

• 실패 전체를 사람에게 보내지 말고
• 진짜 판단이 필요한 것만 보낸다

좋은 운영 습관

• 에이전트 수를 갑자기 너무 많이 늘리지 말 것
• 처음엔 2~3개 세션으로 시작할 것
• PR 하나당 역할을 명확히 나눌 것
• 사람은 아키텍처와 판단, 에이전트는 구현과 반복 수정에 집중시킬 것
• 실패를 발견하면 즉시 reaction 흐름에 넣을 것

자주 하는 실수

1) 대시보드만 보고 끝내는 것

대시보드는 보기 위한 도구가 아니다. 상태를 행동으로 연결해야 한다.

2) 에이전트에게 너무 큰 작업을 주는 것

작업이 크면 drift가 생긴다. 오케스트레이터의 강점은 쪼개기다.

3) 알림이 너무 많은 것

알림이 많아지면 결국 무시하게 된다. notifier는 최소화하는 편이 낫다.

4) 인간이 계속 중간에 끼어드는 것

이 도구는 “사람이 조금 더 편하게 새로고침하는 툴”이 아니다. 인간의 개입을 줄이기 위해 쓰는 것이다.

추천 사용 패턴

패턴 A. 야간 자동 진행

1. 밤에 세션을 준비한다
2. 에이전트가 작업한다
3. 아침에 CI/PR 상태를 본다
4. 실패는 자동 수정한다
5. 승인만 검토한다

패턴 B. 병렬 기능 개발

1. 기능을 3~5개 작업으로 나눈다
2. 각 작업을 다른 에이전트에 준다
3. PR과 CI를 각각 추적한다
4. 충돌이 나면 오케스트레이터가 정리한다

패턴 C. 리뷰 루프 자동화

1. PR 생성
2. 자동 리뷰
3. 수정
4. 재리뷰
5. 승인

이 루프가 안정되면 사람이 해야 할 일은 크게 줄어든다.

이런 사람에게 특히 맞다

• AI 코딩 에이전트를 이미 쓰고 있다
• PR 수가 많아져서 관리가 힘들다
• 자동화보다 조율이 더 중요하다고 느낀다
• GitHub 기반 개발 워크플로우를 갖고 있다

같이 보면 좋은 노트

• 2026-04-30-composio-agent-orchestrator — 상세 요약 노트
• moc-ai-agents-orchestration — 오케스트레이션 관련 노트 모음
• moc-claude-code — Claude Code 관련 기본 개념
• 2026-04-30-archon-harness-builder — 더 결정론적인 워크플로우 하네스 비교용

짧은 결론

Composio Agent Orchestrator는 “AI 에이전트 여러 개를 돌리는 도구”가 아니라, AI 에이전트들을 실제로 운영 가능한 시스템으로 만드는 도구에 가깝다.

처음에는 단순히 편해 보이지만, 익숙해지면 병목이 어디 있는지 보인다. 병목은 에이전트가 아니라, 에이전트를 일일이 돌보는 사람이다. 이 도구는 그 부분을 줄이려는 시도다.