워크플로우, 편집기, 실행

대시보드는 전체 워크플로우 생명주기를 위한 세 가지 화면을 제공합니다. 정의를 탐색하고 관리하는 Workflows 페이지 (/workflows), 동기화된 DAG/YAML 뷰와 Architect AI 지원으로 워크플로우를 작성하는 Workflow Editor 오버레이, 그리고 실행을 시작·모니터링·승인·재시도·단계별 검사하는 Workflow Runs 페이지 (/runs)입니다. 이 페이지의 모든 동작은 게이트웨이 워크플로우 API 위의 얇은 클라이언트이므로, 여기서 할 수 있는 모든 작업을 스크립트로도 수행할 수 있습니다. 자세한 내용은 Workflows & Architect API를 참조하세요.

워크플로우를 시각적으로 운영하려면 이 페이지를 사용하세요. YAML을 직접 작성하려면 첫 번째 워크플로우와 Workflow YAML 레퍼런스부터 시작하고, 실행 생명주기에 대한 심층 내용은 실행, 승인 & 체크포인트를 참조하세요.

Workflows 페이지

사이드바의 Orchestration 섹션에서 Workflows를 열거나 /workflows로 직접 이동하세요. 이 페이지에는 모든 정의가 나열되고, 선택된 정의의 읽기 전용 DAG가 렌더링되며, 툴바에서 생성/실행/편집 생명주기를 수행할 수 있습니다. ?workflow=<name_or_kref>로 특정 정의에 딥링크할 수 있습니다.

정의는 Kumiho 그래프 메모리에 저장된 선언적 YAML 파이프라인입니다(스페이스 Revka/Workflows, 아이템 종류 workflow). 실행은 config.toml이 아닌 operator-mcp 백엔드가 담당합니다. 저장할 때마다 새 리비전이 작성되고 published로 태그되므로 히스토리가 보존됩니다.

워크플로우 선택 및 조회

• 워크플로우 선택기 — 모든 정의의 드롭다운으로, 각 항목에는 이름과 버전/단계 배지가 표시됩니다. 하나를 선택하면 DAG가 로드됩니다.
• DAG 캔버스 (읽기 전용) — 의존성 엣지가 포함된 단계 그래프입니다. 노드를 클릭하면 단계 인스펙터가 열립니다.
• 단계 인스펙터 패널 — 선택한 단계의 role, agent_type, skills, 템플릿 이름을 표시하며, Runs 페이지에서 해당 단계를 여는 링크를 제공합니다.
• 탭 — Definition(위의 DAG)과 Runs 사이를 전환합니다. Runs 탭은 이 워크플로우로 필터링된 /runs?workflow=<name>으로 이동합니다.

이 페이지는 목록을 위해 GET /api/workflows?include_deprecated=true&include_definition=false를 호출하고, GET /api/workflows/revisions/{*kref}로 각 YAML을 필요 시 가져오며, GET /api/workflows/runs?limit=40으로 실행 횟수 배지를 표시합니다.

생명주기 동작

툴바에는 전체 CRUD 생명주기가 포함됩니다. 각 동작은 하나의 게이트웨이 호출에 매핑됩니다.

동작	설명	엔드포인트
Execute	선택한 워크플로우의 실행을 트리거합니다	POST /api/workflows/run/{name}
Create	빈 워크플로우로 편집기 오버레이를 엽니다	POST /api/workflows (저장 시)
Edit	선택한 워크플로우로 편집기 오버레이를 엽니다	PUT /api/workflows/{*path} (저장 시)
Duplicate	새 편집 가능한 정의로 복제합니다	POST /api/workflows (저장 시)
Deprecate	deprecated 플래그를 소프트 토글합니다	POST /api/workflows/deprecate
Delete	정의를 영구적으로 삭제합니다	DELETE /api/workflows/{*path}

참고

기본 제공 워크플로우는 편집하거나 삭제할 수 없으며 복제만 가능합니다. 기본 제공 워크플로우를 복제하면 편집 가능한 사본을 얻을 수 있습니다. 편집기에서 저장하면 X-Revka-Editor-Session 헤더가 전송되므로, 두 명의 운영자가 동일한 워크플로우를 편집할 때 서로의 리비전을 몰래 덮어쓰는 일이 방지됩니다.

