워크플로우 YAML 참조

Revka 워크플로우는 선언적 YAML 문서로, 의존성을 가진 타입별 스텝 집합과 선택적 트리거, 그리고 실행 기본값으로 구성됩니다. operator-mcp 백엔드는 Pydantic 스키마에 따라 YAML을 파싱하고, 6단계 유효성 검사를 실행한 뒤, 해당 정의를 Kumiho 그래프 메모리에 리비전으로 저장하고 결정론적으로 실행합니다.

이 페이지는 스텝별 설정 블록 상위에 있는 모든 요소에 대한 스키마 참조입니다. 최상위 필드, inputs/outputs/triggers 구조, 편집기에서 간결하게 스텝을 작성할 수 있게 해주는 action 축약형, 그리고 저장 및 실행마다 적용되는 유효성 검사기를 다룹니다. 각 스텝 타입의 본문은 스텝 타입 참조를 참조하십시오. ${...} 보간 및 ${{ ... }} 표현식은 변수, 표현식 & 트리거를 참조하십시오. 빠르게 시작하고 싶다면 첫 번째 워크플로우부터 시작하십시오.

최소 예시

유효한 워크플로우의 최소 구성은 name과 스텝 하나입니다.

name: hello-world
version: "1.0"
description: Greet a topic and return the text.
steps:
  - id: greet
    type: agent
    agent:
      agent_type: claude
      role: researcher
      prompt: "Say hello and introduce ${inputs.topic}."

타입이 지정된 입력, 명명된 출력, 트리거를 포함한 더 완전한 구조:

name: daily-report
version: "1.0"
description: Summarise a topic and publish the result.
tags: [reporting]

inputs:
  - name: topic
    type: string
    required: true
    default: ""

triggers:
  - cron: "0 9 * * 1"          # every Monday 09:00
    # timezone is set via the cron job, not the trigger block

steps:
  - id: summarize
    action: summarize          # shorthand → type: agent, role: summarizer, claude
    agent:
      prompt: "Summarise ${inputs.topic} in five bullet points."
      output_fields: [summary]

  - id: report
    type: output
    depends_on: [summarize]
    output:
      format: markdown
      template: |
        # ${inputs.topic}
        ${summarize.output}

outputs:
  - name: result
    source: "${report.output}"

최상위 스키마

다음 필드들은 문서 루트(WorkflowDef)에 위치합니다. name과 steps만 필수입니다.

필드	타입	기본값	설명
name	string	— (필수)	워크플로우 식별자. 게이트웨이가 표시 이름을 슬러그로 변환하여 Kumiho 아이템 id로 사용합니다.
version	string	"1.0"	자유 형식의 의미론적 버전 레이블.
description	string	""	사람이 읽을 수 있는 목적 설명. 대시보드 목록과 검색에 표시됩니다.
tags	list<string>	[]	검색 및 필터링을 위한 분류 레이블.
triggers	list<Trigger>	[]	워크플로우를 자동 실행하는 크론 또는 엔티티 이벤트 조건.
inputs	list<Input>	[]	실행 시 제공되는 타입별 파라미터.
outputs	list<Output>	[]	source를 통해 스텝 출력에서 매핑된 명명된 결과값.
steps	list<Step>	— (필수)	순서가 있는 스텝 정의. 하나 이상 필요합니다.
default_cwd	string	""	실행 시 cwd가 전달되지 않을 때 shell/agent 스텝의 기본 작업 디렉터리.
default_timeout	number	300.0	스텝별 기본 타임아웃(초).
max_total_time	number	3600.0	전체 실행 벽시계 시간의 안전 상한(초, 1시간).
checkpoint	bool	true	각 스텝 후 실행 상태를 유지하여 실패한 실행을 재시도할 수 있게 합니다. 실행, 승인 & 체크포인트를 참조하십시오.

참고

중복된 step.id 값은 유효성 검사 실행 전 파싱 단계에서 거부됩니다. step_by_id는 첫 번째 매칭을 반환하지만 편집기의 라운드트립은 마지막 매칭을 유지하기 때문에 둘이 불일치하게 됩니다. 워크플로우 내 모든 스텝 id는 고유해야 합니다.

Inputs

