내장 워크플로우 및 오케스트레이션 패턴

Revka는 처음부터 직접 작성하지 않아도 되는 두 가지 오케스트레이션 라이브러리를 제공합니다. 내장 워크플로우 템플릿(이름으로 실행하고 복제하여 편집할 수 있는 선언형 YAML)과 멀티 에이전트 오케스트레이션 패턴(여러 에이전트를 동시에 조율하는 명령형 MCP 도구)입니다. 이 두 가지 위에는 임시 조율을 위한 에이전트 팀(spawn_team)과 에이전트 간 채팅룸이 있습니다.

빈 파일 대신 동작하는 템플릿에서 시작하고 싶거나, 단일 에이전트로는 부족해서 검토자, 비평자, 팬아웃, 또는 감독 위원회가 필요할 때 이 페이지를 참고하세요. YAML 스키마를 아직 학습 중이라면 먼저 첫 번째 워크플로우와 스텝 타입 참고서를 읽어보세요. 여기서 설명하는 패턴은 Operator MCP 서버에서 실행되므로 사이드카가 설치되어 있는지 확인하세요(Python MCP 사이드카 설치 참고).

내장 워크플로우 템플릿

오퍼레이터는 일반적인 개발 및 콘텐츠 패턴을 다루는 21개의 사전 빌드 워크플로우 YAML 정의를 제공합니다. 이 정의들은 빌드 시점에 revka 바이너리에 포함되어 워크스페이스에 시드되므로, 사용하기 위해 Python 오퍼레이터를 별도로 체크아웃할 필요가 없습니다. run_workflow(workflow="<name>", ...) 또는 POST /api/workflows/run/{name}으로 이름을 지정해 참조할 수 있습니다.

워크플로우	역할	주요 입력
code-review	코더가 구현하고 검토자가 확인한 뒤, 거부 시 수정본 생성	task, cwd
code-review-advanced	향상된 코드 리뷰 플로우	task, cwd
bug-fix	연구자가 조사하고 코더가 수정하며 테스터가 검증	bug_description
spec-to-impl	아키텍트가 설계하고 코더가 구현하며 검토자가 검증	task
refactor	연구자 분석 → 아키텍트 계획 → 코더 구현 → 검토자 승인	target
multi-module-review	여러 모듈에 걸친 병렬 리뷰	—
research-only	순수 리서치 워크플로우	—
data-pipeline-ingest	데이터를 수집·분석하고 리포트 엔티티 생성	task, cwd
data-pipeline-distribute	파이프라인 결과 배포	—
data-pipeline-summarize	파이프라인 출력 요약	—
revka-agentops-a2a	human_approval 게이트가 있는 IT 인시던트 대응 제어 플레인	incident_id, alert_payload, cwd
revka-workflow-composer	새 워크플로우를 구성하기 위한 메타 워크플로우	—
architecture-discussion	아키텍처 결정을 위한 그룹 채팅	—
novel-writing	창작 글쓰기 워크플로우	—
cold-outreach	아웃리치 콘텐츠 생성	—
canonworks-serial-episode-factory	연재 스토리 에피소드 생성	—
canonworks-serial-canon-state-sync	연재 소설의 캐논 상태 동기화	—
quantum-soul-arc-room	Quantum Soul 연재의 아크 기획 제작룸	—
quantum-soul-episode-room	에피소드 제작룸	—
quantum-soul-production-room	최종 프로덕션 룸	—
smoke-test-all-steps	모든 스텝 타입을 실행하는 통합 테스트	—

내장 정의는 복사해서 활용하기 좋은 출발점입니다. 예를 들어 code-review는 agent(코더) → agent(검토자) → conditional(판정 확인) → agent(수정) → output 순으로 체인을 구성하며, 검토자의 텍스트에 APPROVED가 포함되어 있는지에 따라 분기합니다.

steps:
  - id: review
    type: agent
    depends_on: [implement]
    agent:
      agent_type: codex
      role: reviewer
      prompt: |
        Review the changes. Say APPROVED if good,
        else NEEDS_CHANGES with specific feedback.
  - id: check_verdict
    type: conditional
    depends_on: [review]
    conditional:
      branches:
        - condition: "${review.output} contains APPROVED"
          goto: summary
        - condition: default
          goto: fix

참고

