Workflows

Agent Swarm includes a workflow automation engine that lets you define multi-step processes as directed acyclic graphs (DAGs). Workflows connect triggers, conditions, and actions into pipelines that execute automatically when events occur.

Core Concepts

A workflow consists of:

Nodes — Individual steps in the pipeline (triggers, conditions, or actions)
Edges — Connections between nodes that define execution order and routing
Trigger data — Context passed from the triggering event through the pipeline

Node Types

Trigger Nodes (Entry Points)

Type	Description
`trigger-new-task`	Fires when a new task is created (with optional tag/source/type filters)
`trigger-task-completed`	Fires when a task completes
`trigger-github-event`	Fires on GitHub events (PR opened/closed, issue opened, comments, reviews)
`trigger-slack-message`	Fires on Slack messages (with optional channel/keyword filters)
`trigger-email`	Fires on incoming AgentMail messages
`trigger-webhook`	Fires via HTTP webhook call

Condition Nodes (Routing)

Type	Description
`property-match`	Routes based on matching properties in the trigger data
`code-match`	Routes based on a custom JavaScript expression evaluated in a sandbox
`llm-classify`	Routes based on LLM classification of the input

Action Nodes (Execution)

Type	Description
`create-task`	Creates a new task in the swarm
`send-message`	Sends a message (Slack, email, or internal)
`delegate-to-agent`	Assigns work to a specific agent

Defining a Workflow

Workflows are defined as JSON with nodes and edges arrays:

{
  "name": "pr-review-pipeline",
  "description": "Auto-assign PR reviews when PRs are opened",
  "definition": {
    "nodes": [
      {
        "id": "trigger",
        "type": "trigger-github-event",
        "label": "PR Opened",
        "config": { "eventType": "pull_request.opened" }
      },
      {
        "id": "create-review-task",
        "type": "create-task",
        "label": "Create Review Task",
        "config": {
          "taskTemplate": "Review PR #{{trigger.number}}: {{trigger.title}}",
          "tags": ["review", "automated"],
          "priority": 60
        }
      }
    ],
    "edges": [
      {
        "id": "e1",
        "source": "trigger",
        "sourcePort": "out",
        "target": "create-review-task"
      }
    ]
  }
}

Execution Model

When a workflow triggers:

The event bus receives an event (task created, GitHub webhook, Slack message, etc.)
All enabled workflows are checked — entry nodes are matched against the event
If a trigger matches, execution starts and walks the DAG breadth-first
Each node executes and produces an output port that determines which edges to follow
Async nodes (like delegate-to-agent) pause the run until the delegated work completes, then resume

Template Interpolation

Action node configs support {{variable}} template syntax to reference trigger data and previous node outputs. For example, {{trigger.title}} inserts the title from the triggering event.

Recovery and Retry

Stuck run recovery — The system detects workflow runs that stall and can recover them
Retry failed runs — Use the retry-workflow-run MCP tool to re-execute a failed run from the point of failure

MCP Tools

Tool	Description
`create-workflow`	Create a new workflow with a DAG definition
`get-workflow`	Get workflow details by ID
`list-workflows`	List all workflows (optionally filter by enabled status)
`update-workflow`	Update a workflow's definition, name, or enabled status
`delete-workflow`	Delete a workflow and its run history
`trigger-workflow`	Manually trigger a workflow execution
`get-workflow-run`	Get details of a specific workflow run
`list-workflow-runs`	List runs for a workflow
`retry-workflow-run`	Retry a failed workflow run

Dashboard UI

The dashboard includes a Workflows section (under Operations) with:

Workflows list — View all workflows with enable/disable status
Workflow detail — Interactive React Flow graph visualization of the DAG
Runs list — Track all workflow executions with status
Run detail — Step-by-step execution view with a visual graph overlay showing node statuses

Scheduled Tasks — Time-based task automation (complementary to event-driven workflows)
Task Lifecycle — How tasks created by workflows flow through the system
MCP Tools Reference — Full tool documentation

Workflows

On this page