inputs의 각 항목은 타입이 지정된 파라미터입니다. 실행 시 트리거 호출의 inputs 객체를 통해 값이 제공되며, 제공되지 않은 경우 default로 대체됩니다.

inputs:
  - name: topic
    type: string          # string | number | boolean | list
    required: true
    default: ""
    description: "What to summarise."

필드	타입	기본값	설명
name	string	—	파라미터 이름. ${inputs.<name>}으로 참조합니다.
type	enum	string	string, number, boolean, list 중 하나.
required	bool	true	실행 시 값이 반드시 있어야 하는지 여부.
default	any	null	값이 제공되지 않을 때의 대체값.
description	string	""	편집기에 표시되는 설명.

default가 없는 필수 입력은 실행 시 반드시 제공해야 합니다. 워크플로우에 해당 입력을 매핑하지 않는 트리거가 있는 경우, 유효성 검사기는 경고(advisory warning)를 발생시킵니다. 이 경우에도 업스트림 엔티티 메타데이터에서 자동으로 채워질 수 있습니다.

Outputs

outputs는 ${...} source 표현식을 통해 이름을 스텝 결과에 매핑하여, 호출자와 다운스트림 워크플로우에 안정적인 계약을 제공합니다.

outputs:
  - name: result
    source: "${report.output}"
  - name: next_episode
    source: "${{ int(resolve_cursor.output_data.episode_number) + 1 }}"
    description: "Computed cursor for the next run."

필드	타입	기본값	설명
name	string	—	출력 이름.
source	string	—	실행 종료 시 평가되는 ${...} 또는 ${{ ... }} 표현식.
description	string	""	설명.

Triggers

트리거는 워크플로우를 자동으로 실행합니다. 하나의 구조체(TriggerDef) 내에 두 가지 형태가 있습니다. 시간 기반 트리거에는 cron을, 엔티티 이벤트 트리거에는 on_kind를 설정합니다. cron 트리거가 포함된 정의를 저장하면 크론 잡이 자동으로 등록되며, 비활성화하거나 삭제하면 제거됩니다.

triggers:
  # Time-based
  - cron: "0 9 * * 1"

  # Entity-event: fire when an upstream output step publishes a matching entity
  - on_kind: "qs-arc-plan"          # entity kind to watch (exact match)
    on_tag: "ready"                  # revision tag that fires the trigger
    on_name_pattern: "qs-*"          # optional glob on entity name
    on_space: "Revka/WorkflowOutputs/QuantumSoul"  # optional space prefix
    input_map:                       # map trigger data → workflow inputs
      arc_kref: "${trigger.entity_kref}"
      arc_name: "${trigger.metadata.arc_name}"

필드	타입	기본값	설명
cron	string	""	시간 기반 트리거의 크론 표현식. 설정 시 엔티티 필드는 선택 사항입니다.
on_kind	string	""	감시할 엔티티 종류(정확히 일치). 이벤트 트리거에 필수입니다.
on_tag	string	"ready"	트리거를 발생시키는 리비전 태그(정확히 일치).
on_name_pattern	string	""	엔티티 이름에 대한 선택적 글로브("" = 모두).
on_space	string	""	선택적 공간 경로 접두사 필터("" = 모두).
input_map	map<string,string>	{}	워크플로우 입력 이름을 ${trigger.*} 템플릿에 매핑합니다.

이벤트 트리거 필터는 누적 적용됩니다(AND). input_map이 생략되면, 트리거 엔티티의 메타데이터 키가 일치하는 워크플로우 입력 이름에 자동으로 매핑됩니다. 체이닝 패턴을 포함한 전체 동작 방식은 변수, 표현식 & 트리거에서 확인하십시오.

스텝

각 스텝은 공통 외부 구조(StepDef)와 type에 따라 명명된 타입별 설정 블록 하나를 가집니다. 모든 스텝 타입의 본문은 스텝 타입 참조에 문서화되어 있으며, 아래의 외부 구조 필드는 모든 스텝에 적용됩니다.

