Workflows

Workflows are GAIA’s most powerful feature—intelligent automation sequences that execute complex multi-step tasks across your connected integrations. Unlike simple scripts, GAIA workflows leverage AI to understand context, make decisions, and adapt to changing situations.

What Makes GAIA Workflows Different?

AI-Powered Execution

Each step is executed by an intelligent agent that understands context and makes decisions

Natural Language Definition

Describe what you want in plain English—no coding required

Cross-Integration

Seamlessly connect Gmail, Calendar, Notion, Slack, GitHub, and 100+ more services

Self-Learning

Workflows improve over time as GAIA learns optimal approaches

Architecture Overview

Workflow Components

# From: apps/api/app/models/workflow_models.py:180-244

class Workflow(BaseModel):
    id: str                              # Unique identifier
    user_id: str                         # Owner
    title: str                           # "Process Client Proposals"
    description: str                     # What this workflow does
    steps: List[WorkflowStep]            # Ordered action sequence (max 10)
    trigger_config: TriggerConfig        # When/how to execute
    activated: bool                      # Is it enabled?
    
    # Execution tracking
    total_executions: int
    successful_executions: int
    last_executed_at: datetime

Step Structure

# From: apps/api/app/models/workflow_models.py:32-44

class WorkflowStep(BaseModel):
    id: str
    title: str          # "Search for client context"
    category: str       # "gmail" - Routes to appropriate subagent
    description: str    # Detailed instructions for execution

Steps are abstract descriptions, not specific tool calls. The executing agent decides which exact tools to use based on context.

Trigger Types

1. Manual Triggers

User-initiated execution—perfect for on-demand tasks:

// Example: "Prepare for client meeting"
const workflow = {
  trigger_type: "manual",
  steps: [
    {
      title: "Search client email history",
      category: "gmail",
      description: "Find all emails from client in last 3 months"
    },
    {
      title: "Generate meeting prep document",
      category: "documents",
      description: "Summarize key points, action items, and open questions"
    }
  ]
};

2. Scheduled Triggers

Time-based automation using cron expressions:

# From: apps/api/app/models/workflow_models.py:61-103

class TriggerConfig(BaseModel):
    type: TriggerType.SCHEDULE
    cron_expression: str  # "0 9 * * 1"  = Every Monday at 9am
    timezone: str         # "America/New_York"
    next_run: datetime    # Calculated automatically

Common Schedules:

0 9 * * *
# Every day at 9:00 AM

3. Integration Triggers

Event-driven automation—the most powerful type:

# From: apps/api/app/models/workflow_models.py:71-92

class TriggerConfig(BaseModel):
    type: TriggerType.INTEGRATION
    trigger_name: str         # "gmail_new_email_received"
    trigger_data: dict        # Provider-specific configuration
    composio_trigger_ids: List[str]  # Registered webhook IDs

Example Integration Triggers:

Gmail
Calendar
GitHub
Slack

New email received
Email labeled
Email matching filter
Specific sender detected

Workflow Execution

Intelligent Execution Flow

# From: apps/api/app/agents/prompts/workflow_prompts.py:287-356

# When executing a workflow, GAIA:
# 1. Receives trigger context (if event-driven)
# 2. Loads workflow steps
# 3. Executes each step with full intelligence
# 4. Passes context between steps
# 5. Handles errors and retries
# 6. Logs execution for learning

Execution Modes

Execution Approaches

Step Execution Example

Here’s how GAIA executes a workflow step intelligently:

Step Received

{
  "title": "Create follow-up calendar event",
  "category": "googlecalendar",
  "description": "Schedule 30min meeting for next Tuesday at 2pm"
}

Context Analysis

Agent understands:

“next Tuesday” needs date calculation
User’s timezone from config
30 minutes = duration
“meeting” = event type

Tool Selection

# Agent decides to use calendar subagent
handoff(
  subagent_id="googlecalendar",
  task="Create 30min event on 2024-12-17 at 14:00"
)

Subagent Execution

Calendar subagent:

Checks for conflicts
Finds available slot
Creates event
Returns confirmation

