첫 번째 워크플로우

Revka 워크플로우는 멀티 스텝 파이프라인을 정의하는 YAML 파일입니다. 에이전트를 스폰하거나, 셸 또는 Python을 실행하거나, 조건에 따라 분기하거나, 결과를 게시하는 작업을 operator-mcp 백엔드가 결정론적으로 실행하고 Kumiho 그래프 메모리에 기록합니다. 이 페이지에서는 실질적인 작업을 수행하는 가장 작은 워크플로우를 작성하고, 대시보드에서 생성하고, 실행하고, 결과를 확인하는 전 과정을 안내합니다.

워크플로우를 처음 작성할 때 이 페이지를 참고하세요. 기본 사용에 익숙해지면 워크플로우 YAML 레퍼런스에서 모든 필드를, 스텝 타입 레퍼런스에서 각 스텝 타입을, 워크플로우, 편집기 & 실행에서 대시보드의 세부 기능을 확인할 수 있습니다. 시작하기 전에 게이트웨이와 operator 사이드카가 실행 중인지 확인하세요 — 퀵스타트 및 Python MCP 사이드카 설치를 참고하세요.

워크플로우의 구조

워크플로우는 몇 가지 최상위 필드와 순서가 있는 steps 목록으로 구성됩니다. 가장 작은 유용한 워크플로우는 작업을 수행하는 에이전트 스텝 하나와 결과를 렌더링하는 output 스텝 하나로 이루어집니다.

name: hello-world
version: "1.0"
description: A minimal two-step workflow.

steps:
  - id: greet
    type: agent
    agent:
      agent_type: claude
      role: researcher
      prompt: "Say hello in three languages."

  - id: summary
    type: output
    depends_on: [greet]
    output:
      format: text
      template: "Agent said: ${greet.output}"

여기서 두 가지 일이 발생합니다.

• greet 스텝은 researcher 역할과 프롬프트를 가진 claude 에이전트를 스폰합니다. 텍스트 결과는 ${greet.output}으로 참조할 수 있게 됩니다.
• summary 스텝은 greet에 depends_on을 선언하므로 이후에 실행되며, ${greet.output}을 보간하는 템플릿을 렌더링합니다. ${...} 구문은 런타임에 워크플로우 상태에서 값을 가져옵니다. (모든 네임스페이스는 변수, 표현식 & 트리거를 참고하세요.)

핵심 필드

가장 자주 사용하는 최상위 키입니다. name, version, 그리고 스텝이 최소 하나 이상 필요하며, 나머지는 선택 사항입니다.

필드	타입	필수 여부	의미
name	string	예	워크플로우를 식별하는 고유 슬러그.
version	string	예	시맨틱 버전, 예: "1.0".
description	string	아니요	사람이 읽기 위한 설명.
tags	list	아니요	검색 및 필터링을 위한 분류 레이블.
inputs	list	아니요	실행 시 전달받는 타입이 지정된 파라미터 (아래 참고).
outputs	list	아니요	호출자를 위해 스텝 결과와 매핑되는 명명된 출력.
steps	list	예	순서가 있는 스텝 정의 목록 — 최소 하나 이상 필요.
triggers	list	아니요	자동 실행 조건 (cron 스케줄 또는 엔티티 이벤트).
checkpoint	bool	아니요	각 스텝 후 상태를 저장합니다. 기본값은 true.

워크플로우에 파라미터를 추가하려면 inputs에 선언하고 ${inputs.<name>}으로 참조하세요.

name: hello-world
version: "1.0"
description: Greet the caller in a chosen language.

inputs:
  - name: language
    type: string            # string | number | boolean | list
    required: true
    default: "English"
    description: The language to greet in.

steps:
  - id: greet
    type: agent
    agent:
      agent_type: claude
      role: researcher
      prompt: "Say hello in ${inputs.language}."

  - id: summary
    type: output
    depends_on: [greet]
    output:
      format: text
      template: "Agent said: ${greet.output}"

팁

${inputs.name}이 입력 참조의 표준 형식입니다. 일부 UI 힌트에서는 ${input.name} (단수)로 표시될 수 있으나, 복수형인 inputs를 사용하세요.

워크플로우 파일의 위치

이름으로 워크플로우를 로드하거나 실행할 때, operator는 여러 위치를 탐색하며 나중에 발견된 소스가 앞선 소스를 덮어씁니다.

우선순위	위치	용도
3 (최고)	.revka/workflows/	프로젝트 로컬 재정의 (실행의 cwd 기준 상대 경로).
2	~/.revka/workflows/	사용자 전역 워크플로우.
1 (최저)	.revka/operator_mcp/workflow/builtins/	내장 기본값.
폴백	Kumiho 스페이스 Revka/Workflows	kref로 조회하는 클라우드 관리 정의.

