스텝 타입 참조

워크플로우의 모든 스텝 타입: agent, shell, python, email, notify, resolve, conditional, parallel, goto, output, approvals, a2a, 그리고 오케스트레이션 패턴.

Revka 워크플로우는 스텝의 순서 있는 목록으로 구성됩니다. 각 스텝은 공통 엔벨로프(id, depends_on, retry, timeout 등, 나머지는 워크플로우 YAML 참조에서 확인)를 공유하며, type에 해당하는 이름의 타입별 설정 블록을 정확히 하나 포함합니다. 이 페이지는 해당 설정 블록에 대한 참조 문서로, 각 스텝 타입의 동작 방식, 필드 목록, 그리고 바로 사용 가능한 예제를 제공합니다.

스텝 본문을 작성할 때 사용 가능한 키를 확인하려면 이 페이지를 참조하십시오. 최상위 스키마, action 단축 표기, 검증기에 대한 내용은 YAML 참조를 확인하십시오. 이 필드들에서 사용하는 ${...} 보간과 ${{ ... }} 표현식은 변수, 표현식 & 트리거를 참조하십시오. 처음 시작하는 경우 첫 번째 워크플로우 만들기부터 시작하십시오.

스텝 타입 한눈에 보기

type 필드에는 다음 값을 사용할 수 있습니다. 각 값은 동일한 이름의 설정 블록에 매핑됩니다.

카테고리	타입
에이전트 & 코드	`agent`, `shell`, `python`
커뮤니케이션	`email`, `notify`, `human_approval`, `human_input`
제어 흐름	`conditional`, `parallel`, `goto`
출력 & 데이터	`output`, `resolve`
외부	`a2a`
오케스트레이션	`map_reduce`, `supervisor`, `group_chat`, `handoff`

`agent`

LLM 에이전트를 생성하여 프롬프트를 실행하고, 선택적으로 도구를 사용하며 텍스트를 반환합니다. 가장 핵심적인 스텝 타입입니다. 에이전트는 claude 또는 codex 백엔드를 사용할 수 있으며, 출력을 자유 형식으로 캡처하거나 엄격한 구조화 출력 계약으로 제한할 수 있습니다.

- id: research
  type: agent
  depends_on: []
  agent:
    agent_type: claude          # claude or codex
    role: researcher            # coder, researcher, reviewer, tester, etc.
    prompt: |
      Research ${inputs.topic} and summarize the findings.
    output_fields: [summary, score]   # optional structured-output contract
    model: null                 # optional model override
    timeout: 300                # seconds
    template: my-template       # optional agent pool template
  skills:
    - "kref://CognitiveMemory/Skills/some-skill.skilldef"
  retry: 1                      # retry once on failure
  retry_delay: 10               # seconds between retries

필드	타입	기본값	설명
`agent_type`	enum	`claude`	에이전트 백엔드: `claude` 또는 `codex`.
`role`	string	—	에이전트 페르소나(`coder`, `researcher`, `reviewer`, `tester` 등).
`prompt`	string	—	LLM 프롬프트. `${...}` 보간을 지원합니다.
`output_fields`	list<string>	`[]`	설정 시, 필수 구조화 출력 필드를 선언합니다.
`model`	string	`null`	선택적 모델 재정의.
`timeout`	number	`300`	실행 제한 시간(초).
`template`	string	—	상속할 에이전트 풀 템플릿 이름.

skills, retry, retry_delay는 agent 블록이 아닌 공유 스텝 엔벨로프의 일부입니다.

Agent 구조화 출력 & `output_fields`

agent.output_fields를 설정하면 실행기는 프롬프트에 구조화 출력 지침을 추가하고, 선언된 모든 필드가 응답에 포함될 것을 요구합니다. 누락된 필드가 있으면 structured_output_missing 오류와 함께 스텝이 실패합니다. 이를 통해 에이전트를 분기 가능한 타입 함수로 활용할 수 있습니다.

- id: auditor
  type: agent
  agent:
    role: reviewer
    prompt: "Review canon consistency and report a verdict."
    output_fields: [verdict, production_ready]