정의를 생성·업데이트·deprecated 처리·삭제하면 해당 정의의 cron 작업도 동기화됩니다. YAML에 cron 트리거가 선언된 워크플로우는 저장 시 cron 작업이 등록되고, deprecated 처리하거나 삭제하면 제거됩니다. 자세한 내용은 변수, 표현식 & 트리거를 참조하세요.

Workflow Editor (전체 화면 오버레이)

Create, Edit, Duplicate를 클릭하면 편집기가 전체 화면 오버레이로 열립니다. 시각적 DAG와 YAML 문서라는 두 가지 방식으로 동일한 워크플로우를 동시에 편집하며, 양방향 동기화를 유지합니다. 또한 AI 공동 저자(Architect), 단계 팔레트, 단계별 설정 패널, 리비전 히스토리 스트립이 제공됩니다.

Visual (DAG)

WorkflowDagWorkspace는 커스텀 단계 노드와 엣지로 구성된 대화형 캔버스로, 미니맵과 조건 분기의 TRUE/FALSE 엣지 레이블을 제공합니다. StepTypePalette에서 단계 유형을 캔버스로 드래그하세요. 지원되는 단계 유형은 code, agent, shell, test, human_approval, gate, parallel, for_each, a2a, handoff 등입니다. 드래그한 후 단계 간 의존성을 연결합니다.

YAML

YAML 패널은 YAML 구문 지원, 단계 디렉티브 명령 자동완성(EditorCommandList), 단계 입출력을 위한 표현식 텍스트 영역을 갖춘 CodeMirror 편집기입니다. YAML을 직접 편집하면 DAG가 업데이트되고, DAG를 재배치하면 YAML이 업데이트됩니다. 어느 패널이든 매 순간 진실의 원천입니다.

단계 설정

임의의 노드를 선택하면 오른쪽에 StepConfigPanel이 열리며, 해당 단계 유형의 모든 필드를 편집할 수 있습니다. 자격 증명 서비스를 호출하는 단계에는 AuthProfilePicker가 표시되며, 인증 프로파일 드롭다운과 인라인 “새 인증 프로파일” 모달을 제공합니다. 이 선택기는 다음 엔드포인트를 사용합니다.

GET    /api/auth/profiles        # list profiles for the dropdown
POST   /api/auth/profiles        # create a new profile inline
DELETE /api/auth/profiles/{id}   # remove a profile

에이전트 단계는 GET /api/agents?page=1&per_page=50에서 할당 가능한 에이전트 목록도 가져옵니다.

Architect (AI 보조 편집)

Architect는 편집기 내부의 채팅 패널입니다. 원하는 변경 사항을 자연어로 설명하면(“게시 전에 리뷰 게이트를 추가해줘”) LLM이 revise_workflow 도구를 호출해 워크플로우를 실시간으로 편집합니다. 이 도구는 YAML을, 그리고 결과적으로 DAG를 인플레이스로 재작성합니다. 메시지는 operator WebSocket 세션을 통해 전달됩니다.

Architect가 도구를 호출하는 대신 채팅에 YAML을 출력하는 경우, 편집기는 해당 YAML을 POST /api/architect/validate_yaml에 게시하는 폴백을 실행합니다. 이를 통해 캔버스에 반영되기 전 스키마 및 워크플로우 수준 검사를 통과합니다. Architect의 전체 인터페이스(제안, 검증, 리비전 목록, 되돌리기)는 Workflows & Architect API에 문서화되어 있습니다.

리비전 히스토리 스트립

편집기 하단에는 워크플로우의 과거 리비전이 나열된 수평 RevisionHistoryStrip이 있습니다. 이 스트립은 다음 엔드포인트로 채워집니다.

GET /api/architect/revisions?workflow_kref=<kref>

리비전을 클릭하면 미리 볼 수 있으며, 해당 리비전을 현재 published 리비전으로 재게시하여 되돌릴 수 있습니다.

POST /api/architect/republish
Content-Type: application/json

{ "revision_kref": "kref://Revka/Workflows/daily-report.workflow?r=2" }

재게시는 아무것도 삭제하지 않습니다. 이전 리비전을 published로 재태그하므로 되돌리기는 안전하며, 그 자체도 되돌릴 수 있습니다.

저장 및 검증

