Your first workflow

A Revka workflow is a YAML file that defines a multi-step pipeline — spawn agents, run shell or Python, branch on conditions, publish results — that the operator-mcp backend executes deterministically and audits in Kumiho graph memory. This page walks you end to end: write the smallest workflow that does something, create it in the dashboard, run it, and read what came back.

Use this page the first time you author a workflow. Once you are comfortable, the Workflow YAML reference documents every field, the Step types reference covers each step type, and Workflows, editor & runs goes deeper on the dashboard. Make sure your gateway and the operator sidecars are running first — see Quickstart and Install the Python MCP sidecars.

What a workflow looks like

A workflow has a few top-level fields and an ordered list of steps. The smallest useful workflow is one agent step that does some work, followed by an output step that renders the result:

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}"

Two things are happening here:

• The greet step spawns a claude agent with the researcher role and a prompt. Its text result becomes available as ${greet.output}.
• The summary step depends_on greet, so it runs after it, and renders a template that interpolates ${greet.output}. The ${...} syntax pulls values from workflow state at run time. (See Variables, expressions & triggers for every namespace.)

The core fields

These are the top-level keys you will use most. name, version, and at least one step are required; the rest are optional.

Field	Type	Required	Meaning
name	string	yes	Unique slug that identifies the workflow.
version	string	yes	Semantic version, e.g. "1.0".
description	string	no	Human-readable purpose.
tags	list	no	Classification labels for search and filtering.
inputs	list	no	Typed parameters the run accepts (see below).
outputs	list	no	Named outputs that map to step results for callers.
steps	list	yes	The ordered step definitions — at least one required.
triggers	list	no	Auto-launch conditions (cron schedules or entity events).
checkpoint	bool	no	Persist state after each step. Defaults to true.

To make the workflow take a parameter, declare it under inputs and reference it with ${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}"

Tip

${inputs.name} is the canonical form for input references. Older UI hints sometimes show ${input.name} (singular) — use the plural inputs.

Where workflow files live

When you load or run a workflow by name, the operator searches several locations and later sources override earlier ones:

Priority	Location	Purpose
3 (highest)	.revka/workflows/	Project-local overrides (relative to the run’s cwd).
2	~/.revka/workflows/	User-global workflows.
1 (lowest)	.revka/operator_mcp/workflow/builtins/	Shipped built-in defaults.
Fallback	Kumiho space Revka/Workflows	Cloud-managed definitions, resolved by kref.

So a hello-world.yaml in a project’s .revka/workflows/ shadows a user-global one of the same name, which in turn shadows a built-in.

Note

Files named *.r{N}.yaml (for example hello-world.r3.yaml) are revision artifacts, not directly loaded by the directory scanner. They are reached only via kref resolution. When you save from the dashboard, Revka writes both the revision artifact and registers a Kumiho artifact; the bare {slug}.yaml is what the directory scan picks up. A harmless validation warning about .r{N}.yaml files is expected.

Create it in the dashboard

The dashboard is the fastest way to author and store a workflow. Definitions are saved as Kumiho items (space Revka/Workflows, item kind workflow), with the YAML stored as a workflow.yaml revision artifact — not in config.toml. Every save writes a new revision and tags it published.

1. Open Workflows from the Orchestration section of the sidebar, or go to /workflows. (Need the dashboard? See Run the dashboard.)

2. Click Create to open the full-screen editor overlay on a blank workflow.

3. The editor keeps a visual DAG and a YAML document in bi-directional sync. Switch to the YAML pane and paste the hello-world YAML above, or drag step nodes from the palette onto the canvas and configure each one in the right-hand panel.

   Caution

   If you edited the YAML text directly, apply it to the graph before saving. Save serializes the graph back to YAML, so an un-applied text edit will not be persisted.