steps:
  - id: research               # unique within the workflow (required)
    name: "Research phase"     # display label; defaults to id
    type: agent                # the step type (or omit and use `action`)
    depends_on: [resolve_topic]
    skills:
      - "kref://CognitiveMemory/Skills/some-skill.skilldef"
    retry: 1                   # retry up to N times after the first attempt
    retry_delay: 10            # seconds between retries
    timeout: 600               # step-level override, pushed into the type config
    agent:
      prompt: "..."

필드	타입	기본값	설명
id	string	— (필수)	고유 스텝 식별자. ${id.output}으로 참조합니다.
name	string	id	대시보드 그래프에 표시되는 레이블.
type	enum	agent	스텝 타입 중 하나. action이 설정된 경우 생략 가능합니다.
depends_on	list<string>	[]	먼저 완료되어야 하는 스텝 id. depends_on이 없는 형제 스텝은 자연스럽게 병렬로 실행됩니다.
action	string	""	type과 에이전트 기본값을 추론하는 축약형.
agent_hints	list<string>	[]	action이 선택한 에이전트 타입/역할을 재정의합니다(예: [codex]).
skills	list<string>	[]	에이전트 스텝에 주입되는 스킬 kref.
assign	string	""	사전 할당된 에이전트 풀 템플릿. agent.template이 설정되지 않은 경우 연결됩니다.
description	string	""	action 스텝에 명시적 agent.prompt가 없을 때 프롬프트로 사용됩니다.
compression	bool	false	대용량 출력을 다운스트림 스텝에 전달하기 전에 압축합니다.
retry	int (0–5)	0	첫 번째 실패 후 재시도 횟수.
retry_delay	number	5.0	재시도 사이의 대기 시간(초).
timeout	number	상속	스텝 수준 타임아웃. agent/shell/python/email/image/a2a/group_chat 설정에 전달됩니다.

주의

depends_on에 id를 나열한 에이전트 스텝은 실제로 해당 의존성을 사용해야 합니다. agent.prompt에서 ${<dep>.output_data.artifact_path}(전체 컨텍스트에 권장) 또는 다른 ${<dep>.*} 필드를 참조해야 합니다. 그렇지 않으면 런타임이 업스트림 콘텐츠 없이 에이전트를 시작하므로 유효성 검사기가 이를 거부합니다. 프롬프트에서 의존성을 참조하거나, 순서 지정만 필요한 경우 depends_on에서 제거하십시오. 에이전트가 아닌 스텝은 순서 지정 목적으로만 depends_on을 사용할 수 있습니다.

스텝 타입

type 필드는 다음 값을 허용합니다(StepType). 각각 동일한 이름의 설정 블록에 매핑됩니다.

카테고리	타입
에이전트 & 코드	agent, shell, python, compute, image
커뮤니케이션	email, notify, human_approval, human_input
흐름 제어	conditional, parallel, goto, for_each
출력 & 데이터	output, resolve, tag, deprecate
Kumiho 그래프	kumiho_context, kumiho_bundle_update, kumiho_patch_apply
오케스트레이션	map_reduce, supervisor, group_chat, handoff
외부	a2a, manus

각 타입의 필드는 스텝 타입 참조를 참조하십시오.

액션 축약형

편집기와 직접 작성한 워크플로우에서 action을 설정하면 type과 에이전트 블록을 생략할 수 있습니다. 스키마는 각 액션 이름을 스텝 타입에 매핑하고, 에이전트 액션의 경우 기본 역할과 에이전트 타입도 제공합니다. agent: 블록을 추가하여 프롬프트와 다른 필드를 재정의할 수 있으며, agent_hints로 에이전트 타입을 재정의할 수 있습니다.

# Terse form
- id: research
  action: research            # → type: agent, role: researcher, agent_type: claude
  agent_hints: [codex]        # override: run on codex instead of claude
  description: "Research the competitive landscape."

# Equivalent explicit form
- id: research
  type: agent
  agent:
    agent_type: codex
    role: researcher
    prompt: "Research the competitive landscape."

전체 ACTION_DEFAULTS 매핑:

