Workflows

A workflow in Moira is a directed graph of nodes that defines a multi-step process for AI agents to execute.

Workflow Structure

Every workflow consists of:

{
  "id": "my-workflow",
  "metadata": {
    "name": "My Workflow",
    "version": "1.0.0",
    "description": "Description of what this workflow does"
  },
  "nodes": [
    // Array of node definitions
  ]
}

Metadata

Field	Required	Description
`name`	Yes	Human-readable workflow name
`version`	Yes	Semantic version string
`description`	Yes	What the workflow accomplishes

Nodes Array

Nodes are the steps in your workflow. Each node has an id and a type that determines its behavior.

Workflow Execution

When a workflow starts:

Engine creates an execution instance with unique processId
Finds the start node (type: start)
Returns the first directive to the agent
Agent executes and returns result
Engine evaluates connections and moves to next node
Repeat until reaching an end node (type: end)

Execution Context

Each execution maintains a context object containing:

{
  variables: Record<string, unknown>; // User-defined variables
  nodeStates: Record<string, unknown>; // Per-node state
  executionId: string; // Unique execution ID
  workflowId: string; // Source workflow ID
  currentNodeId: string; // Current position
}

Node Types

Moira supports 7 node types:

Type	Purpose
`start`	Entry point for workflow execution
`end`	Terminal node marking completion
`agent-directive`	Agent task with directive and completion condition
`condition`	Branch based on structured conditions
`expression`	Compute values using arithmetic expressions
`subgraph`	Delegate to another workflow
`telegram-notification`	Send notifications via Telegram

See Nodes for detailed documentation on each type.

Connections

Nodes connect via the connections object that defines the flow. Each node type has specific connection types:

Agent Directive Node

{
  "id": "analyze-task",
  "type": "agent-directive",
  "directive": "Analyze the task requirements",
  "completionCondition": "Analysis is complete",
  "connections": {
    "success": "next-step",
    "error": "error-handler"
  }
}

Condition Node

{
  "id": "check-status",
  "type": "condition",
  "condition": {
    "type": "equals",
    "left": { "type": "variable", "path": "status" },
    "right": { "type": "literal", "value": "success" }
  },
  "connections": {
    "true": "success-path",
    "false": "retry-path"
  }
}

Complete Workflow Example

{
  "id": "simple-workflow",
  "metadata": {
    "name": "Simple Task Workflow",
    "version": "1.0.0",
    "description": "A basic workflow demonstrating node connections"
  },
  "nodes": [
    {
      "id": "start",
      "type": "start",
      "connections": { "default": "main-task" }
    },
    {
      "id": "main-task",
      "type": "agent-directive",
      "directive": "Complete the assigned task",
      "completionCondition": "Task is completed successfully",
      "connections": { "success": "end" }
    },
    {
      "id": "end",
      "type": "end"
    }
  ]
}

Workflow Visibility

Workflows have visibility settings:

private - Only the owner can access
public - All users can start the workflow

Best Practices

Start with start - Every workflow must have a start node
End with end - Use end nodes to mark completion
Clear Directives - Write unambiguous instructions
Measurable Conditions - Completion conditions should be verifiable
Error Handling - Include error connections for graceful failures
Documentation - Add descriptions to complex nodes

Nodes - Node types and configuration
Templates - Dynamic content in workflows