내장 워크플로우는 대시보드에서 source: builtin으로 표시되며, 편집하거나 삭제할 수 없고 복제만 가능합니다. **복제(Duplicate)**를 사용하면 편집 가능한 custom 사본을 얻을 수 있습니다. revka-agentops-a2a 템플릿은 사람이 개입하는 승인 게이트의 대표 예시입니다(실행, 승인 및 체크포인트 참고).

revka workflows — 템플릿 목록 조회 및 동기화

내장 YAML 파일은 워크스페이스의 operator_mcp/workflow/builtins/ 경로에 위치하며, 이는 가장 낮은 우선순위의 탐색 위치입니다(전체 우선순위 순서는 첫 번째 워크플로우 참고). revka workflows 서브커맨드는 이 온디스크 사본을 관리합니다.

revka workflows list            # list the templates embedded in this binary
revka workflows sync            # seed templates into the workspace (skips existing)
revka workflows sync --force    # overwrite existing template files

커맨드	플래그	동작
revka workflows list	—	현재 실행 중인 바이너리에 컴파일된 워크플로우 템플릿 목록을 출력합니다.
revka workflows sync	--force	내장된 YAML을 <workspace>/operator_mcp/workflow/builtins/에 복사합니다. --force를 전달하지 않으면 기존 파일은 유지됩니다.

온보딩 시 이 템플릿들이 자동으로 시드됩니다. Revka를 업그레이드한 후 새 템플릿을 반영하려면 revka workflows sync를 실행하세요. sync는 기본적으로 누락된 파일만 작성하므로 다른 워크플로우에 대한 편집 내용이 덮어쓰이지 않습니다. 출시 버전으로 복원하려는 경우에만 --force를 사용하세요.

팁

대상 디렉토리는 게이트웨이와 cron 스케줄러가 스캔하는 경로와 일치해야 하므로, 항상 활성 워크스페이스에 동기화하세요. Revka를 업그레이드한 후 내장 템플릿을 최신 출시 상태로 새로 고치려면 revka workflows sync --force를 사용하는 것이 가장 깔끔한 방법입니다.

워크플로우 프리셋 (명령형)

프리셋은 YAML 워크플로우보다 가벼운 형태로, YAML 대신 코드로 정의된 재사용 가능한 오케스트레이션 패턴입니다. 프리셋은 각 스텝에 role, agent_type, 선택적 depends_on 엣지(스텝 인덱스 기준), 선택적 review_loop 플래그로 구성된 스텝 목록입니다. code-review, spec-to-impl, bug-fix 등의 프리셋은 명령형 MCP 도구로 제공되며, 멀티 에이전트 실행을 확정하기 전에 미리 확인(preview)할 수 있습니다.

도구	목적
list_workflow_presets(tag?)	내장 및 커스텀 프리셋 목록 조회; tag(예: review, testing)로 필터링 가능.
save_workflow_preset(name, description, steps, tags?)	커스텀 프리셋을 저장하여 재사용.
get_workflow_plan(preset)	실행하지 않고 프리셋의 실행 계획(스텝, 웨이브, 의존성)을 미리 확인.

토큰을 소비하기 전에 get_workflow_plan으로 웨이브 구조(어떤 스텝이 병렬로 실행되고 어떤 스텝이 다른 스텝을 기다리는지)를 검증하세요. 프리셋은 전체 YAML 워크플로우보다 단순합니다. 에이전트 토폴로지를 기술할 뿐, 셸, Python, 조건문, 트리거가 포함된 완전한 타입 기반 스텝 문법은 지원하지 않습니다.

멀티 에이전트 오케스트레이션 패턴

단일 에이전트로 충분하지 않을 때, 오퍼레이터는 MCP 도구로 6가지 고수준 패턴을 제공합니다. 각 패턴은 여러 에이전트를 스폰하고 조율한 뒤 구조화된 결과를 반환합니다. 또한 워크플로우 스텝 타입(map_reduce, supervisor, group_chat, handoff)으로도 사용할 수 있습니다. 스텝 타입 참고서를 참조하세요.

review_fix_loop 검토자가 판정(APPROVED / NEEDS_CHANGES / BLOCKED)을 파싱하고, 수정자가 변경을 적용한 뒤 반복합니다.

refinement_loop 0~100 품질 점수 및 신뢰도 기반 비평자 선택을 통한 비평 → 개선 사이클. review_fix_loop의 권장 대체재입니다.