따라서 프로젝트의 .revka/workflows/에 있는 hello-world.yaml은 동일한 이름의 사용자 전역 파일을 가리고, 사용자 전역 파일은 내장 파일을 가립니다.

참고

*.r{N}.yaml 형식으로 명명된 파일(예: hello-world.r3.yaml)은 리비전 아티팩트이며, 디렉터리 스캐너가 직접 로드하지 않습니다. kref 조회를 통해서만 접근됩니다. 대시보드에서 저장하면 Revka는 리비전 아티팩트를 작성하고 Kumiho 아티팩트를 등록합니다. 디렉터리 스캔이 인식하는 것은 {slug}.yaml (확장자만 있는 파일)입니다. .r{N}.yaml 파일에 대한 무해한 유효성 검사 경고는 정상입니다.

대시보드에서 워크플로우 만들기

대시보드는 워크플로우를 작성하고 저장하는 가장 빠른 방법입니다. 정의는 Kumiho 항목(스페이스 Revka/Workflows, 항목 종류 workflow)으로 저장되며, YAML은 workflow.yaml 리비전 아티팩트로 보관됩니다 — config.toml에 저장되지 않습니다. 저장할 때마다 새 리비전이 작성되고 published로 태그됩니다.

1. 사이드바의 Orchestration 섹션에서 Workflows를 열거나 /workflows로 이동하세요. (대시보드가 필요하신가요? 대시보드 실행을 참고하세요.)

2. Create를 클릭하면 빈 워크플로우의 전체 화면 편집기 오버레이가 열립니다.

3. 편집기는 시각적 DAG와 YAML 문서를 양방향으로 동기화합니다. YAML 창으로 전환하여 위의 hello-world YAML을 붙여넣거나, 팔레트에서 스텝 노드를 캔버스로 드래그하고 오른쪽 패널에서 각각 구성하세요.

   주의

   YAML 텍스트를 직접 수정한 경우, 저장하기 전에 그래프에 적용하세요. 저장은 그래프를 YAML로 직렬화하므로, 적용되지 않은 텍스트 편집은 저장되지 않습니다.

4. Save를 클릭하세요. 게이트웨이는 YAML을 유효성 검사합니다(중복 스텝 ID, 끊어진 의존성, 사이클, 스텝별 구성, 변수 참조, 트리거에 대한 6단계 검사). 성공하면 게시된 Kumiho 리비전을 생성하고 YAML에 선언된 cron 작업을 동기화합니다. 유효성 검사 오류는 인라인으로 표시되어 저장 전에 수정할 수 있습니다.

목록의 각 정의에는 source가 표시됩니다: builtin, builtin-modified, 또는 custom.

참고

내장 워크플로우는 편집하거나 삭제할 수 없으며, 복제만 가능합니다. Duplicate를 사용해 편집 가능한 복사본을 만드세요. 대시보드에서 저장하면 ~/.revka/workflows/{slug}.r{N}.yaml에 YAML이 디스크에도 저장되고 Kumiho 아티팩트가 등록됩니다. 이후 정의를 수정해도 이미 완료된 실행의 그래프는 소급하여 변경되지 않습니다 — 각 실행은 실행 당시의 리비전에 고정됩니다.

API로 생성하기

스크립팅을 선호한다면 YAML을 문자열로 POST하세요. 모든 워크플로우 라우트에는 페어링 베어러 토큰이 필요합니다(페어링 & 인증 참고).

POST /api/workflows
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "hello-world",
  "description": "A minimal two-step workflow.",
  "definition": "name: hello-world\nversion: \"1.0\"\nsteps:\n  - id: greet\n    type: agent\n    agent:\n      agent_type: claude\n      role: researcher\n      prompt: \"Say hello in three languages.\"\n",
  "version": "1.0",
  "tags": ["example"]
}

필드	필수 여부	의미
name	예	표시 이름; 항목 식별자로 슬러그화됩니다.
description	예	사람이 읽기 위한 설명.
definition	예	전체 워크플로우 YAML (문자열 형식).
version	아니요	시맨틱 버전 레이블.
tags	아니요	검색 및 필터링을 위한 분류 목록.

성공하면 게이트웨이가 유효성을 검사하고, 이름을 슬러그화하고, YAML을 workflow.yaml 아티팩트로 갖는 published 리비전을 작성한 뒤 201 Created를 반환합니다. 정의 CRUD 전체 엔드포인트는 워크플로우 & Architect API에서 확인하세요.

워크플로우 실행하기

대시보드 또는 API에서 실행을 시작할 수 있습니다.

Dashboard

