Workflows¶

Workflows are automated multi-step processes that orchestrate agent interactions. They enable complex, repeatable automation scenarios.

What is a Workflow?¶

A Workflow defines:

A sequence of steps involving agents
Trigger conditions (manual, scheduled, or event-based)
Data flow between steps
Success/failure handling

Workflow Architecture¶

┌────────────────────────────────────────────────────────┐
│                     Workflow                            │
│  ┌──────────┐    ┌──────────┐    ┌──────────────────┐ │
│  │ Trigger  │───►│ Step 1   │───►│ Step 2           │ │
│  │ (Manual) │    │ (Agent A)│    │ (Agent B)        │ │
│  └──────────┘    └──────────┘    └────────┬─────────┘ │
│                                           │           │
│                                           ▼           │
│                                  ┌──────────────────┐ │
│                                  │ Step 3           │ │
│                                  │ (Notification)   │ │
│                                  └──────────────────┘ │
└────────────────────────────────────────────────────────┘

Creating a Workflow¶

Via Dashboard¶

Navigate to Workflows in the sidebar
Click Create Workflow
Add a trigger
Add steps
Configure data flow
Save and enable

Workflow Components¶

Component	Description
Trigger	What starts the workflow
Steps	Individual actions/agent calls
Transitions	How data flows between steps
Conditions	Logic for branching

Trigger Types¶

Manual Trigger¶

Start the workflow by clicking a button or API call.

trigger:
  type: manual

Scheduled Trigger¶

Run the workflow on a schedule.

trigger:
  type: schedule
  cron: "0 9 * * *"  # Daily at 9 AM

Webhook Trigger¶

Start the workflow from external events.

trigger:
  type: webhook
  path: /workflows/my-workflow/trigger

Step Types¶

Agent Step¶

Send a message to an agent and capture the response.

steps:
  - id: analyze
    type: agent
    agent_id: "uuid"
    input:
      message: "Analyze this: {{trigger.data}}"
    output:
      analysis: "{{response.content}}"

Condition Step¶

Branch based on a condition.

steps:
  - id: check_sentiment
    type: condition
    condition: "{{analyze.sentiment}} == 'negative'"
    then: escalate
    else: respond

Notification Step¶

Send notifications to external systems.

steps:
  - id: notify
    type: notification
    channel: webhook
    url: "https://example.com/notify"
    payload:
      result: "{{analyze.output}}"

Data Flow¶

Variable Syntax¶

Use {{variable}} to reference data:

Reference	Description
`{{trigger.data}}`	Data from the trigger
`{{step_id.output}}`	Output from a previous step
`{{context.workflow_id}}`	Workflow metadata

Example Data Flow¶

workflow:
  name: Customer Feedback Analysis

  trigger:
    type: webhook

  steps:
    - id: analyze
      type: agent
      agent_id: "sentiment-analyzer"
      input:
        message: "Analyze sentiment: {{trigger.body.feedback}}"

    - id: route
      type: condition
      condition: "{{analyze.sentiment}} == 'negative'"
      then: escalate
      else: respond

    - id: escalate
      type: agent
      agent_id: "escalation-agent"
      input:
        message: "Handle escalation: {{trigger.body.feedback}}"
        context: "{{analyze.output}}"

    - id: respond
      type: agent
      agent_id: "response-agent"
      input:
        message: "Generate response: {{trigger.body.feedback}}"

Workflow Status¶

Workflow States¶

State	Description
`draft`	Not yet enabled
`active`	Ready to run
`disabled`	Manually disabled

Execution States¶

State	Description
`pending`	Queued for execution
`running`	Currently executing
`completed`	Successfully finished
`failed`	Error occurred
`cancelled`	Manually stopped

Monitoring¶

Execution History¶

View past workflow runs:

Go to Workflows
Click on a workflow
View Execution History tab

Execution Details¶

For each run, see:

Start/end time
Status of each step
Input/output data
Error messages (if failed)

Example Workflows¶

Support Ticket Triage¶

name: Support Ticket Triage
trigger:
  type: webhook

steps:
  - id: classify
    type: agent
    agent_id: "classifier-agent"
    input:
      message: "Classify this ticket: {{trigger.body.subject}} - {{trigger.body.description}}"

  - id: route
    type: condition
    condition: "{{classify.priority}} == 'urgent'"
    then: urgent_handler
    else: normal_handler

  - id: urgent_handler
    type: agent
    agent_id: "urgent-support"
    input:
      message: "Handle urgent: {{trigger.body.description}}"

  - id: normal_handler
    type: agent
    agent_id: "general-support"
    input:
      message: "Handle: {{trigger.body.description}}"

  - id: notify
    type: notification
    channel: webhook
    url: "{{trigger.body.callback_url}}"
    payload:
      ticket_id: "{{trigger.body.id}}"
      response: "{{urgent_handler.output || normal_handler.output}}"

Daily Report Generation¶

name: Daily Sales Report
trigger:
  type: schedule
  cron: "0 8 * * *"  # 8 AM daily

steps:
  - id: gather_data
    type: agent
    agent_id: "data-collector"
    input:
      message: "Collect sales data for yesterday"

  - id: analyze
    type: agent
    agent_id: "analyst"
    input:
      message: "Analyze this sales data: {{gather_data.output}}"

  - id: generate_report
    type: agent
    agent_id: "report-writer"
    input:
      message: "Write a report based on: {{analyze.output}}"

  - id: distribute
    type: notification
    channel: webhook
    url: "https://slack.example.com/webhook"
    payload:
      text: "Daily Sales Report\n{{generate_report.output}}"

Code Review Pipeline¶

name: Code Review
trigger:
  type: webhook

steps:
  - id: security_review
    type: agent
    agent_id: "security-reviewer"
    input:
      message: "Review for security issues: {{trigger.body.diff}}"

  - id: style_review
    type: agent
    agent_id: "style-reviewer"
    input:
      message: "Review code style: {{trigger.body.diff}}"

  - id: compile_feedback
    type: agent
    agent_id: "feedback-compiler"
    input:
      message: |
        Compile review feedback:
        Security: {{security_review.output}}
        Style: {{style_review.output}}

  - id: post_comment
    type: notification
    channel: webhook
    url: "{{trigger.body.comment_url}}"
    payload:
      body: "{{compile_feedback.output}}"

Best Practices¶

1. Keep Steps Focused¶

# Good: Single responsibility
- id: analyze
  type: agent
  agent_id: "analyzer"

- id: summarize
  type: agent
  agent_id: "summarizer"

# Avoid: Overloaded steps
- id: do_everything
  type: agent
  # Agent does analysis AND summary AND notification

2. Handle Failures¶

steps:
  - id: critical_step
    type: agent
    on_failure:
      action: notify
      channel: webhook
      url: "https://alerts.example.com"

3. Use Meaningful IDs¶

# Good
- id: analyze_sentiment
- id: route_by_priority
- id: generate_response

# Avoid
- id: step1
- id: step2

4. Test Before Enabling¶

Create workflow in draft state
Run manual tests
Verify outputs
Enable for production

API Reference¶

List Workflows¶

GET /api/workflows

Get Workflow¶

GET /api/workflows/{id}

Execute Workflow¶

POST /api/workflows/{id}/execute
Content-Type: application/json

{
  "data": {
    "input": "value"
  }
}

Get Execution Status¶

GET /api/workflows/{id}/executions/{execution_id}