Aegis Orchestrator
Workflows

Creating Workflows via the UI

Step-by-step guide to creating, editing, and managing workflows using the Zaru web interface, including scope management and FSM visualization.

Creating Workflows via the UI

The Zaru web interface provides structured forms and a YAML editor for creating and managing workflows. Workflows define finite state machines (FSMs) that coordinate agents, system commands, container steps, and human approval gates into durable, restartable sequences.

Two surfaces are available:

  • Admin console (/admin/workflows) — operators manage all workflows across tenants, including scope changes
  • Dashboard (/dashboard/workflows) — users manage their own workflows

Prerequisites

  • A Zaru account with an active session
  • For admin access: an aegis:admin or aegis:operator Keycloak role
  • Agents referenced in the workflow must already be deployed

Creating a Workflow

Step 1: Navigate to the Workflow List

  • Admin: Click Workflows in the admin sidebar
  • Dashboard: Click Workflows in the dashboard navigation

Step 2: Click "New Workflow"

On the admin surface, this button is only visible to users with admin or operator roles.

Step 3: Choose an Editing Mode

Toggle between Structured Form and YAML Editor at the top of the page.

The structured form guides you through each section of the workflow manifest. The YAML editor gives direct access to the full manifest with syntax highlighting.

Step 4: Define the Workflow

Metadata

FieldExampleNotes
namedev-pipelineLowercase, alphanumeric, hyphens. Must be unique.
version1.0.0Semantic version string.
descriptionIterative code gen with reviewUsed for discovery search.
labelscategory: developmentKey-value pairs for filtering.
tagsci-cd, code-reviewUsed for discovery and search.

Initial State

Set spec.initial_state to the name of the first state the workflow enters when executed.

States

Each state in the FSM has:

  • Name — unique identifier within the workflow (e.g., GENERATE, VALIDATE, COMPLETE)

  • Kind — determines what the state does:

    KindPurpose
    AgentRun a deployed agent with templated input
    SystemExecute a shell command
    HumanWait for human approval or input
    ContainerRunRun a Docker container (CI/CD step)
    ParallelAgentsRun multiple agents concurrently with consensus
    ParallelContainerRunRun multiple containers concurrently
    SubworkflowInvoke another workflow as a nested FSM
  • Kind-specific fields — e.g., agent name for Agent kind, command for System kind, prompt for Human kind

  • Transitions — ordered list of condition/target pairs defining where the FSM moves next

Transitions

Each transition has:

  • condition — when to take this transition (always, exit_code_zero, exit_code_non_zero, score_above, score_below, consensus, input_equals_yes, input_equals_no, custom)
  • target — the state name to transition to
  • threshold — (for score/consensus conditions) numeric threshold
  • feedback — (optional) Handlebars template passed to the target state as error context

A state with an empty transitions: [] array is a terminal state — the workflow ends when it is reached.

The form's Recommended schedule section (Cron, Time zone, Jitter (seconds)) writes spec.default_schedule: "A recommendation only: it is offered when someone makes a schedule for this workflow and creates nothing by itself." See Schedules. A manifest carrying the old spec.schedule is refused by the YAML mode's validation, and one loaded with it opens with that key left out and a line saying so.

Step 5: Submit

Click Register Workflow, then choose the version in the Save Changes dialog. The dialog's current version is the manifest's metadata.version: from the YAML text while the YAML tab is the active tab, else from the form. The orchestrator validates the manifest, checks that referenced agents exist, and registers the workflow. Validation errors are shown inline.


The FSM Visualization Tab

The workflow detail and edit pages include a Visualization tab that renders the state machine as an interactive graph. See Workflow Visualization for details on reading the graph.

The visualization updates live as you edit the YAML, providing immediate feedback on your workflow topology.


Workflow Scope

Workflows have a scope that controls visibility:

ScopeVisibility
UserOnly the creating user can see and execute the workflow
TenantAll users in the same tenant can see and execute the workflow
GlobalAll users across all tenants can see and execute the workflow

Workflows created via the dashboard are User-scoped by default.

Changing Scope (Admin Only)

On the admin surface, the workflow detail page shows a Scope badge (User, Tenant, or Global). Operators can click the badge to open the scope change dialog and promote or demote the workflow:

  1. Click the scope badge on the workflow detail page
  2. Select the new scope (User, Tenant, or Global)
  3. Confirm the change

Scope changes are immediate. Promoting a User workflow to Tenant makes it visible to all tenant members. Promoting to Global makes it platform-wide.

Scope management is not available on the consumer dashboard surface.


Editing a Workflow

  1. Navigate to the workflow detail page (click the workflow name in the list)
  2. Click Edit
  3. Modify fields on the Form tab or the YAML tab
  4. Use the Visualization tab to verify the updated FSM topology
  5. Click Save Changes, then choose the version in the Save Changes dialog: a patch, minor or major bump of the current version, or Force overwrite to keep the current version and overwrite its entry

The YAML tab shows the manifest as the orchestrator stores it. It is rewritten from the form's fields only after you change something on the Form tab, so switching tabs without editing the form leaves the text as it was.

A save from the YAML tab sends your text as typed, with only the value of its metadata.version line changed to the version you chose in the dialog. Text with no metadata.version line is refused with a message, and nothing is saved. A save from the Form tab sends the form's fields.

The orchestrator stores the parsed manifest and returns its own serialisation of it, so comments and formatting in a manifest are not kept: the next time you open the workflow, the YAML tab shows the stored manifest without them.

The save registers the manifest with POST /v1/workflows. A new version creates a new version entry; Force overwrite adds force=true and overwrites the existing entry of the same name and version.


Deleting a Workflow

  1. Navigate to the workflow detail page
  2. Click Delete
  3. Confirm in the dialog

Running workflow executions are not affected by deletion, but no new executions can be started.

On the admin surface, admin and operator roles can delete any workflow. On the dashboard, users can only delete workflows they created.


Running a Workflow

From the workflow detail page or list, click Execute to open the execution dialog:

  1. Enter the workflow input (plain text or JSON matching the workflow's expected input schema)
  2. Click Run
  3. You are redirected to the execution detail view

Minimal Example

apiVersion: 100monkeys.ai/v1
kind: Workflow
metadata:
  name: simple-pipeline
  version: "1.0.0"
  description: "Generate code and validate it."
  tags:
    - code-generation
spec:
  initial_state: GENERATE
  states:
    GENERATE:
      kind: Agent
      agent: python-coder
      input: "{{workflow.task}}"
      transitions:
        - condition: always
          target: VALIDATE
    VALIDATE:
      kind: Agent
      agent: output-judge
      input: "Evaluate: {{GENERATE.output}}"
      transitions:
        - condition: score_above
          threshold: 0.9
          target: COMPLETE
        - condition: score_below
          threshold: 0.9
          target: GENERATE
          feedback: "{{VALIDATE.output.reasoning}}"
    COMPLETE:
      kind: System
      command: "echo done"
      transitions: []

See the Workflow Manifest Reference for the complete field specification.


Version History

Multiple workflow versions coexist in the database. Deploying a workflow with a different version string creates a new version entry rather than overwriting the existing one.

To view all versions:

  1. Navigate to the workflow detail page
  2. Click the Versions tab
  3. The list shows all versions with their scope indicators (User, Tenant, or Global)
  4. Click any version to view its manifest

Execution History

The workflow detail page includes an Executions tab that shows all executions spawned by that workflow, filtered by workflow name.

  1. Navigate to the workflow detail page
  2. Click the Executions tab
  3. Each row shows the execution status, start time, and duration
  4. Click any execution to view the full Glass Lab narrative replay

On this page