저장하면 현재 그래프가 YAML로 직렬화되고 유효성 검사 후 저장됩니다. 검증은 operator의 6단계 validate_workflow 검사를 실행합니다(중복 단계 ID, 의존성 참조, 사이클 감지, 단계별 설정, 변수 참조, 트리거 필드). 오류는 인라인으로 표시되며 저장이 차단됩니다. 성공하면 게이트웨이가 새 리비전을 작성하고, published로 태그하며, cron 작업을 재동기화합니다. 자세한 규칙은 Workflow YAML 레퍼런스를 참조하세요.

주의

저장하지 않은 초안은 내비게이션 간 편집기의 초안 저장소에 유지되므로, 편집 중에 나가도 즉시 작업이 사라지지는 않습니다. 그러나 저장하기 전까지는 영구 리비전이 아닙니다. 사용하기 전에 반드시 명시적으로 저장하세요.

Workflow Runs 페이지

대시보드(개요 페이지의 “Open all runs” 링크 또는 워크플로우의 Runs 탭)에서 Workflow Runs를 열거나 /runs로 직접 이동하세요. 이 페이지에서 개별 실행을 시작·모니터링·감사합니다. 실행 목록, 단계별 상태 오버레이가 포함된 DAG, 단계 인스펙터, 승인 패널, 의존성 경로 하이라이트, 아티팩트 뷰어가 표시됩니다.

다음 쿼리 파라미터로 딥링크할 수 있습니다.

파라미터	의미
?run=<run_id>	특정 실행을 엽니다
?workflow=<name_or_kref>	실행 목록을 하나의 워크플로우로 필터링합니다
?node=<step_id>	실행에서 단계를 미리 선택합니다
?path=all|failed|blocked	경로 하이라이트 모드를 설정합니다 (아래 참조)

이 페이지는 GET /api/workflows/runs?limit=20&workflow=<name>으로 실행 목록을, GET /api/workflows/runs/{run_id}로 선택된 실행의 전체 상세 정보를 읽습니다. 그리고 GET /api/workflows/revisions/{kref}를 통해 표시되는 DAG를 실행 당시의 정확한 YAML에 고정합니다. 정의의 이후 편집이 과거 실행의 그래프를 덮어쓰지 않습니다.

실행 상태

실행의 상태 필은 색상으로 구분됩니다. 상태 목록은 다음과 같습니다.

상태	의미
pending	생성되었지만 실행기가 아직 처리하지 않은 상태.
running	실행기가 활성 상태.
paused	human_approval 또는 human_input 게이트에서 대기 중.
completed	모든 단계가 성공적으로 완료됨.
failed	단계가 실패했으며, 실행을 재시도할 수 있도록 체크포인트가 보존됨.
cancelled	사용자 또는 시스템에 의해 중지됨.
stale	체크포인트와 라이브 잠금이 없는 비종단 상태 — 예를 들어 재배포 후 로컬 상태가 초기화된 경우.

for_each 단계는 추가로 루프 진행 레이블(x/total)을 표시합니다.

단계 인스펙터 탭

실행 DAG에서 임의의 노드를 클릭하면 단계 인스펙터가 열립니다. 일곱 개의 탭이 있습니다.

• Summary — 상태, 에이전트 ID, 역할, 템플릿, 출력 미리 보기. 완료된 conditional/gate 단계에는 매칭된 분기, goto 대상, 분기 값이 표시됩니다.
• Transcript — 해당 단계에서 에이전트의 전체 대화.
• Input — 단계가 받은 해석된 입력값.
• Output — 단계의 텍스트 출력.
• Errors — 실행기 오류, output_data, stderr, 또는 캡처된 입력에서 가져온 실패 상세 정보.
• Tool Calls — 단계 에이전트가 호출한 도구 호출: 이름, 인자, 결과, 상태.
• Messages — 단계 에이전트의 메시지 스트림.

Tool Calls 및 Messages 탭은 에이전트별 활동 로그를 사용합니다.

GET /api/workflows/agent-activity/{agent_id}?view=summary&limit=100

승인 패널

단계가 approval_required(human_approval 게이트)에 진입하면, 인스펙터에 Approve 및 Reject 버튼과 선택적 피드백 텍스트 박스가 포함된 승인 패널이 표시됩니다. 제출하면 다음이 호출됩니다.

POST /api/workflows/runs/{run_id}/approve
Authorization: Bearer <token>
Content-Type: application/json

{ "approved": true, "feedback": "LGTM" }