액션	스텝 타입	역할	에이전트 타입
research	agent	researcher	claude
code	agent	coder	codex
review	agent	reviewer	claude
deploy	agent	deployer	codex
test	agent	tester	codex
build	agent	builder	codex
summarize	agent	summarizer	claude
task	agent	coder	claude
notify	notify	—	—
approve	human_approval	—	—
gate	conditional	—	—
human_input	human_input	—	—
resolve	resolve	—	—
compute	compute	—	—
kumiho_context	kumiho_context	—	—
kumiho_bundle_update	kumiho_bundle_update	—	—
kumiho_patch_apply	kumiho_patch_apply	—	—

해석 방식:

• type 생략, action 설정 → type이 표에서 추론됩니다.
• type이 액션 별칭으로 설정된 경우(예: type: notify) → 실제 스텝 타입으로 확장되고(notify → notify; 에이전트 별칭 → agent), 원래 값이 action으로 기록됩니다.
• 에이전트 액션에 agent 블록이 없는 경우 → 액션의 역할과 에이전트 타입으로 기본 AgentStepConfig가 합성되며, description(또는 Execute <action> task: <name>)이 프롬프트로 사용됩니다.
• agent_hints 는 합성된 에이전트 타입을 재정의합니다. codex/coder → codex; claude/researcher/reviewer → claude. coder, researcher, reviewer 힌트는 역할도 설정합니다. 알 수 없는 액션 이름이 사용된 경우 task가 대체 액션으로 사용됩니다.

참고

편집기는 레거시 플랫 조건부 구문(condition + 스텝 레벨의 on_true/on_false)도 허용합니다. 스키마가 로드 시 이를 표준적인 conditional.branches 형태로 재작성하므로, 두 형태 모두 읽을 수 있지만 중첩 형태로 작성하는 것을 권장합니다.

워크플로우 유효성 검사 (6단계)

정의가 저장되거나 실행되기 전에 operator의 validate_workflow가 일련의 구조적 단계를 실행하고 { valid, errors, warnings, execution_order, all_step_ids }를 반환합니다. error가 하나라도 있으면 정의가 유효하지 않으며, warning은 참고용이며 저장을 차단하지 않습니다.

1. 스텝 ID 중복 — 모든 step.id는 고유해야 합니다. (완전한 중복은 파싱 단계에서 이미 거부되지만, 이 단계에서도 구조화된 결과에 보고됩니다.)

2. 의존성 참조 — 모든 depends_on 항목은 기존 스텝을 참조해야 합니다. 알 수 없는 참조는 오류이며, 다음 단계의 인접 맵을 구성하는 데 사용됩니다.

3. 순환 감지 — depends_on에 대한 깊이 우선 위상 정렬. 역방향 엣지는 Dependency cycle detected 오류입니다. 결과 위상 순서가 execution_order가 됩니다(parallel/for_each 래퍼의 자식 스텝은 중복 실행을 방지하기 위해 제외됩니다).

4. 스텝별 설정 — 타입별 검사. 예를 들어, shell은 command가 필요하고, image와 map_reduce/supervisor/group_chat는 필수 필드가 있으며, conditional 분기와 goto/handoff 대상은 실제 스텝(또는 end)을 가리켜야 하고, parallel은 존재하며 상호 의존하지 않는 2개 이상의 하위 스텝이 필요하고, output은 어느 하나라도 설정된 경우 entity_name과 entity_kind 모두 필요하며, agent.output_fields는 유효하고 예약되지 않은 식별자여야 합니다.

5. 변수 참조 — 모든 보간 가능한 문자열에서 ${...} 및 ${{ ... }} 참조를 스캔합니다. 내장 네임스페이스(inputs, loop, env, trigger, for_each, previous, outputs, run_id, rejection)는 허용됩니다. 알 수 없는 스텝 id인 다른 선행 네임스페이스는 오류가 아닌 경고를 생성하므로, 아직 생성되지 않은 데이터를 참조하는 첫 번째 실행 패턴도 저장할 수 있습니다.

6. 에이전트 의존성 & 계약 검사 — 두 가지 세밀한 에이전트 단계: depends_on 항목이 프롬프트에서 한 번도 참조되지 않은 에이전트 스텝은 오류입니다(위의 주의 사항 참조). output_fields에 <field>를 선언하지 않은 에이전트 스텝에 대한 ${X.output_data.<field>} 참조는 경고입니다.