handoff_agent 발견 내용, 수정된 파일, 작업 상태를 한 에이전트에서 다른 에이전트로 전달합니다.

group_chat 순서를 돌아가며 진행하는 중재 멀티 에이전트 토론. 트랜스크립트, 요약, 결론을 반환합니다.

supervisor_run 동적 위임 — 슈퍼바이저가 현재까지의 결과를 바탕으로 다음 전문가를 선택합니다.

map_reduce N개의 병렬 매퍼에 작업을 분산하고, 리듀서가 모든 결과를 종합합니다.

review_fix_loop

완료된 에이전트의 작업에 대해 검토자를 스폰하고 판정(APPROVED / NEEDS_CHANGES / BLOCKED)을 파싱합니다. 변경이 필요한 경우 피드백과 함께 수정자를 스폰하며, max_rounds에 도달할 때까지 반복합니다.

review_fix_loop(coder_agent_id, cwd, task?, reviewer_type?, fixer_type?,
                max_rounds?, review_focus?, timeout?)

파라미터	기본값	의미
coder_agent_id	— (필수)	검토할 작업을 완료한 에이전트.
cwd	— (필수)	검토자와 수정자의 작업 디렉토리.
reviewer_type	codex	검토자 에이전트 타입.
fixer_type	codex	수정자 에이전트 타입.
max_rounds	2 (최대 5)	검토 → 수정 반복 횟수.
review_focus	—	추가 지침, 예: focus on security.
timeout	300	에이전트당 타임아웃(초).

refinement_loop

review_fix_loop의 구조화된 후속 패턴입니다. 0~100 품질 점수, 신뢰도 기반 비평자 선택(비평자의 신뢰 점수가 0.7 미만으로 떨어지면 자동 전환), 폴백 사다리(창작자 → 전담 수정자 → 에스컬레이션)를 갖춘 비평 → 개선 사이클을 실행합니다.

refinement_loop(creator_agent_id, cwd, task?, creator?, critic?, model?,
                max_rounds?, threshold?, review_focus?, timeout?)

파라미터	기본값	의미
creator_agent_id	— (필수)	검토 및 개선할 작업을 완료한 에이전트.
cwd	— (필수)	비평자와 수정자의 작업 디렉토리.
creator	codex	수정을 적용하는 에이전트 타입.
critic	claude	비평자 에이전트 타입; 신뢰 점수가 0.7 미만이면 자동 전환.
max_rounds	2 (최대 5)	비평 → 개선 반복 횟수.
threshold	70	통과에 필요한 품질 점수(0~100).
timeout	300	에이전트당 타임아웃(초).

팁

새 작업에는 review_fix_loop 대신 refinement_loop를 사용하세요. 수치 점수와 신뢰도 기반 비평자 선택으로 명확한 종료 조건을 제공하고, 비평자의 이력에 따라 적응합니다. 신뢰 점수는 템플릿별로 추적됩니다(get_agent_trust 참고).

handoff_agent

소스 에이전트에서 발견 내용, 수정된 파일, 작업 상태를 추출하여 수신 에이전트의 프롬프트에 주입하고, Kumiho에서 핸드오프 체인을 추적합니다. 컨텍스트를 재도출하지 않고 연구자의 발견 내용을 코더에게, 또는 코더의 작업을 테스터에게 전달할 때 사용합니다.

handoff_agent(from_agent_id, reason, to_agent_type?, task?, cwd?, model?, timeout?)

파라미터	기본값	의미
from_agent_id	— (필수)	핸드오프할 작업을 완료한 에이전트.
reason	— (필수)	핸드오프 이유.
to_agent_type	claude	수신 에이전트 타입 또는 풀 템플릿 이름.
task	—	수신 에이전트의 구체적인 작업.
cwd	소스 에이전트의 cwd	수신 에이전트의 작업 디렉토리.
timeout	300	에이전트당 타임아웃(초).

group_chat

중재된 멀티 에이전트 토론을 실행합니다. 참가자들이 순서를 돌아가며 발언(round_robin 또는 moderator_selected)하고, 진행자가 마지막에 합의를 도출합니다. 트랜스크립트, 요약, 결론을 반환합니다.

group_chat(topic, participants, moderator?, strategy?, max_rounds?, cwd?, model?, timeout?)

