.do
ApiAgents

Workflows API

API for orchestrating multi-agent workflows and complex task automation

The Workflows API enables you to orchestrate complex multi-agent workflows with sequential, parallel, and conditional execution patterns. Automate end-to-end processes involving multiple agents and teams.

Base URL

https://api.do/agents/workflows

Overview

Workflow capabilities include:

  • Sequential Execution - Tasks run in order
  • Parallel Execution - Tasks run simultaneously
  • Conditional Logic - Branch based on results
  • Error Handling - Retry, fallback, escalation
  • State Management - Share data between steps
  • Progress Tracking - Monitor execution in real-time

Endpoints

Create Workflow

Create a new workflow definition.

POST /agents/workflows

Request Body

FieldTypeRequiredDescription
namestringYesWorkflow name
descriptionstringNoWorkflow description
stepsarrayYesWorkflow steps
errorHandlingobjectNoError handling strategy
timeoutnumberNoMax execution time (seconds)

Example Request

curl -X POST "https://api.do/agents/workflows" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "SaaS Product Launch Workflow",
    "description": "End-to-end workflow for launching a new SaaS product",
    "steps": [
      {
        "id": "market-research",
        "type": "task",
        "agent": "mira",
        "task": "Conduct market research for SaaS product",
        "output": "research-data"
      },
      {
        "id": "product-strategy",
        "type": "task",
        "agent": "priya",
        "task": "Define product strategy",
        "input": "research-data",
        "output": "strategy-doc"
      },
      {
        "id": "parallel-development",
        "type": "parallel",
        "steps": [
          {
            "id": "backend-dev",
            "agent": "tom",
            "task": "Develop backend",
            "input": "strategy-doc",
            "output": "backend-code"
          },
          {
            "id": "frontend-dev",
            "agent": "rae",
            "task": "Develop frontend",
            "input": "strategy-doc",
            "output": "frontend-code"
          }
        ]
      },
      {
        "id": "testing",
        "type": "task",
        "agent": "quinn",
        "task": "Run comprehensive tests",
        "input": ["backend-code", "frontend-code"],
        "output": "test-results"
      },
      {
        "id": "deploy",
        "type": "task",
        "agent": "dev",
        "task": "Deploy to production",
        "input": ["backend-code", "frontend-code", "test-results"],
        "output": "deployment-url"
      }
    ],
    "errorHandling": {
      "strategy": "retry",
      "maxRetries": 3,
      "escalateOnFailure": true
    },
    "timeout": 604800
  }'

Example Response

{
  "success": true,
  "data": {
    "workflowId": "wf_abc123",
    "name": "SaaS Product Launch Workflow",
    "description": "End-to-end workflow for launching a new SaaS product",
    "steps": [
      {
        "id": "market-research",
        "type": "task",
        "agent": "mira",
        "task": "Conduct market research for SaaS product",
        "output": "research-data"
      },
      {
        "id": "product-strategy",
        "type": "task",
        "agent": "priya",
        "task": "Define product strategy",
        "input": "research-data",
        "output": "strategy-doc"
      },
      {
        "id": "parallel-development",
        "type": "parallel",
        "steps": [
          {
            "id": "backend-dev",
            "agent": "tom",
            "task": "Develop backend",
            "input": "strategy-doc",
            "output": "backend-code"
          },
          {
            "id": "frontend-dev",
            "agent": "rae",
            "task": "Develop frontend",
            "input": "strategy-doc",
            "output": "frontend-code"
          }
        ]
      },
      {
        "id": "testing",
        "type": "task",
        "agent": "quinn",
        "task": "Run comprehensive tests",
        "input": ["backend-code", "frontend-code"],
        "output": "test-results"
      },
      {
        "id": "deploy",
        "type": "task",
        "agent": "dev",
        "task": "Deploy to production",
        "input": ["backend-code", "frontend-code", "test-results"],
        "output": "deployment-url"
      }
    ],
    "status": "draft",
    "createdAt": "2024-10-27T18:00:00Z"
  },
  "metadata": {
    "requestId": "req_wf123",
    "timestamp": "2024-10-27T18:00:00Z"
  }
}

Execute Workflow

Execute a workflow with input data.

POST /agents/workflows/:id/execute

Path Parameters

ParameterTypeRequiredDescription
idstringYesWorkflow identifier

Request Body

FieldTypeRequiredDescription
inputobjectNoInitial workflow input
prioritystringNoExecution priority
notificationsobjectNoNotification settings

Example Request

curl -X POST "https://api.do/agents/workflows/wf_abc123/execute" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "productName": "CloudSync Pro",
      "targetMarket": "SMB businesses",
      "budget": 100000
    },
    "priority": "high",
    "notifications": {
      "email": "[email protected]",
      "slack": "#product-launches"
    }
  }'

Example Response