7. 트리거 — 각 트리거는 유효해야 합니다. 비 크론 트리거는 on_kind와 on_tag가 필요하며, 트리거가 매핑하지 않는 필수 입력이 있는 워크플로우는 경고를 생성합니다(엔티티 메타데이터에서 자동으로 채워질 수 있습니다).

유효성 검사 실행 위치

• 대시보드 — 저장 시 자동으로 유효성을 검사하며, 오류는 편집기에 인라인으로 표시됩니다. 워크플로우, 편집기 & 실행을 참조하십시오.
• 게이트웨이 API — POST /api/workflows, PUT /api/workflows/{*kref}, POST /api/workflows/run/{name}은 저장 또는 디스패치 전에 유효성을 검사하고, 실패 시 400을 반환합니다.
• Operator MCP — validate_workflow 및 dry_run_workflow 도구를 사용하면 에이전트 또는 Architect 패널이 저장 없이 정의를 확인할 수 있습니다.

게이트웨이는 고정된 타임아웃으로 operator의 유효성 검사기를 호출합니다. 인프라 오류로 인해 유효성 검사를 실행할 수 없는 경우(operator에 일시적으로 접근 불가), 저장을 차단하는 대신 건너뜁니다(fail-open). 전체 HTTP 동작은 워크플로우 & Architect API에서 확인하십시오.

실패 응답 구조

정의에 대한 POST/PUT 및 POST /api/workflows/run/{name}은 다음과 같이 400을 반환합니다.

{
  "error": "Workflow validation failed: ...",
  "valid": false,
  "errors": [
    { "message": "depends_on references unknown step 'reserch'", "severity": "error", "step_id": "report", "field": "depends_on" }
  ],
  "warnings": [
    { "message": "Variable reference '${draft.output}' — step 'draft' not found", "severity": "warning", "step_id": "report" }
  ]
}

각 항목은 message와 severity(error 또는 warning), 그리고 문제 위치를 나타내는 선택적 step_id와 field를 포함합니다.

Operator 도구: 선언적 워크플로우 엔진

워크플로우는 operator-mcp 엔진에 의해 실행됩니다. 이 엔진은 전체 생명주기를 에이전트와 대시보드가 호출하는 MCP 도구로 제공합니다. 유효성 검사 도구는 작성 중에 주로 사용하며, 나머지는 워크플로우를 실행하고 관리합니다. 백엔드 연결 방식은 Operator MCP를 참조하십시오.

validate_workflow

실행이나 저장 없이 6단계 유효성 검사기를 실행합니다. 워크플로우를 이름, 인라인 정의, 또는 원시 YAML로 받아 ValidationResult(valid, errors, warnings)를 반환합니다.

validate_workflow(
  workflow?,        # name of a stored/builtin workflow
  workflow_def?,    # inline definition object
  workflow_yaml?,   # raw YAML string
  cwd?,             # working directory for discovery
)
→ { "valid": true, "errors": [], "warnings": [ ... ] }

저장 전에 초안을 린트할 때 사용합니다. 게이트웨이의 POST /api/architect/validate_yaml 경로는 시각적 편집기의 채팅 대체 경로를 위한 관련 propose_workflow_yaml 도구의 얇은 래퍼입니다.

dry_run_workflow

유효성 검사와 함께 스텝을 실제로 실행하지 않고 실행을 미리 봅니다. 계획된 실행 순서, 스텝 수, 비용 추정치를 보고합니다. 실제 실행 전에 워크플로우가 대략 예상대로 동작하는지, 그리고 비용이 어느 정도인지 확인할 때 사용합니다.

dry_run_workflow(
  workflow?,        # name of a stored/builtin workflow
  workflow_def?,    # inline definition object
  inputs?,          # input values to plan against
  cwd?,
)
→ preview of execution order, step count, and estimated cost

기타 생명주기 도구