Result Integration

Main agent receives event_id and continues to next step with full context

Creating Workflows

Via Natural Language

The easiest way—just describe what you want:

# From: apps/api/app/agents/tools/workflow_tool.py:247-298

@tool
async def create_workflow(
    user_request: str,  # "Email me a summary of my todos every morning"
    mode: Literal["new", "from_conversation"] = "new"
) -> dict:
    """
    GAIA's workflow assistant will:
    1. Understand your intent
    2. Ask clarifying questions if needed
    3. Search for appropriate triggers
    4. Generate optimized steps
    5. Present draft for confirmation
    """

Example Conversation:

"When I get an email from my boss, create a todo and notify me on Slack"

From Conversation History

Turn any successful interaction into a reusable workflow:

// From: apps/web/src/features/workflows/types/workflowExecutionTypes.ts

// After completing a task manually with GAIA:
// "Save this as a workflow that runs every Monday"

// GAIA extracts:
interface ConversationContext {
  suggested_title: string;
  summary: string;
  workflow_steps: string[];
  integrations_used: string[];
}

// And creates a reusable automation

Workflow Generation Principles

GAIA follows strict optimization rules to create efficient workflows.

Ultra-Efficient Steps

# From: apps/api/app/agents/prompts/workflow_prompts.py:139-180

# CRITICAL RULES:
# - MINIMIZE STEPS: Aim for 3-5 max
# - COMBINE OPERATIONS: Use tools that handle multiple tasks
# - ELIMINATE REDUNDANCY: Never duplicate actions
# - NO COGNITIVE STEPS: No "analyze" or "review" steps
# - ONLY EXTERNAL ACTIONS: Every step must use a tool

Bad Example (Inefficient):

{
  "steps": [
    {"title": "Fetch email", "category": "gmail"},
    {"title": "Read email content", "category": "general"},
    {"title": "Analyze sentiment", "category": "general"},
    {"title": "Extract action items", "category": "general"},
    {"title": "Create todo for each item", "category": "todos"},
    {"title": "Log the interaction", "category": "documents"}
  ]
}

Good Example (Optimized):

{
  "steps": [
    {
      "title": "Process email and extract actions",
      "category": "gmail",
      "description": "Get email content and identify action items"
    },
    {
      "title": "Create todos in batch",
      "category": "todos",
      "description": "Create todo items for all extracted actions"
    }
  ]
}

The LLM executing the workflow handles all analysis, understanding, and decision-making. Steps should only describe external tool actions.

Advanced Features

Trigger Context Awareness

# From: apps/api/app/agents/prompts/workflow_prompts.py:358-440

# Email-triggered workflows receive full context:
EMAIL_TRIGGERED_WORKFLOW_PROMPT = """
You are executing a workflow triggered by an email.

EMAIL CONTEXT AVAILABLE:
- From: {email_sender}
- Subject: {email_subject}
- Content: {email_content_preview}
- Received: {trigger_timestamp}

You DON'T need to fetch the email—you already have it!
Focus on USING the email data, not retrieving it.
"""

Dynamic Tool Discovery

# Agents can discover tools at runtime
retrieve_tools(query="send slack message")
# Returns: SLACK_SEND_MESSAGE, SLACK_SEND_DIRECT_MESSAGE, etc.

# Then load specific tools
retrieve_tools(exact_tool_names=["SLACK_SEND_MESSAGE"])

Error Handling

# From: apps/api/app/models/workflow_models.py:221-228

class Workflow(BaseModel):
    current_step_index: int
    execution_logs: List[str]
    error_message: Optional[str]
    
    # Workflows maintain state for recovery
    # Failed steps can be retried
    # User notified of failures

Workflow Categories

Email Management

Auto-label important emails
Create todos from requests
Schedule meetings from proposals
Archive newsletters

Meeting Automation

Prepare meeting briefs
Schedule follow-ups
Send summaries
Track action items

Project Tracking

Sync GitHub issues to Notion
Update status in Slack
Generate weekly reports
Track deadlines

Content Publishing

Draft social posts
Cross-post to platforms
Schedule publications
Track engagement

