Workflow Tool

What is it?

The Workflow Tool lets you create and run reusable, multi-step automation pipelines. Instead of building a sequence of actions manually each time, you define your pipeline once as a JSON file and execute it whenever you need it.

A workflow is a sequential pipeline — each stage runs one after another, in the order you specify. Each stage can perform a different type of action, from sending a prompt to a swarm of agents, calling a tool, or even pausing to ask you a question.

Workflows are distinct from swarms (ad-hoc, turn-by-turn fan-out). A workflow is a persisted, reusable pipeline: you write it once as a file, then run it as many times as you want. One of its stage types can even invoke a swarm internally, giving you the best of both worlds.

How it works

A workflow is defined as a JSON file stored in the YukkaiDocs/workflows/ directory. Each file describes a series of stages, and each stage has:

• A type (what action it performs)
• A dependsOn field (which stages must finish before it starts)
• Type-specific parameters (prompt text, tool configuration, branch conditions, etc.)

Stages run sequentially — not in parallel. Parallelism only happens inside a swarm or dynamicSwarm stage, across its fanned-out items.

An optional Agent-in-the-Middle supervisor can be enabled to handle errors autonomously — retrying failed stages, skipping problematic ones, or escalating issues when needed.

How to use it

The Workflow Tool has five actions:

Action	Description
run	Execute a workflow by name. Pass optional inputs as key-value pairs.
validate	Check a workflow file for errors before running it. Always do this for new or edited workflows.
list	Show all available workflow files with their stage counts and supervisor flags.
status	Check the progress of a running workflow, including any pending human questions.
stop	Gracefully stop a running workflow (the current stage finishes first).

Basic steps

1. Write a workflow JSON file in YukkaiDocs/workflows/
2. Validate it to catch errors early
3. Run it — with optional inputs
4. Check status if it pauses or you want to monitor progress
5. Stop it if something goes wrong

Examples

Listing available workflows

Action: list

This shows every workflow file you have, including how many stages each one contains and whether the supervisor is enabled.

Validating a workflow

Action: validate
workflow_name: "my-daily-report"

Always validate a new or edited workflow before running it. This catches structural errors before execution begins.

Running a workflow

Action: run
workflow_name: "my-daily-report"
inputs:
  topic: "AI industry news"
  recipient: "team@company.com"

The inputs object passes key-value pairs that stages can reference during execution.

Checking status

Action: status

If a workflow includes a human-in-the-loop stage and pauses to ask you a question, the status will show the pending question. You answer it, then run status again (or re-run) to resume.

Stopping a workflow

Action: stop

This is a graceful stop — the stage currently in flight will finish, but no further stages will start.

Stage types

Each stage in your workflow JSON uses one of these action types (written in camelCase):

Stage type	What it does
prompt	Send a prompt to an AI model
swarm	Fan out to multiple agents working in parallel
dynamicSwarm	Like swarm, but items are generated dynamically at runtime (max 50 concurrent, 1000 total)
toolCall	Call a specific Yukkai tool
subWorkflow	Run another workflow inside this one
humanInTheLoop	Pause and ask the user a question before continuing
wait	Wait for a specified duration
branch	Conditionally choose a path based on a simple condition (true/false, ==/!=, non-empty-is-truthy)

Note: The branch condition evaluator is intentionally simple — it supports literal true/false, equality checks, and non-empty-is-truthy. It is not a full expression language.

Tips & best practices

• Always validate first. Run validate on any new or modified workflow before executing it. This catches structural problems without wasting a run.
• Keep stages focused. Each stage should do one thing well. Complex logic is easier to debug when stages are small and composable.
• Use human-in-the-loop sparingly. Pausing to ask questions is powerful but slows things down. Reserve it for decisions that genuinely need your input.
• Leverage the supervisor. If your workflow is long or critical, enable the Agent-in-the-Middle supervisor so transient failures get retried automatically.
• Compose with sub-workflows. Instead of one giant workflow, break it into smaller ones and chain them with subWorkflow stages. This makes each part reusable and testable on its own.
• Name workflows clearly. Workflow names come from filenames (without .json), so use descriptive, kebab-case names like daily-news-digest or weekly-code-review.
• Check status when paused. If a workflow seems stuck, run status — it may be waiting for you to answer a human-in-the-loop question.
• Stop gracefully. Use stop rather than force-killing. The current stage finishes cleanly, avoiding partial or corrupted results.