{
  "success": true,
  "data": {
    "executionId": "exec_xyz789",
    "workflowId": "wf_abc123",
    "workflowName": "SaaS Product Launch Workflow",
    "status": "running",
    "currentStep": "market-research",
    "progress": {
      "completed": 0,
      "total": 5,
      "percentage": 0
    },
    "startedAt": "2024-10-27T18:00:00Z",
    "estimatedCompletion": "2024-11-10T18:00:00Z",
    "trackingUrl": "https://api.do/agents/workflows/executions/exec_xyz789"
  },
  "metadata": {
    "requestId": "req_wf124",
    "timestamp": "2024-10-27T18:00:00Z"
  }
}

Get Execution Status

Get the status of a workflow execution.

GET /agents/workflows/executions/:id

Path Parameters

ParameterTypeRequiredDescription
idstringYesExecution identifier

Example Request

curl -X GET "https://api.do/agents/workflows/executions/exec_xyz789" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "success": true,
  "data": {
    "executionId": "exec_xyz789",
    "workflowId": "wf_abc123",
    "workflowName": "SaaS Product Launch Workflow",
    "status": "running",
    "currentStep": "parallel-development",
    "progress": {
      "completed": 2,
      "total": 5,
      "percentage": 40
    },
    "steps": [
      {
        "id": "market-research",
        "status": "completed",
        "agent": "mira",
        "startedAt": "2024-10-27T18:00:00Z",
        "completedAt": "2024-10-28T14:30:00Z",
        "duration": "20.5 hours",
        "output": {
          "research-data": "https://storage.do/exec_xyz789/research.pdf"
        }
      },
      {
        "id": "product-strategy",
        "status": "completed",
        "agent": "priya",
        "startedAt": "2024-10-28T14:30:00Z",
        "completedAt": "2024-10-29T16:00:00Z",
        "duration": "25.5 hours",
        "output": {
          "strategy-doc": "https://storage.do/exec_xyz789/strategy.pdf"
        }
      },
      {
        "id": "parallel-development",
        "status": "running",
        "steps": [
          {
            "id": "backend-dev",
            "status": "running",
            "agent": "tom",
            "startedAt": "2024-10-29T16:00:00Z",
            "progress": 65
          },
          {
            "id": "frontend-dev",
            "status": "running",
            "agent": "rae",
            "startedAt": "2024-10-29T16:00:00Z",
            "progress": 58
          }
        ]
      },
      {
        "id": "testing",
        "status": "pending"
      },
      {
        "id": "deploy",
        "status": "pending"
      }
    ],
    "startedAt": "2024-10-27T18:00:00Z",
    "estimatedCompletion": "2024-11-10T18:00:00Z"
  },
  "metadata": {
    "requestId": "req_wf125",
    "timestamp": "2024-10-30T12:00:00Z"
  }
}

List Workflows

List all workflows.

GET /agents/workflows

Query Parameters

ParameterTypeRequiredDescription
statusstringNoFilter by status
categorystringNoFilter by category
limitnumberNoMax results (default: 50)
offsetnumberNoPagination offset

Cancel Execution

Cancel a running workflow execution.

POST /agents/workflows/executions/:id/cancel

Path Parameters

ParameterTypeRequiredDescription
idstringYesExecution identifier

Example Request

curl -X POST "https://api.do/agents/workflows/executions/exec_xyz789/cancel" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Requirements changed"
  }'

Pause Execution

Pause a running workflow execution.

POST /agents/workflows/executions/:id/pause

Resume Execution

Resume a paused workflow execution.

POST /agents/workflows/executions/:id/resume

Retry Failed Step

Retry a failed workflow step.

POST /agents/workflows/executions/:id/steps/:stepId/retry

Workflow Step Types

Task Step

Execute a single agent task:

{
  "id": "analysis",
  "type": "task",
  "agent": "amy",
  "task": "Analyze data",
  "input": "raw-data",
  "output": "analysis-results"
}

Parallel Step

Execute multiple tasks simultaneously:

{
  "id": "parallel-work",
  "type": "parallel",
  "steps": [
    { "id": "task1", "agent": "tom", "task": "..." },
    { "id": "task2", "agent": "rae", "task": "..." }
  ]
}

Conditional Step

Branch based on conditions:

{
  "id": "conditional",
  "type": "conditional",
  "condition": "test-results.passed === true",
  "then": {
    "id": "deploy",
    "agent": "dev",
    "task": "Deploy to production"
  },
  "else": {
    "id": "fix",
    "agent": "tom",
    "task": "Fix failing tests"
  }
}

Loop Step

Repeat a task multiple times:

{
  "id": "process-items",
  "type": "loop",
  "items": "data-array",
  "step": {
    "id": "process",
    "agent": "amy",
    "task": "Process item"
  }
}

Team Step

Assign to a team:

{
  "id": "team-project",
  "type": "team",
  "teamId": "engineering",
  "task": "Build feature",
  "input": "requirements",
  "output": "completed-feature"
}

TypeScript SDK Example

import { $ } from 'sdk.do'