4. Click Save. The gateway validates the YAML (a six-pass check for duplicate step IDs, dangling dependencies, cycles, per-step config, variable references, and triggers). On success it creates a published Kumiho revision and syncs any cron jobs the YAML declares. Validation errors appear inline so you can fix them before the save lands.

Each definition in the list shows its source: builtin, builtin-modified, or custom.

Note

Built-in workflows cannot be edited or deleted — only duplicated. Use Duplicate to get an editable copy. Saving from the dashboard also persists the YAML to disk at ~/.revka/workflows/{slug}.r{N}.yaml and registers a Kumiho artifact. Later edits to a definition do not retroactively change an already-completed run’s graph — each run is pinned to the revision it executed.

Or create it over the API

If you prefer scripting, POST the YAML as a string. Every workflow route requires the pairing bearer token (see Pairing & authentication).

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"]
}

Field	Required	Meaning
name	yes	Display name; slugified into the item identifier.
description	yes	Human-readable purpose.
definition	yes	The full workflow YAML, as a string.
version	no	Semantic version label.
tags	no	Classification list for search and filtering.

On success the gateway validates, slugifies the name, writes a published revision with the YAML as the workflow.yaml artifact, and returns 201 Created. The full definition CRUD surface is in Workflows & Architect API.

Run it

You can launch a run from the dashboard or the API.

Dashboard

On the Workflows page, select hello-world and click Execute. If the workflow declares inputs, you are prompted for their values first. The run appears on the Workflow Runs page (/runs), where you watch each step light up live.

API

POST to the run endpoint. The path segment is the workflow name (not a kref):

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

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

Field	Required	Meaning
inputs	no	Object mapping workflow input names to values.
cwd	no	Working directory for shell and agent steps.
target_step_id	no	”Run to here” — execute only the transitive ancestors of this step plus the step itself, then stop.

The definition is validated before dispatch; an invalid definition or unknown target_step_id returns 400. On success you get a run id back:

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

A run moves through these statuses:

Status	Meaning
pending	Created but not yet picked up by the executor.
running	The executor is active.
paused	Waiting at a human_approval or human_input gate.
completed	All steps finished successfully.
failed	A step failed; the checkpoint is preserved so you can retry.
cancelled	Stopped by a user or the system.
stale	Non-terminal status with no checkpoint and no live lock (for example, after a redeploy wiped local state).

Note

State is checkpointed after each step to ~/.revka/workflow_checkpoints/{run_id}.json. If a run fails, the checkpoint is preserved so Retry re-runs only from the first failed step. See Runs, approvals & checkpoints.

Read the output

In the dashboard

Open the run on the Workflow Runs page (/runs). The run viewer pins the run to the exact YAML revision it executed, so the graph always reflects what actually ran. Click any node to open the step inspector, which shows the step’s status, agent id and role, and an output preview. For your hello-world run, the summary node’s output is the rendered "Agent said: ..." template.

Over the API

Fetch the run by its id:

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

The response is { "run": { ... } } with per-step detail. Live runs are read from the executor’s in-memory status; finished runs are resolved from the Kumiho run record. An unknown run_id returns 404. The run lifecycle endpoints (list, retry, cancel, delete, approve) are documented in Workflows & Architect API.

Tip

Agent steps also write their full text output to disk and expose the path as ${greet.output_data.artifact_path}. When a later step needs the complete prior output, point it at that artifact path rather than inlining the whole text with ${greet.output} — that keeps downstream prompts small.

Next steps

Workflow YAML reference Every top-level field and step option in full.

Step types reference agent, shell, python, conditional, parallel, output, and more.

Variables, expressions & triggers The ${...} namespaces, the ${{ ... }} evaluator, and cron/entity triggers.

Runs, approvals & checkpoints Pause for approval, retry failed runs, and how checkpoints work.

Built-in workflows & patterns Ship-with templates and multi-agent orchestration patterns.

Dashboard: workflows, editor & runs The DAG/YAML editor, the Architect, and the runs page in depth.