Flows Overview

Automate tasks with time-based schedules and event-driven triggers

Flows are automated tasks that execute scripts or LLM prompts. They can be run on schedules or triggered by events. Flows enable you to build sophisticated automations by combining time-based triggers (cron schedules) and event-driven triggers (real-time events from integrated services) with script execution.

What are Flows?

Flows provide workflow automation capabilities for the Mirra platform. Each flow defines when and how a script should execute, with configurable triggers, execution parameters, and resource access controls. Flows can be triggered automatically via cron schedules, by subscribing to events from integrated services like Telegram or Gmail, or manually via the SDK API.

The Mirra platform supports two trigger types: time-based triggers using cron expressions for scheduled execution, and event-based triggers with conditional logic for real-time event processing. Both trigger types execute scripts with the same execution environment and access to the Mirra SDK.

Flows support comprehensive lifecycle management, allowing developers to pause, resume, update, and monitor automated tasks. Each flow maintains execution history, enabling debugging and performance analysis.

Syntax

Creating a Time-Based Flow

POST /api/sdk/v1/flows/createTimeFlow

{
  "title": "Daily Report Generation",
  "description": "Generate and send daily analytics report",
  "schedule": "0 9 * * *",
  "prompt": "Generate daily analytics report for yesterday",
  "recommendedTools": ["memory", "gmail"]
}

Creating an Event-Based Flow

POST /api/sdk/v1/flows/createEventFlow

{
  "title": "Urgent Message Handler",
  "description": "Auto-respond to urgent Telegram messages",
  "eventType": "telegram.message",
  "conditions": {
    "field": "text",
    "operator": "contains",
    "value": "urgent"
  },
  "prompt": "Acknowledge the urgent message and create a reminder"
}

When to Use Flows

Flows are ideal for:

Scheduled Automation - Daily reports, periodic data synchronization, scheduled reminders
Event-Driven Automation - Auto-respond to messages, process incoming emails, trigger workflows
Monitoring - Health checks, alert processing, status updates
Data Processing - ETL jobs, batch processing, data aggregation
Integration Workflows - Connect multiple services, orchestrate complex automations

Flows abstract away scheduling complexity and event subscription management, allowing developers to focus on business logic.

Trigger Types

Time-Based Triggers

Time-based triggers use cron expressions to schedule periodic script execution. Cron expressions provide flexible scheduling capabilities, from simple daily runs to complex multi-condition schedules.

{
  "trigger": {
    "type": "time",
    "config": {
      "cronExpression": "0 9 * * 1-5"
    }
  }
}

Common Cron Patterns:

0 9 * * * - Daily at 9:00 AM
*/15 * * * * - Every 15 minutes
0 9 * * 1-5 - Weekdays at 9:00 AM
0 0 1 * * - First day of each month at midnight

Event-Based Triggers

Event-based triggers execute scripts automatically when matching events occur. The trigger system supports complex conditional logic with field-level filtering, enabling precise control over when scripts run.

{
  "trigger": {
    "type": "event",
    "config": {
      "eventType": "telegram.message",
      "rootCondition": {
        "operator": "AND",
        "conditions": [
          {
            "field": "text",
            "operator": "contains",
            "value": "$BTC"
          },
          {
            "field": "sender",
            "operator": "equals",
            "value": "crypto_alerts"
          }
        ]
      }
    }
  }
}

Event subscriptions support nested conditions with AND/OR logic, field comparisons, and pattern matching. See Technical Notes for complete condition syntax documentation.

Use Cases

Scheduled Automation

Generate and send daily reports every morning
Run weekly data cleanup and optimization tasks
Perform periodic health checks and monitoring
Sync data with external systems on a schedule

Event-Driven Automation

Auto-respond to Telegram messages based on keywords or senders
Process incoming emails and create tasks or reminders
Track mentions across all communication channels
Trigger workflows based on calendar events or voice calls

Monitoring & Alerts

Check system health periodically and send alerts
Monitor cryptocurrency prices and notify on threshold breaches
Track application metrics and log anomalies
Process error logs and create incident tickets

Data Processing

ETL jobs that run on schedule or when data arrives
Aggregate data from multiple sources periodically
Process batch uploads and transform data
Archive old data and maintain data retention policies

Execution Modes

Flows support different execution modes that control how scripts run:

LLM Mode (Default)

LLM mode executes the flow's prompt through Mirra's AI agent, which interprets natural language instructions and uses available tools to complete the task.

{
  "scriptId": "script_crypto_monitor"
}

The AI agent automatically:

Interprets the natural language prompt
Selects appropriate tools (resources, memory, messaging)
Executes multi-step workflows
Handles errors and edge cases

Direct Mode

Direct mode executes a specific script directly without LLM interpretation, providing deterministic execution and lower latency.

{
  "scriptId": "script_abc123",
  "config": {
    "timeout": 60,
    "memory": 512
  }
}

Direct mode is ideal for:

Performance-critical workflows
Deterministic execution requirements
Pre-tested scripts with known behavior
Cost optimization (no LLM calls)

POST /api/sdk/v1/flows/pauseFlow
{
  "assignmentId": "flow_abc123"
}

Resume a paused flow to re-enable execution:

POST /api/sdk/v1/flows/resumeFlow
{
  "assignmentId": "flow_abc123"
}

Updating Flows

Update flow configuration, triggers, or execution parameters:

POST /api/sdk/v1/flows/updateFlow
{
  "assignmentId": "flow_abc123",
  "title": "Updated Flow Title",
  "prompt": "New execution prompt",
  "schedule": "0 10 * * *"
}

Monitoring and Debugging

Execution History

Each flow maintains a complete execution history with results, logs, and performance metrics:

GET /api/sdk/v1/flows/{assignmentId}

Response includes:

Execution count and results
Last execution timestamp
Success/failure status
Execution duration and cost
Error messages and stack traces

Search and Filter

Find flows by status, trigger type, or execution results:

POST /api/sdk/v1/flows/searchFlows
{
  "status": "active",
  "trigger": { "type": "time" },
  "limit": 20
}

Next Steps

Endpoints - Complete API reference for all flow operations
Examples - Practical code examples and patterns
Technical Notes - Configuration, limits, and best practices