도구	목적
run_workflow(workflow, inputs, cwd, run_id?, max_cost_usd?)	이름 또는 인라인 정의로 실행합니다. max_cost_usd는 비용 상한 초과 시 실행을 중단합니다.
list_workflows(cwd?, tag?)	내장, 사용자, 프로젝트 로컬 워크플로우를 나열합니다. 태그로 필터링 가능합니다.
get_workflow_status(run_id, include_outputs?)	실행 중이거나 완료된 실행의 스텝별 결과.
cancel_workflow(run_id)	다음 스텝 경계에서 실행 중이거나 일시 정지된 실행을 취소합니다.
resume_workflow(run_id, approved?, cwd?)	human_approval 스텝 후 실행을 재개합니다.
retry_workflow(run_id, cwd?)	첫 번째 실패 스텝부터 재시도합니다. 성공한 스텝은 유지됩니다.
create_workflow(workflow_def, directory?)	YAML을 생성하고 ~/.revka/workflows/에 저장합니다.
revise_workflow(workflow_kref, operations, rationale?)	구조화된 추가/편집/삭제/재정렬/연결 작업을 적용하여 새 리비전을 생성합니다.
propose_workflow_yaml(proposed_yaml, intent_summary?, base_yaml?)	Architect 전용: 저장 없이 유효성 검사 + 비교. 시각적 편집기를 지원합니다.
get_workflow_metadata(include?)	사용 가능한 스텝 타입, 풀 에이전트, 인증 프로필, 스킬, 채널.
recall_workflow_runs(workflow?, limit?) / get_workflow_run_detail(run_id)	Kumiho 메모리의 최근 실행 및 스텝별 상세 정보.

참고

스키마가 허용하는 agent_type 값 — claude, codex, agy, agent, opencode — 이 각 에이전트 스텝을 생성합니다. agent.tools의 기본값은 none(MCP 도구 주입 없음)이고 agent.max_turns의 기본값은 3이므로, 명시적으로 설정하지 않으면 에이전트 스텝은 도구를 반복 사용하지 않습니다. 실제로 도구 사용이 필요한 스텝에서는 두 값을 모두 높이십시오.

파일 검색 & 저장

워크플로우는 디스크 또는 Kumiho에 저장될 수 있습니다. operator는 다음 위치를 스캔하며, 이름이 충돌하면 나중 소스가 우선합니다.

우선순위	위치	목적
최고	.revka/workflows/ (프로젝트 로컬)	프로젝트별 재정의.
	~/.revka/workflows/ (사용자)	사용자 전역 워크플로우.
최저	operator_mcp/workflow/builtins/	기본 제공 기본값(내장 워크플로우 & 패턴 참조).
대체	Kumiho space Revka/Workflows	클라우드 관리 정의.

대시보드나 API에서 저장하면 정의가 Revka/Workflows 공간의 workflow 종류 Kumiho 아이템으로 저장됩니다. YAML 자체는 workflow.yaml 리비전 아티팩트로 작성됩니다(Kumiho의 크기 제한을 유지하기 위해 인라인 메타데이터가 아닌 방식). 대시보드는 YAML을 ~/.revka/workflows/{slug}.r{N}.yaml에도 작성합니다. 디렉터리 스캐너는 기본 {slug}.yaml을 처리하고, .r{N}.yaml 리비전 파일은 kref 해석을 통해서만 접근합니다. 저장할 때마다 새 리비전이 작성되고 published로 태그가 지정되므로, 각 실행은 실행한 정확한 YAML에 고정될 수 있습니다.

참고

디스크와 Kumiho 간의 name 충돌은 위의 우선순위 순서로 해결됩니다. 정의를 편집해도 진행 중이거나 이전 실행의 그래프는 변경되지 않습니다. 해당 실행들은 실행한 리비전에 고정된 상태를 유지합니다.

관련 페이지

스텝 타입 참조 agent, shell, conditional, parallel, output 등 모든 스텝 타입의 전체 설정 블록.

변수, 표현식 & 트리거 ${...} 네임스페이스, ${{ ... }} 표현식 평가기, 크론/엔티티 트리거.

실행, 승인 & 체크포인트 실행 상태, 재시도, 체크포인트, 사람 승인 게이트.

워크플로우 & Architect API 이 정의를 저장, 유효성 검사, 실행, 수정하는 HTTP 인터페이스.

내장 워크플로우 & 패턴 학습에 활용할 수 있는 기본 제공 워크플로우 템플릿과 오케스트레이션 패턴.

Operator MCP 워크플로우 YAML을 파싱, 유효성 검사, 실행하는 Python 백엔드.