Praison AI

Workflows CLI

Run a multi-agent workflow from a YAML file with praisonai-ts

The praisonai-ts workflow command reads a YAML file, builds one agent per step, and runs each step against your model.

Diagram

praisonai-ts workflow

output

workflow.yaml

Parse agents + steps

Step 1 Agent

Step 2 Agent

Results

Quick Start

  1. Write a workflow

    Save a minimal wf.yaml with one agent and one step.

    yaml
    name: My Workflow
agents:
  writer: gpt-4o-mini
steps:
  - name: write
    agent: writer
    task: Write a two-line poem about the sea
  2. Run it
    bash
    export OPENAI_API_KEY=...   # steps fail per-step without a key
praisonai-ts workflow wf.yaml

Workflow YAML

A workflow file has top-level metadata, an agents: map, and a steps: list.

yaml
name: Research Workflow
description: Research and summarise a topic

# agents: is a MAP of agent-name -> definition (not a list).
agents:
  # Long form: instructions + llm (both optional).
  researcher:
    instructions: Research the topic and gather information.
    llm: gpt-4o
  # Shorthand: `<agent-name>: <llm>` is the same as `writer: { llm: <llm> }`.
  writer: gpt-4o-mini

steps:
  - name: research
    agent: researcher
    task: Research AI trends in healthcare
  - name: write
    agent: writer
    task: Write a two-paragraph summary
    # depends_on limits which prior outputs feed this step's prompt.
    depends_on: [research]
KeyTypeDescription
namestringWorkflow name shown in output.
descriptionstringOptional summary printed before the run.
agentsmapAgent-name to definition. Not a list.
stepslistOrdered steps, each with an agent and a task.

Agents block

Each entry maps an agent name to its definition, in long form or shorthand.

Diagram

expands to

agents:

researcher: { instructions, llm }

writer: gpt-4o-mini

writer: { llm: gpt-4o-mini }

FieldTypeDefaultDescription
instructionsstringgeneric assistant promptAgent instructions. Falls back to role, then a generic fallback.
llmstringCLI resolved --modelModel for this agent. Falls back to the CLI’s resolved model.

The shorthand writer: gpt-4o-mini is equivalent to writer: { llm: gpt-4o-mini }.

Steps block

Each step names an agent, gives it a task, and optionally declares dependencies.

FieldTypeDescription
namestringStep name, used in output and as a depends_on target.
agentstringAgent from the agents: map. If agents: is set, an unknown name is rejected.
taskstringThe instruction for this step. Required.
depends_onlistPrior step names whose outputs feed this step’s prompt.

Use inline-array syntax for dependencies. A bare depends_on: is an empty list.

yaml
steps:
  - name: write
    agent: writer
    task: Write the summary
    depends_on: [research, outline]   # inline array

Sequential vs parallel

Steps run in order by default; --parallel runs them all at once without shared context.

Diagram

Yes

No

Do later steps need earlier outputs?

Sequential (default)

–parallel

ModeBehaviour
Sequential (default)Steps run in declaration order. Each step’s prompt is prefixed with its depends_on outputs if declared, otherwise with every earlier step’s output. A failed step stops the run.
--parallelAll steps run together, without shared context — each step sees only its own task. Outcomes are recorded independently and one failure does not cancel the others.
bash
# Sequential (default)
praisonai-ts workflow wf.yaml

# Parallel, no shared context
praisonai-ts workflow wf.yaml --parallel

Failure and exit codes

The command rejects wrong-schema files and reports step failures with specific exit codes.

SituationExitMessage shape
One or more sequential steps failed5 / 4 / 3 / 1"N of M step(s) failed: step_name: <error>; ..."
File yields no steps (bad YAML, wrong shape, empty steps:)1"No steps found in <file>. A workflow needs a 'steps:' list, each entry naming an 'agent' and a 'task'."
Scalar steps: not-a-list value1Same “no steps” message
A step references an agent not in agents:1"Step '<name>' references agent '<x>', which is not defined in the workflow's 'agents:' block."
A step has no task1"Step '<name>' has no 'task' to run"
All steps succeed0Success output

Command reference

Run a workflow file with optional parallel and JSON flags.

bash
praisonai-ts workflow <file> [--parallel] [--json] [--verbose] [--model <model>]
OptionDescription
<file>Path to the workflow YAML file (positional, required).
--parallelRun all steps at once without shared context.
--jsonEmit JSON, including per-step { status, output } or { status, error }.
--verbosePrint extra detail, including stack traces on failure.
--modelOverride the resolved model for steps that omit llm.

JSON output records each step under results:

json
{
  "success": true,
  "data": {
    "workflow": "Research Workflow",
    "steps": 2,
    "results": {
      "research": { "status": "completed", "output": "..." },
      "write": { "status": "completed", "output": "..." }
    }
  }
}

Related

Workflows (SDK)

Build workflows in code with AgentFlow and the YAML workflow engine.

 Agent Flow

Chain steps programmatically with AgentFlow.

 Python Workflow CLI

The Python praisonai workflow command for cross-language users.