게이트웨이는 재개하기 전에 내부 레지스트리에서 원자적으로 승인을 클레임합니다. 따라서 대시보드 클릭과 채팅 채널 응답이 동시에 도착해도 동일한 게이트를 이중으로 처리할 수 없습니다. 처리 완료 시 human_approval_resolved SSE 이벤트를 브로드캐스트하여 열린 모든 클라이언트가 업데이트됩니다.

참고

승인은 페이지를 가리지 않습니다. 보류 중인 승인이 있으면 대시보드의 어느 페이지에 있든 Approve/Reject 버튼이 포함된 글로벌 토스트가 표시되고, 내비게이션에 배지 카운트가 나타납니다. 게이트를 처리하기 위해 Runs 페이지에 있을 필요가 없습니다. 개념적 모델에 대해서는 자율성 수준 & 승인을 참조하세요.

경로 하이라이트

경로 하이라이트 컨트롤(?path=로도 설정 가능)은 DAG를 선택한 하위 집합으로 희미하게 처리하여 대규모 실행에서 인과 관계를 추적할 수 있게 합니다.

• all — 모든 단계, 희미하게 처리 없음.
• failed — 실패로 이어진 단계 체인.
• blocked — 일시 정지 또는 실패로 인해 차단된 단계 체인.

아티팩트 뷰어

에이전트 단계는 출력을 인라인으로 삽입하지 않고 Kumiho 아티팩트에 씁니다. 단계에서 아티팩트 뷰어 모달을 열면 구문 강조와 함께 아티팩트 본문을 읽을 수 있습니다. 다음 엔드포인트에서 가져옵니다.

GET /api/artifact-body?location=<uri>
Authorization: Bearer <token>

이는 인라인 미리 보기를 스크롤하는 대신 큰 단계 출력을 읽는 권장 방법입니다. 동일한 아티팩트는 자산 & 메모리 탐색기에서도 탐색할 수 있습니다.

실행 동작

각 실행의 툴바에는 나머지 생명주기 동작이 제공됩니다.

1. Execute / re-run — POST /api/workflows/run/{name}으로 새 실행을 트리거합니다. inputs, 선택적 cwd 작업 디렉터리, 그리고 “여기까지 실행”을 위한 target_step_id(대상 단계와 그 조상 단계만 실행)를 제공할 수 있습니다.

2. Retry — POST /api/workflows/runs/{run_id}/retry. 첫 번째 실패한 단계부터 재실행합니다. 성공한 단계의 출력은 체크포인트에서 복원되므로, 실패한 단계와 그 하위 단계만 다시 실행됩니다. 재시도에 선택적 cwd 오버라이드를 전달할 수 있습니다.

3. Cancel — POST /api/workflows/runs/{run_id}/cancel. 다음 단계 경계에서 실행기에 중지 신호를 보냅니다. 실행이 활성 상태이면 200을, 활성 레지스트리에 없으면(이미 완료되었거나 알 수 없는 경우) 404를, 이미 종단 상태이면 409를 반환합니다.

4. Delete — DELETE /api/workflows/runs/{run_id}. 실행 기록을 삭제(204 No Content)하고, ~/.revka/workflow_checkpoints/{run_id}.json의 로컬 체크포인트를 최선으로 정리합니다.

재시도, 취소, 승인은 모두 /api/events 스트림에 SSE 이벤트(workflow_retry, workflow_cancel, human_approval_resolved)를 브로드캐스트합니다. 페이지와 글로벌 승인 토스터가 이를 통해 실시간으로 업데이트됩니다. 자세한 내용은 실시간: WebSocket, SSE & 라이브 캔버스를 참조하세요.

관련 페이지

Workflows & Architect API 이 페이지들의 배경 게이트웨이 엔드포인트: 정의 CRUD, 실행 생명주기, 승인, Architect.

실행, 승인 & 체크포인트 실행 상태, 재시도 의미 체계, 체크포인트 파일, 스테일 실행에 대한 심층 설명.

Workflow YAML 레퍼런스 편집기가 작성하는 전체 정의 스키마: 모든 최상위 필드 및 검증 규칙.

단계 유형 레퍼런스 팔레트에서 드래그할 수 있는 모든 단계 유형: agent, shell, conditional, parallel, human_approval 등.

대시보드 개요 라이브 실행 DAG, 위험/에이전트 레일, 감사 체인 배지가 포함된 운영자 랜딩 페이지.

대시보드 실행하기 게이트웨이를 시작하고, 브라우저와 페어링하고, 사이드바 내비게이션에 익숙해지세요.