Workflows allow you to orchestrate multiple agents, and these workflows can be called externally via APIs at any time. In this guide, we will walk you through the steps.

​
Quick steps to execute Workflows externally

​
Step 1: Design Your Workflow in Agent Studio UI

What You’re Doing: Creating your workflow visually instead of writing complex JSON manually. Why This Matters: The Agent Studio visual builder automatically generates the correct JSON structure for you - no need to understand complex workflow syntax or risk JSON errors. How to Do It:
  1. Open Agent Studio visual workflow builder
  2. Drag and drop nodes (agents, APIs, conditionals) onto the canvas
  3. Connect nodes with lines to define the flow
  4. Configure each node’s parameters in the UI
  5. CRITICAL: Click on Workflow API
  6. Copy the entire workflow_data JSON structure

​
Step 2: Execute Your Workflow via run-dag API

What You’re Doing: Taking the JSON from Step 1 and executing it with real data. Why This Matters: This is where your visual workflow becomes a running process that does actual work (processes data, calls APIs, makes decisions). How to Do It: 
curl -X POST "https://lao.studio.lyzr.ai/run-dag/" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_data": {
      // PASTE THE COMPLETE JSON FROM STEP 1 HERE
      // Everything from "Export JSON" goes here
      "tasks": [
        {
          "name": "process_data",
          "function": "agent", 
          "params": {
            "config": {
              "agent_id": "your_agent_id",
              "api_key": "your_agent_key"
            },
            "query": "Process this customer inquiry"
          }
        }
      ],
      "flow_name": "Quick_Test",
      "run_name": "test_001"
    },
    "inputs": {
      // These are the runtime values - what your workflow processes
      "user_input": "Hello world",
      "customer_email": "user@company.com"
    }
  }'
What Happens: The workflow engine executes each node in the correct order, passing data between them, and returns the final results. Key Points:
  • workflow_data: The complete JSON from your visual builder (Step 1)
  • inputs: The actual data you want to process (overrides default values)
  • Response contains the results from each node in your workflow

​
Step 3: Monitor Execution with WebSocket Events

What You’re Doing: Getting real-time updates as your workflow runs. Why This Matters: For enterprise use, you need to know immediately when workflows complete, fail, or need attention. Don’t wait for polling - get instant notifications. How to Do It: 
// Connect to the specific workflow execution
const ws = new WebSocket('wss://lao-socket.studio.lyzr.ai/ws/Quick_Test/test_001');

ws.onopen = () => {
  console.log('✅ Connected - monitoring workflow execution');
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log(`${data.event_type}: ${data.task_name}`);
  
  // Handle different event types
  switch(data.event_type) {
    case 'task_completed':
      console.log('Node finished:', data.output);
      break;
    case 'flow_completed':
      console.log('🎉 Workflow done! Results:', data.output);
      // Process final results, update UI, notify users
      break;
    case 'task_failed':
      console.error('❌ Node failed:', data.error);
      // Handle errors, retry, alert ops team
      break;
  }
};

ws.onerror = (error) => {
  console.error('WebSocket error:', error);
};
What You Get:
  • Real-time progress updates as each node executes
  • Immediate error notifications if something fails
  • Final results as soon as the workflow completes
  • Ability to update users and trigger other systems instantly

​
Executing workflow via run-dag Endpoint

What This Is: The core API endpoint that takes your visual workflow and executes it with real data. URL: https://lao.studio.lyzr.ai/run-dag/
Method: POST
Purpose: Execute any workflow with real-time monitoring Why You Use This: This is where your designed workflow becomes a running automation that processes data, calls APIs, makes decisions, and produces results.

​
Request Structure Explained

{
  "workflow_data": {
    // This entire block comes from Agent Studio's "Export JSON"
    "tasks": [...],           // Your workflow nodes (agents, APIs, etc.)
    "flow_name": "string",    // Workflow name from Studio
    "run_name": "string",     // Unique execution ID (you choose this)
    "default_inputs": {...},  // Default values from input nodes
    "edges": [...]            // How nodes connect (auto-generated)
  },
  "inputs": {
    // The actual data you want to process RIGHT NOW
    "customer_message": "Help with billing",
    "priority": "high"
  }
}
Key Concept:
  • workflow_data = Your workflow template (same every time)
  • inputs = The specific data for THIS execution (changes each time)

​
How to Get workflow_data JSON

🎯 Method 1: Agent Studio Visual Builder ⭐ Always Use This What You’re Doing: Getting the perfect JSON without any manual work. Step-by-Step:
  1. Open Agent Studio workflow builder
  2. Design your workflow visually (drag, drop, connect nodes)
  3. Click “Export JSON” or “Get API Code” button in the UI
  4. Copy the ENTIRE workflow_data JSON structure
  5. Paste it into your API calls
Why This Works: The visual builder generates syntactically perfect, validated JSON that includes all the complex node configurations, dependencies, and connections.
🔧 Method 2: Workflow Management API (For Existing Workflows) What You’re Doing: Retrieving a workflow you already created and saved. 
# Get existing workflow JSON
curl -X GET "{BASE_URL}/v3/workflows/{flow_id}" \
  -H "x-api-key: YOUR_API_KEY"