파라미터	기본값	의미
topic	— (필수)	토론 주제.
participants	— (필수)	에이전트 타입 또는 풀 템플릿 이름(최소 2개).
moderator	claude	진행자 에이전트.
strategy	moderator_selected	발언 순서: round_robin 또는 moderator_selected.
max_rounds	8 (최대 20)	최대 발언 횟수.
timeout	120	턴당 타임아웃(초).

architecture-discussion 내장 워크플로우는 group_chat 템플릿이며, 스텝 인스펙터에서 각 group_chat 스텝의 전체 트랜스크립트를 확인할 수 있습니다.

supervisor_run

동적 위임 방식입니다. 슈퍼바이저가 작업을 분석하고 가장 적합한 전문가에게 서브태스크를 위임하며, 결과를 통합한 뒤 현재까지의 결과를 바탕으로 다음 에이전트를 선택하는 과정을 반복합니다. 정적 DAG 방식인 spawn_team과 달리, 토폴로지는 런타임에 결정됩니다.

supervisor_run(task, cwd, templates?, max_iterations?, supervisor_type?, model?, timeout?)

파라미터	기본값	의미
task	— (필수)	수행할 작업.
cwd	— (필수)	작업 디렉토리.
templates	풀 내 전체	사용할 전문가 풀 템플릿 이름.
max_iterations	5 (최대 10)	위임 → 통합 반복 횟수.
supervisor_type	claude	슈퍼바이저 에이전트.
timeout	300	에이전트당 타임아웃(초).

map_reduce

splits(파일 경로, 섹션, 서브태스크) 목록을 N개의 병렬 매퍼 에이전트에 분산하고, 리듀서가 모든 결과를 종합합니다. 여러 파일을 한 번에 검토하거나 분석할 때 적합합니다.

map_reduce(task, splits, cwd, mapper?, reducer?, concurrency?, model?, timeout?, halt_on_failure?)

파라미터	기본값	의미
task	— (필수)	전체 작업 설명.
splits	— (필수)	병렬로 처리할 세그먼트(최소 2개).
cwd	— (필수)	작업 디렉토리.
mapper	claude	매퍼 에이전트 타입 또는 풀 템플릿.
reducer	claude	리듀서 에이전트 타입 또는 풀 템플릿.
concurrency	3 (최대 10)	최대 동시 매퍼 수.
halt_on_failure	false	하나의 매퍼가 실패하면 나머지 매퍼를 중단.
timeout	300	에이전트당 타임아웃(초).

에이전트 팀 (spawn_team)

팀은 에이전트 템플릿 묶음과 의존성 엣지를 함께 저장한 단위로, Kumiho의 Revka/Teams 하위에 저장됩니다. 엣지(REPORTS_TO, SUPPORTS, DEPENDS_ON)는 DAG 토폴로지를 정의하고, spawn_team은 이를 웨이브 단위로 실행합니다. 미해결 의존성이 없는 에이전트들이 동시에 실행되고, 해당 웨이브가 완료되면 다음 웨이브가 실행됩니다. 이는 동적 방식인 supervisor_run의 정적 대응 패턴입니다.

도구	목적
create_team(name, description, member_krefs, edges?)	팀 번들을 생성하거나 업데이트합니다(업데이트 시 멤버와 엣지가 교체됨).
list_teams()	Kumiho에서 모든 팀 목록을 조회합니다.
get_team(kref)	멤버와 엣지를 포함한 팀 상세 정보를 조회합니다.
search_teams(query)	이름 또는 설명으로 팀을 검색합니다.
spawn_team(team_kref, task, cwd?, dry_run?, halt_on_failure?, resume_from?)	팀을 웨이브 단위로 실행합니다.
get_spawn_progress(team_name?)	웨이브별 진행 상황, 완료 현황, 중단 이유를 확인합니다.
lint_team(team_kref, task?)	역할 균형, 명명 규칙, 역량 커버리지, 엣지 완전성을 검사합니다.

엣지는 {from_kref, to_kref, edge_type} 형태로 선언합니다.

{
  "name": "rust-dev-team",
  "description": "Implement + review Rust features",
  "member_krefs": ["kref://.../coder", "kref://.../reviewer"],
  "edges": [
    { "from_kref": "kref://.../reviewer", "to_kref": "kref://.../coder", "edge_type": "DEPENDS_ON" }
  ]
}