Workflows 페이지에서 hello-world를 선택하고 Execute를 클릭하세요. 워크플로우에 inputs가 선언되어 있으면 먼저 값을 입력하라는 메시지가 표시됩니다. 실행은 Workflow Runs 페이지(/runs)에 표시되며, 각 스텝이 실시간으로 활성화되는 것을 볼 수 있습니다.

API

실행 엔드포인트에 POST하세요. 경로 세그먼트는 워크플로우 이름(kref가 아님)입니다.

POST /api/workflows/run/hello-world
Authorization: Bearer <token>
Content-Type: application/json

{
  "inputs": { "language": "Japanese" },
  "cwd": "/path/to/project"
}

필드	필수 여부	의미
inputs	아니요	워크플로우 입력 이름을 값에 매핑하는 객체.
cwd	아니요	셸 및 에이전트 스텝의 작업 디렉터리.
target_step_id	아니요	”여기까지 실행” — 이 스텝의 전이적 선행 스텝과 해당 스텝만 실행하고 중지합니다.

디스패치 전에 정의가 유효성 검사됩니다. 유효하지 않은 정의나 알 수 없는 target_step_id는 400을 반환합니다. 성공하면 실행 id가 반환됩니다.

{ "run_id": "<uuid>", "workflow": "hello-world", "status": "pending" }

실행은 다음 상태를 거칩니다.

상태	의미
pending	생성되었으나 executor가 아직 처리하지 않은 상태.
running	executor가 활성 상태로 실행 중.
paused	human_approval 또는 human_input 게이트에서 대기 중.
completed	모든 스텝이 성공적으로 완료됨.
failed	스텝이 실패함; 체크포인트가 보존되어 재시도 가능.
cancelled	사용자 또는 시스템에 의해 중지됨.
stale	체크포인트와 활성 잠금이 없는 비종료 상태 (예: 재배포로 로컬 상태가 초기화된 경우).

참고

각 스텝 후 상태는 ~/.revka/workflow_checkpoints/{run_id}.json에 체크포인트됩니다. 실행이 실패하면 체크포인트가 보존되므로 Retry는 첫 번째 실패한 스텝부터만 다시 실행합니다. 실행, 승인 & 체크포인트를 참고하세요.

출력 확인하기

대시보드에서

Workflow Runs 페이지(/runs)에서 해당 실행을 여세요. 실행 뷰어는 실행 당시의 정확한 YAML 리비전에 고정되므로, 그래프는 실제로 실행된 내용을 항상 반영합니다. 노드를 클릭하면 스텝 인스펙터가 열리며 스텝의 상태, 에이전트 id 및 역할, 출력 미리보기가 표시됩니다. hello-world 실행에서 summary 노드의 출력은 렌더링된 "Agent said: ..." 템플릿입니다.

API로 확인하기

실행 id로 실행 정보를 조회하세요.

GET /api/workflows/runs/{run_id}
Authorization: Bearer <token>

응답은 스텝별 세부 정보가 포함된 { "run": { ... } } 형식입니다. 진행 중인 실행은 executor의 인메모리 상태에서, 완료된 실행은 Kumiho 실행 레코드에서 조회됩니다. 알 수 없는 run_id는 404를 반환합니다. 실행 라이프사이클 엔드포인트(목록 조회, 재시도, 취소, 삭제, 승인)는 워크플로우 & Architect API에서 확인하세요.

팁

에이전트 스텝은 전체 텍스트 출력을 디스크에도 기록하며, 해당 경로를 ${greet.output_data.artifact_path}로 노출합니다. 이후 스텝에서 이전 단계의 전체 출력이 필요한 경우, ${greet.output}으로 전체 텍스트를 인라인하는 대신 아티팩트 경로를 가리키세요 — 이렇게 하면 다운스트림 프롬프트를 작게 유지할 수 있습니다.

다음 단계

워크플로우 YAML 레퍼런스 모든 최상위 필드와 스텝 옵션을 상세히 설명합니다.

스텝 타입 레퍼런스 agent, shell, python, conditional, parallel, output 등 각 스텝 타입을 설명합니다.

변수, 표현식 & 트리거 ${...} 네임스페이스, ${{ ... }} 평가자, cron/엔티티 트리거를 설명합니다.

실행, 승인 & 체크포인트 승인을 위한 일시 중지, 실패한 실행 재시도, 체크포인트 동작 방식을 설명합니다.

내장 워크플로우 & 패턴 기본 제공 템플릿과 멀티 에이전트 오케스트레이션 패턴을 설명합니다.

대시보드: 워크플로우, 편집기 & 실행 DAG/YAML 편집기, Architect, 실행 페이지를 심층적으로 설명합니다.