Data Sync

Sync CRM data
Update spreadsheets
Backup documents
Consolidate reports

Personal Productivity

Morning briefings
Evening reviews
Weekly planning
Habit tracking

Monitoring & Analytics

Execution History

// From: apps/web/src/features/workflows/types/workflowExecutionTypes.ts

interface WorkflowExecution {
  execution_id: string;
  workflow_id: string;
  status: "running" | "success" | "failed";
  started_at: string;
  completed_at?: string;
  duration_seconds?: number;
  conversation_id?: string;  // Links to chat history
  summary?: string;
  error_message?: string;
  trigger_type: string;
}

Performance Metrics

# From: apps/api/app/models/workflow_models.py:230-234

class Workflow(BaseModel):
    total_executions: int
    successful_executions: int
    
    # Calculate success rate
    @property
    def success_rate(self) -> float:
        if self.total_executions == 0:
            return 0.0
        return self.successful_executions / self.total_executions

Best Practices

Workflow Design Tips

Technical Deep Dive

Workflow Service

# From: apps/api/app/agents/tools/workflow_tool.py

class WorkflowService:
    @staticmethod
    async def create_workflow(request, user_id, user_timezone):
        # 1. Validate trigger config
        # 2. Generate steps (if not provided)
        # 3. Calculate next_run for scheduled triggers
        # 4. Register integration webhooks
        # 5. Store in PostgreSQL
        # 6. Index for search
    
    @staticmethod
    async def execute_workflow(workflow_id, context, user_id):
        # 1. Load workflow
        # 2. Build execution prompt with steps
        # 3. Create conversation context
        # 4. Execute via agent (streaming or silent)
        # 5. Track execution history
        # 6. Update statistics

Subagent Router

# From: apps/api/app/agents/prompts/workflow_prompts.py:330-343

# Main agent routes steps to specialized subagents:

if step.category in ["gmail", "notion", "twitter", "linkedin", "calendar"]:
    # Use handoff for provider-specific tools
    handoff(
        subagent_id=step.category,
        task=f"{step.title}: {step.description}"
    )
else:
    # Direct execution for general tools
    retrieve_tools(query=step.description)
    # Call tools directly

Proactive AI - Autonomous execution
Integrations - Connected services
Agents - Specialized executors
Memory System - Learning from executions

Next Steps:

Get Started

Core Concepts

User Guide

Integrations

Self-Hosting

​Workflows

​What Makes GAIA Workflows Different?

AI-Powered Execution

Natural Language Definition

Cross-Integration

Self-Learning

​Architecture Overview

​Workflow Components

​Step Structure

​Trigger Types

​1. Manual Triggers

​2. Scheduled Triggers

​3. Integration Triggers

​Workflow Execution

​Intelligent Execution Flow

​Execution Modes

​Step Execution Example

​Creating Workflows

​Via Natural Language

​From Conversation History

​Workflow Generation Principles

​Ultra-Efficient Steps

​Advanced Features

​Trigger Context Awareness

​Dynamic Tool Discovery

​Error Handling

​Workflow Categories

Email Management

Meeting Automation

Project Tracking

Content Publishing

Data Sync

Personal Productivity

​Monitoring & Analytics

​Execution History

​Performance Metrics

​Best Practices

​Technical Deep Dive

​Workflow Service

​Subagent Router

​Related Concepts

Build docs developers (and LLMs) love

Workflows

What Makes GAIA Workflows Different?

Architecture Overview

Workflow Components

Step Structure

Trigger Types

1. Manual Triggers

2. Scheduled Triggers

3. Integration Triggers

Workflow Execution

Intelligent Execution Flow

Execution Modes

Step Execution Example

Creating Workflows

Via Natural Language

From Conversation History

Workflow Generation Principles

Ultra-Efficient Steps

Advanced Features

Trigger Context Awareness

Dynamic Tool Discovery

Error Handling

Workflow Categories

Monitoring & Analytics

Execution History

Performance Metrics

Best Practices

Technical Deep Dive

Workflow Service

Subagent Router

Related Concepts