에이전트는 다음 세 가지 형식 중 하나로 계약을 충족할 수 있습니다:

전체 JSON 객체 — {"verdict":"APPROVED","production_ready":true}
펜스 JSON 블록 — 객체를 포함하는 ```json 코드 블록
FINAL_OUTPUT: 블록 — FINAL_OUTPUT:으로 시작하는 후행 YAML 블록

파싱된 필드는 다운스트림에서 ${auditor.output_data.verdict}로 참조하거나, 표현식 내에서 auditor.output_data.verdict로 사용할 수 있습니다:

- id: gate
  type: conditional
  depends_on: [auditor]
  conditional:
    branches:
      - condition: "${{ auditor.output_data.production_ready == true }}"
        goto: publish
      - condition: default
        goto: fix

`shell`

서브프로세스에서 셸 명령을 실행합니다. 종료 코드가 성공 여부를 결정하며, allow_failure를 설정하지 않은 경우 0이 아닌 종료 코드는 스텝 실패로 처리됩니다.

- id: build
  type: shell
  shell:
    command: "cd ${inputs.project_dir} && npm run build"
    timeout: 60
    allow_failure: false        # true = a non-zero exit doesn't fail the workflow

필드	타입	기본값	설명
`command`	string	— (필수)	실행할 명령. `${...}` 보간을 지원합니다.
`timeout`	number	상속	제한 시간(초).
`allow_failure`	bool	`false`	`true`로 설정 시, 0이 아닌 종료 코드가 스텝을 실패시키지 않습니다.

`python`

Python 스크립트 파일 또는 인라인 Python 코드를 실행합니다. 인자는 워크플로우 상태에서 해석된 키워드 인수로 전달됩니다.

- id: transform
  type: python
  python:
    script: "scripts/transform.py"   # or use `code:` for inline Python
    args:
      topic: "${inputs.topic}"
    timeout: 60

필드	타입	기본값	설명
`script`	string	—	Python 스크립트 파일 경로.
`code`	string	—	인라인 Python 소스 코드(`script` 대신 사용).
`args`	map	`{}`	키/값 쌍으로 키워드 인수로 전달됩니다. 값은 `${...}`를 지원합니다.
`timeout`	number	상속	제한 시간(초).

script와 code 중 하나만 지정하십시오. 둘 다 지정할 수 없습니다.

`email`

설정된 이메일 제공자를 통해 SMTP로 발신 이메일을 전송합니다. dry_run: true로 설정하면 실제 발송 없이 메시지를 렌더링하고 로깅합니다 — 테스트 시 유용합니다.

- id: outreach
  type: email
  email:
    to: "[email protected]"
    subject: "Revka report"
    body: "${report.output}"
    dry_run: true

필드	타입	기본값	설명
`to`	string	—	수신자 주소.
`subject`	string	—	제목 줄. `${...}`를 지원합니다.
`body`	string	—	메시지 본문. `${...}`를 지원합니다.
`dry_run`	bool	`false`	`true`로 설정 시, 메시지를 렌더링하고 로깅하지만 전송하지 않습니다.

이메일 제공자 설정은 이메일, iMessage, Linq & 자동화를 참조하십시오.

`notify`

하나 이상의 채널에 비차단 알림을 전송하고 즉시 계속 진행합니다 — 워크플로우를 절대 일시 중지하지 않습니다. 진행 상황 알림에 사용하고, 실제로 대기가 필요한 경우에는 human_approval 또는 human_input을 사용하십시오.

- id: heads_up
  type: notify
  notify:
    channels: [dashboard, slack]
    title: "Workflow update"
    message: "Run ${run_id} completed."

필드	타입	기본값	설명
`channels`	list<string>	—	전달할 채널 이름 목록(예: `dashboard`, `slack`).
`title`	string	—	알림 제목.
`message`	string	—	알림 본문. `${...}`를 지원합니다.

사용 가능한 채널 이름은 채널 개요를 참조하십시오.

`resolve`

LLM 호출 없이 kind, tag, 선택적 필터로 Kumiho 엔티티를 조회합니다. agent 스텝의 결정론적 대응 타입으로, 이전 실행 상태(다중 실행 연속성에 활용) 조회나 의존성 엔티티 주입에 사용됩니다.

- id: resolve_cursor
  type: resolve
  resolve:
    kind: "qs-episode-final"    # entity kind (exact match)
    tag: "published"            # revision tag (exact match)
    name_pattern: ""            # optional glob on entity name
    space: ""                   # space path filter (default: Revka/WorkflowOutputs)
    mode: latest                # latest = single newest | all = list
    metadata_source: revision   # revision | item | artifact
    fields: [part, episode_number]   # metadata fields to extract (empty = all)
    fail_if_missing: false      # false = don't fail if nothing is found

필드	타입	기본값	설명
`kind`	string	—	일치시킬 엔티티 kind(정확히 일치). 엔티티 매칭에 필수.
`tag`	string	`"ready"`	일치시킬 리비전 태그(정확히 일치).
`name_pattern`	string	`""`	엔티티 이름에 대한 선택적 글로브 필터.
`space`	string	`Revka/WorkflowOutputs`	선택적 공간 경로 접두사 필터.
`mode`	enum	`latest`	`latest`는 가장 최신 단일 결과를 반환하고, `all`은 목록을 반환합니다.
`metadata_source`	enum	`revision`	메타데이터를 읽을 위치: `revision`, `item`, 또는 `artifact`.
`fields`	list<string>	`[]`	추출할 특정 메타데이터 필드. 비어 있으면 전체를 반환합니다.
`fail_if_missing`	bool	`false`	`true`로 설정 시, 일치 항목이 없으면 스텝이 실패합니다.

출력 데이터: found, item_kref, revision_kref, name, metadata_source, 그리고 fields의 각 필드에 대한 항목(예: ${resolve_cursor.output_data.episode_number}).

`conditional`

스텝 출력에 대해 불리언 표현식을 평가하고 대상 스텝으로 실행을 라우팅합니다. 브랜치는 순서대로 확인되며, 첫 번째 일치 항목이 선택됩니다. default 브랜치를 catch-all로 사용하십시오.

- id: gate
  type: conditional
  depends_on: [review]
  conditional:
    branches:
      - condition: "${review.output} contains APPROVED"
        goto: publish
      - condition: "${review.status} == 'failed'"
        goto: fix
      - condition: default        # catch-all
        goto: fix

필드	타입	설명
`branches`	list	`{condition, goto, value?}` 항목의 순서 있는 목록.
`branches[].condition`	string	평가할 표현식, 또는 리터럴 `default`.
`branches[].goto`	string	이동할 스텝 id, 또는 실행을 종료하는 `"end"`.
`branches[].value`	string	일치한 브랜치와 함께 기록될 선택적 값 표현식.

condition에서 지원하는 연산자: ==, !=, contains, >, <, >=, <=. 더 복잡한 로직은 ${{ ... }} 표현식을 사용하십시오 — 변수, 표현식 & 트리거 참조.

실행 출력 필드: 완료된 conditional 스텝은 matched_branch_index, matched_branch_label, matched_goto, matched_condition, matched_value_expr, matched_output을 기록합니다. 대시보드 그래프와 스텝 인스펙터는 일치한 브랜치와 대상을 표시합니다. 브랜치 goto 대상은 실제 스텝(또는 end)을 가리켜야 하며, 검증기가 이를 확인합니다.

`parallel`

여러 스텝을 동시에 실행하고 설정 가능한 전략으로 합류합니다. 명명된 하위 스텝은 이 래퍼가 소유하며, 정상적인 최상위 실행 순서에서 제외되어 별도로 실행되지 않습니다.

- id: fan_out
  type: parallel
  parallel:
    steps: [step_a, step_b, step_c]
    join: all                   # all | any | majority
    max_concurrency: 5          # 1-10

필드	타입	기본값	설명
`steps`	list<string>	—	병렬로 실행할 스텝 id 목록(상호 의존하지 않는 기존 스텝 2개 이상).
`join`	enum	`all`	`all`은 모든 스텝을 기다리고 하나라도 실패하면 실패; `any`는 첫 번째 성공 시 반환; `majority`는 50% 초과 성공이 필요.
`max_concurrency`	int (1–10)	`5`	최대 동시 하위 스텝 수.

`goto`

이전 스텝으로 돌아가 반복 루프를 구현하며, 안전을 위한 상한이 있습니다. condition이 참이고 반복 횟수가 max_iterations 미만인 경우에만 점프가 발생합니다.

- id: retry_loop
  type: goto
  depends_on: [check_quality]
  goto:
    target: improve             # step id to jump back to
    condition: "${check_quality.output} contains NEEDS_WORK"
    max_iterations: 3           # safety cap (1-20)

필드	타입	기본값	설명
`target`	string	—	돌아갈 스텝 id(존재해야 함).
`condition`	string	—	루프를 계속하려면 참이어야 하는 표현식.
`max_iterations`	int (1–20)	—	무한 실행 방지를 위한 루프 상한.

현재 루프 횟수는 루프 본문 내에서 ${loop.iteration}으로 참조할 수 있습니다.

`output`

템플릿을 렌더링하고 선택적으로 결과를 Kumiho 엔티티로 게시합니다. 게시 시 리비전에 태그가 지정되며, 이는 revision.tagged 이벤트를 발생시켜 다운스트림 워크플로우를 트리거합니다 — 워크플로우 체이닝이 작동하는 방식입니다.

- id: report
  type: output
  depends_on: [analyze]
  output:
    format: markdown            # text | json | markdown
    template: |
      # Analysis Report
      ${analyze.output}
    entity_name: "analysis-${inputs.topic}"
    entity_kind: "analysis-report"
    entity_tag: "ready"
    entity_space: "Revka/WorkflowOutputs"
    metadata_target: item       # item | revision | artifact
    entity_metadata:
      topic: "${inputs.topic}"
      summary: "${analyze.output}"

필드	타입	기본값	설명
`format`	enum	`text`	렌더 형식: `text`, `json`, 또는 `markdown`.
`template`	string	—	렌더링할 콘텐츠. `${...}`를 지원합니다.
`entity_name`	string	—	엔티티 이름. `entity_name` + `entity_kind`(+`entity_tag`)를 설정하면 게시됩니다.
`entity_kind`	string	—	다운스트림 resolve/트리거 매칭에 사용할 엔티티 kind.
`entity_tag`	string	—	게시 시 적용할 리비전 태그.
`entity_space`	string	`Revka/WorkflowOutputs`	게시할 Kumiho 공간 경로.
`metadata_target`	enum	`item`	`entity_metadata`가 기록될 위치: `item`, `revision`, 또는 `artifact`.
`entity_metadata`	map	`{}`	키/값 메타데이터. `${...}`를 지원합니다.

출력 데이터: entity_kref, entity_revision_kref.

`human_approval`

워크플로우를 일시 중지하고 운영자의 승인 또는 거부를 기다립니다. 일시 중지 전에 체크포인트가 기록되므로 재시작 후에도 실행이 유지됩니다. 이는 표준적인 human-in-the-loop 게이트입니다.

- id: approve
  type: human_approval
  human_approval:
    message: "Deploy to production?"
    timeout: 3600               # seconds (1 hour)

필드	타입	설명
`message`	string	승인자에게 표시할 프롬프트.
`timeout`	number	게이트 타임아웃까지 대기할 시간(초).

실행은 paused 상태로 일시 중지됩니다. 대시보드, 채널, 또는 API를 통해 해결할 수 있습니다:

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

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

`human_input`

워크플로우를 일시 중지하고 운영자의 자유 형식 텍스트 응답을 기다립니다. 응답은 다운스트림에서 ${ask_user.output}으로 참조할 수 있어, 이후 프롬프트에 사람의 지침을 반영할 수 있습니다.

- id: ask_user
  type: human_input
  human_input:
    message: "What changes do you want?"
    channel: dashboard
    timeout: 3600

필드	타입	설명
`message`	string	운영자에게 표시할 질문.
`channel`	string	질문을 보낼 채널(예: `dashboard`).
`timeout`	number	응답 대기 시간(초).

`a2a`

A2A(agent-to-agent) 프로토콜을 사용하여 HTTP로 외부 에이전트를 호출합니다. 원격 에이전트가 작업을 수행하고 결과를 반환하면, 이것이 이 스텝의 출력이 됩니다.

- id: external
  type: a2a
  a2a:
    url: "https://agent.example.com/a2a"
    skill_id: "analyze-data"
    message: "Analyze: ${inputs.data}"
    timeout: 300

필드	타입	기본값	설명
`url`	string	—	외부 에이전트의 A2A 엔드포인트.
`skill_id`	string	—	원격 에이전트에서 호출할 스킬.
`message`	string	—	작업 메시지. `${...}`를 지원합니다.
`timeout`	number	상속	제한 시간(초).

오케스트레이션 패턴

네 가지 고수준 스텝 타입은 에이전트와 조건문을 직접 연결하는 대신, 하나의 스텝에서 여러 에이전트를 조율합니다. 이 타입들은 오퍼레이터의 다중 에이전트 패턴을 래핑합니다 — 전체 메커니즘은 에이전트 생성 및 조율과 내장 워크플로우 & 패턴을 참조하십시오.

타입	목적
`map_reduce`	N개의 분할에 대해 병렬 매퍼 에이전트로 팬아웃한 후, 리듀서 에이전트가 모든 결과를 합성합니다. 많은 파일을 동시에 검토하는 데 적합합니다.
`supervisor`	동적 위임 루프 — 슈퍼바이저 에이전트가 지금까지의 결과를 기반으로 다음 전문가를 선택하며, 최대 반복 횟수 제한이 있습니다.
`group_chat`	순서를 제어하는 중재자가 있는 다중 에이전트 토론. 트랜스크립트, 요약, 결론을 반환합니다.
`handoff`	한 에이전트의 발견 사항과 컨텍스트를 추출하여 다른 에이전트의 프롬프트에 주입하고, Kumiho에서 체인을 추적합니다.

- id: review_all
  type: map_reduce
  map_reduce:
    task: "Review each module for correctness and safety."
    splits: ["src/auth", "src/api", "src/db"]
    mapper: reviewer            # role/template for the parallel mappers
    reducer: summarizer         # role/template that synthesizes results
    concurrency: 3              # parallel mappers (max 10)

대시보드 스텝 인스펙터는 group_chat 트랜스크립트와 에이전트별 결과를 렌더링하여 다중 에이전트 스텝이 결론에 도달한 과정을 감사할 수 있습니다.

스텝 타입 참조

스텝 타입 한눈에 보기

`agent`

Agent 구조화 출력 & `output_fields`

`shell`

`python`

`email`

`notify`

`resolve`

`conditional`

`parallel`

`goto`

`output`

`human_approval`

`human_input`

`a2a`

오케스트레이션 패턴

관련 페이지

시작하기

핵심 개념

가이드

CLI 참조

게이트웨이 API

대시보드

채널

프로바이더 및 모델

도구

메모리

워크플로우 및 SOP

크론 및 스케줄링

보안 및 감사

배포 및 운영

하드웨어

MCP 및 확장성

에코시스템

참조

스텝 타입 참조

스텝 타입 한눈에 보기

agent

Agent 구조화 출력 & output_fields

shell

python

email

notify

resolve

conditional

parallel

goto

output

human_approval

human_input

a2a

오케스트레이션 패턴

관련 페이지

시작하기

핵심 개념

가이드

CLI 참조

게이트웨이 API

대시보드

채널

프로바이더 및 모델

도구

메모리

워크플로우 및 SOP

크론 및 스케줄링

보안 및 감사

배포 및 운영

하드웨어

MCP 및 확장성

에코시스템

참조

`agent`

Agent 구조화 출력 & `output_fields`

`shell`

`python`

`email`

`notify`

`resolve`

`conditional`

`parallel`

`goto`

`output`

`human_approval`

`human_input`

`a2a`