# The response contains a 'flow_data' field
# Use that flow_data as your workflow_data in run-dag calls
When You Use This: When you have workflows already saved in the system and want to execute them programmatically.
❌ Method 3: Manual Construction (NEVER Do This) What This Means: Writing the complex JSON structure by hand. Why You Don’t Do This:
  • Extremely complex JSON structure with nested dependencies
  • Easy to make syntax errors that break execution
  • Hard to maintain and debug
  • The visual builder does this perfectly for you
Exception: Only for very simple, single-node workflows for testing.

​
Response Structure

Initial Response (Immediate): 
{
  "status": "processing",
  "task_id": "0d3c400a-d35b-43db-9e9f-655d857d8594"
}
What This Means:
  • Your workflow has been accepted and is now running
  • Use the task_id to track the execution
  • Connect to WebSocket using your flow_name and run_name to monitor progress
  • The workflow continues executing asynchronously
Final Results (via WebSocket): 
{
  "event_type": "flow_completed",
  "status": "completed",
  "results": {
    "node_name": { "output": "..." }
  },
  "execution_time": 12.34,
  "task_id": "0d3c400a-d35b-43db-9e9f-655d857d8594"
}

​
Getting Final Results via Task Status API

What This Is: An alternative way to get workflow results after execution completes, using the task_id from the initial response. When to Use This:
  • When you can’t use WebSocket connections (firewall restrictions, etc.)
  • When you need to retrieve results later (hours/days after execution)
  • As a backup method to ensure you capture results

​
Task Status Endpoint

URL: https://lao.studio.lyzr.ai/task-status/{task_id}
Method: GET
Purpose: Retrieve the final results of a completed workflow

​
Example Request

curl -X 'GET' \
  'https://lao.studio.lyzr.ai/task-status/0d3c400a-d35b-43db-9e9f-655d857d8594' \
  -H 'accept: application/json'

​
Response While Processing

Important: This endpoint returns processing status while the workflow is still running. You’ll need to poll periodically or use WebSocket for real-time updates. 
{
  "status": "processing",
  "task_id": "0d3c400a-d35b-43db-9e9f-655d857d8594"
}

​
Response After Completion

Once the workflow finishes, you get the complete results from all nodes: 
{
  "status": "completed",
  "results": {
    "agent_yellowidea": "Theme Prompt: Imagine a clandestine society of cats who, by moonlight and under carpets, have taught themselves the art of software development. Their paws dance across glowing keyboards, creating code laced with feline curiosity and the occasional mischievous bug. Explore their secret workshops, the tangled wires, the hush of concentration, and the whimsical programs they dream up to make human lives—and their own—a little more magical and mysterious.",
    "agent_yellowpoem": "**Moonlit Debuggers**\n\nBeneath the velvet hush of midnight floor,\nBetween the gold-eyed glances and the hush\nOf sleeping houses, tail-tips prick and paws\nUnspool carpet corners—whiskered hush—\nThe secret signal, \"Code. The moon is up.\"\n\n[... full poem content ...]",
    "agent_yellowpoet": "**Moonlit Debuggers**\n\nBeneath the velvet hush of midnight floors,\nBetween gold-eyed glances and the pause\nOf sleeping houses, tail-tips prick and paws\n[... full poem content ...]"
  }
}
What You Get:
  • status: Either “processing” or “completed”
  • results: Object containing output from each node (keyed by node name)
  • Each node’s complete output data

​
Polling Pattern Example

async function getWorkflowResults(taskId, maxAttempts = 30) {
  const url = `https://lao.studio.lyzr.ai/task-status/${taskId}`;
  
  for (let i = 0; i < maxAttempts; i++) {
    try {
      const response = await fetch(url, {
        headers: { 'accept': 'application/json' }
      });
      
      const data = await response.json();
      
      if (data.status === 'completed') {
        console.log('✅ Workflow completed!');
        return data.results;
      } else if (data.status === 'failed') {
        console.error('❌ Workflow failed:', data.error);
        throw new Error(data.error);
      }
      
      // Still processing, wait before retry
      console.log(`⏳ Still processing... (attempt ${i + 1}/${maxAttempts})`);
      await new Promise(resolve => setTimeout(resolve, 2000)); // Wait 2 seconds
      
    } catch (error) {
      console.error('Error fetching task status:', error);
      throw error;
    }
  }
  
  throw new Error('Workflow did not complete within timeout period');
}

// Usage
const taskId = '0d3c400a-d35b-43db-9e9f-655d857d8594';
getWorkflowResults(taskId)
  .then(results => {
    console.log('Final results:', results);
    // Process each node's output
    Object.entries(results).forEach(([nodeName, output]) => {
      console.log(`${nodeName}:`, output);
    });
  })
  .catch(error => console.error('Failed to get results:', error));