// Create workflow
const workflow = await $.Workflow.create({
  name: 'SaaS Product Launch',
  description: 'End-to-end product launch',
  steps: [
    {
      id: 'research',
      type: 'task',
      agent: 'mira',
      task: 'Market research',
      output: 'research-data',
    },
    {
      id: 'strategy',
      type: 'task',
      agent: 'priya',
      task: 'Product strategy',
      input: 'research-data',
      output: 'strategy-doc',
    },
    {
      id: 'development',
      type: 'parallel',
      steps: [
        {
          id: 'backend',
          agent: 'tom',
          task: 'Backend dev',
          input: 'strategy-doc',
        },
        {
          id: 'frontend',
          agent: 'rae',
          task: 'Frontend dev',
          input: 'strategy-doc',
        },
      ],
    },
  ],
})

// Execute workflow
const execution = await $.Workflow.execute({
  workflowId: workflow.workflowId,
  input: {
    productName: 'CloudSync Pro',
    targetMarket: 'SMB',
  },
  priority: 'high',
})

// Monitor execution
const status = await $.Workflow.getExecution(execution.executionId)
console.log(`Status: ${status.status}`)
console.log(`Progress: ${status.progress.percentage}%`)
console.log(`Current step: ${status.currentStep}`)

// Cancel execution
await $.Workflow.cancel(execution.executionId, {
  reason: 'Requirements changed',
})

// Retry failed step
if (status.steps.some((s) => s.status === 'failed')) {
  const failedStep = status.steps.find((s) => s.status === 'failed')
  await $.Workflow.retryStep(execution.executionId, failedStep.id)
}

Python SDK Example

from do_sdk import Workflow

# Create workflow
workflow = Workflow.create(
    name='SaaS Product Launch',
    description='End-to-end product launch',
    steps=[
        {
            'id': 'research',
            'type': 'task',
            'agent': 'mira',
            'task': 'Market research',
            'output': 'research-data'
        },
        {
            'id': 'strategy',
            'type': 'task',
            'agent': 'priya',
            'task': 'Product strategy',
            'input': 'research-data',
            'output': 'strategy-doc'
        }
    ]
)

# Execute workflow
execution = Workflow.execute(
    workflow_id=workflow.workflow_id,
    input={
        'productName': 'CloudSync Pro',
        'targetMarket': 'SMB'
    },
    priority='high'
)

# Monitor execution
status = Workflow.get_execution(execution.execution_id)
print(f'Status: {status.status}')
print(f'Progress: {status.progress.percentage}%')

CLI Example

# Create workflow from file
do workflow create workflow.json

# Execute workflow
do workflow execute wf_abc123 \
  --input '{"productName":"CloudSync","targetMarket":"SMB"}' \
  --priority high

# Get execution status
do workflow execution exec_xyz789

# List workflows
do workflow list

# Cancel execution
do workflow cancel exec_xyz789 --reason "Requirements changed"

# Retry step
do workflow retry exec_xyz789 backend-dev

Best Practices

1. Design for Failure

Include error handling and retry logic:

const workflow = await $.Workflow.create({
  name: 'Resilient Workflow',
  steps: [
    /* ... */
  ],
  errorHandling: {
    strategy: 'retry',
    maxRetries: 3,
    backoff: 'exponential',
    escalateOnFailure: true,
    notifyOnError: true,
  },
})

2. Optimize with Parallelism

Run independent tasks in parallel:

// Good: Parallel execution
{
  type: 'parallel',
  steps: [
    { agent: 'tom', task: 'Backend' },
    { agent: 'rae', task: 'Frontend' },
    { agent: 'max', task: 'Design' }
  ]
}

// Bad: Sequential when parallel possible
[
  { agent: 'tom', task: 'Backend' },
  { agent: 'rae', task: 'Frontend' }, // Waits for backend
  { agent: 'max', task: 'Design' }     // Waits for frontend
]

3. Share Data Efficiently

Use step outputs as inputs:

const workflow = await $.Workflow.create({
  steps: [
    {
      id: 'step1',
      agent: 'amy',
      task: 'Analyze data',
      output: 'analysis', // Named output
    },
    {
      id: 'step2',
      agent: 'priya',
      task: 'Create strategy',
      input: 'analysis', // References step1 output
    },
  ],
})

4. Monitor Progress

Track workflow execution:

const execution = await $.Workflow.execute({ workflowId: 'wf_abc123' })

// Poll for updates
const interval = setInterval(async () => {
  const status = await $.Workflow.getExecution(execution.executionId)
  console.log(`Progress: ${status.progress.percentage}%`)

  if (status.status === 'completed') {
    clearInterval(interval)
    console.log('Workflow completed!')
  }
}, 30000)

Support

On this page

Base URLOverviewEndpointsCreate WorkflowRequest BodyExample RequestExample ResponseExecute WorkflowPath ParametersRequest BodyExample RequestExample ResponseGet Execution StatusPath ParametersExample RequestExample ResponseList WorkflowsQuery ParametersCancel ExecutionPath ParametersExample RequestPause ExecutionResume ExecutionRetry Failed StepWorkflow Step TypesTask StepParallel StepConditional StepLoop StepTeam StepTypeScript SDK ExamplePython SDK ExampleCLI ExampleBest Practices1. Design for Failure2. Optimize with Parallelism3. Share Data Efficiently4. Monitor ProgressRelated DocumentationSupport