주요 동작:

• **dry_run: true**는 실제로 스폰하지 않고 그래프를 검증하여 스테이지 미리보기를 반환합니다. 실제 실행 전에 lint_team과 함께 사용하세요.
• **halt_on_failure**는 기본값이 true로, 업스트림 스테이지에 실패가 있으면 다운스트림 스테이지를 중단합니다. false로 설정하면 실패와 관계없이 계속 진행합니다.
• **resume_from**은 체크포인트 ID를 받습니다. 스폰이 중간에 중단되면 응답에 checkpoint_id가 포함됩니다. 처음부터 다시 실행하는 대신 실패한 웨이브부터 재개하려면 이 ID를 다시 전달하세요.

에이전트 및 팀 모델에 대한 전반적인 내용은 에이전트, 팀 및 스웜과 에이전트 스폰 및 조율을 참고하세요.

에이전트 간 채팅룸

채팅룸은 스폰된 에이전트 간의 비동기 조율을 위한 명명된 채널입니다. 에이전트가 메시지를 게시하고, 선택적으로 다른 에이전트를 @멘션하면(현재 유휴 상태인 해당 에이전트에게 후속 프롬프트가 전달됨) 공유 로그를 읽을 수 있습니다. 세션 매니저가 이러한 멘션 기반 인터럽트를 자동으로 연결하므로, 채팅룸은 팀을 위한 공유 메모리이자 의사결정 로그 역할을 합니다.

도구	목적
chat_create(name, purpose?)	룸을 생성합니다.
chat_post(room_id, content, sender_id?, sender_name?, mentions?, reply_to?)	메시지를 게시합니다. mentions는 유휴 에이전트에게 후속 프롬프트를 전달합니다.
chat_read(room_id, limit?, since?)	최근 메시지를 읽습니다(기본 50개; since는 ISO 타임스탬프로 새 메시지만 필터링).
chat_list()	모든 활성 룸 목록을 조회합니다.
chat_wait(room_id, timeout?)	새 메시지를 최대 60,000ms까지 롱폴링합니다.
chat_delete(room_id)	룸과 메시지를 삭제합니다.

{ "name": "design-review", "purpose": "Review the auth module" }

룸은 에이전트 세션이 유지되는 동안 지속됩니다. 제공된 operator-orchestrator.md 스킬에는 룸과 spawn_team 및 위의 패턴들을 결합하는 “채팅룸을 백본으로 하는” 팀 조율 패턴이 자세히 설명되어 있습니다.

참고

채팅룸은 선택적인 Node.js 세션 매니저 사이드카가 필요합니다. 이 사이드카는 채팅 서비스를 호스팅하고 멘션 인터럽트를 중계합니다. 설치되어 있지 않으면 라이브 실행 뷰와 채팅 기반 조율에 이벤트가 수신되지 않습니다. Python MCP 사이드카 설치를 참고하세요.

패턴 선택 가이드

하고자 하는 작업	사용 패턴
판정에 따라 단일 에이전트 출력 개선	review_fix_loop
품질 점수에 따라 단일 에이전트 출력 개선	refinement_loop
한 에이전트에서 다른 에이전트로 컨텍스트 전달	handoff_agent
여러 에이전트 간 의사결정	group_chat
시스템이 다음 작업자를 자동 선택	supervisor_run
다수의 파일/섹션을 병렬 처리	map_reduce
고정된 반복 가능한 에이전트 토폴로지 실행	spawn_team (또는 YAML 워크플로우)
메시지를 통한 에이전트 간 비동기 조율	에이전트 간 채팅룸

다음 단계

스텝 타입 참고서 YAML에서 map_reduce, supervisor, group_chat, handoff 스텝 타입을 사용하는 방법.

첫 번째 워크플로우 워크플로우를 처음부터 작성하고 저장하여 실행하는 방법.

실행, 승인 및 체크포인트 승인 게이트, 재시도, 실행 수명 주기.

에이전트 스폰 및 조율 create_agent, 수명 주기 도구, 팀, 오케스트레이션 스킬.

Operator MCP 이 워크플로우와 패턴을 실행하는 Python 사이드카.

revka 스킬, 워크플로우 및 SOP 템플릿, 스킬, SOP를 위한 CLI 인터페이스.