v0.5.2 release - Contributors, Sponsors and Enquiries are most welcome 😌

Workflows

Workflows enable multi-agent orchestration, allowing you to coordinate multiple agents to solve complex tasks through sequential, parallel, or supervised execution patterns.

What are Workflows?

Workflows coordinate multiple agents to work together on complex tasks. AgentSea supports three workflow patterns:

➡️

Sequential

Agents execute one after another, passing output as input

⚡

Parallel

All agents execute simultaneously and results are combined

👔

Supervisor

A supervisor routes tasks dynamically to specialized agents

Sequential Workflows

Agents execute one after another, with each agent's output becoming the next agent's input.

typescript
import {
  WorkflowFactory,
  AnthropicProvider,
  ToolRegistry,
} from '@lov3kaizen/agentsea-core';
import type { WorkflowConfig, WorkflowType } from '@lov3kaizen/agentsea-types';

const workflow = WorkflowFactory.create(
  {
    name: 'content-pipeline',
    type: 'sequential',
    agents: [
      {
        name: 'researcher',
        model: 'claude-sonnet-4-20250514',
        provider: 'anthropic',
        systemPrompt: 'Research the topic and gather information.',
        tools: [httpRequestTool],
      },
      {
        name: 'writer',
        model: 'claude-sonnet-4-20250514',
        provider: 'anthropic',
        systemPrompt: 'Write a comprehensive article based on the research.',
      },
      {
        name: 'editor',
        model: 'claude-sonnet-4-20250514',
        provider: 'anthropic',
        systemPrompt: 'Edit and polish the article for publication.',
      },
    ],
  },
  new AnthropicProvider(),
  new ToolRegistry(),
);

// Execute workflow
const result = await workflow.execute(
  'Write an article about AI agents',
  context,
);

console.log(result.content); // Final edited article

Parallel Workflows

All agents execute simultaneously, and their results are aggregated.

typescript
const workflow = WorkflowFactory.create(
  {
    name: 'multi-analysis',
    type: 'parallel',
    agents: [
      {
        name: 'sentiment-analyzer',
        model: 'claude-sonnet-4-20250514',
        provider: 'anthropic',
        systemPrompt: 'Analyze the sentiment of the text.',
      },
      {
        name: 'keyword-extractor',
        model: 'claude-sonnet-4-20250514',
        provider: 'anthropic',
        systemPrompt: 'Extract key topics and keywords.',
      },
      {
        name: 'summarizer',
        model: 'claude-sonnet-4-20250514',
        provider: 'anthropic',
        systemPrompt: 'Create a concise summary.',
      },
    ],
  },
  new AnthropicProvider(),
  new ToolRegistry(),
);

// All agents run in parallel
const result = await workflow.execute(
  'Analyze this product review: ...',
  context,
);

// Result contains combined output from all agents
console.log(result.content);

Supervisor Workflows

A supervisor agent dynamically routes tasks to specialized worker agents based on the input.

typescript
const workflow = WorkflowFactory.create(
  {
    name: 'customer-support',
    type: 'supervisor',
    supervisor: {
      name: 'routing-agent',
      model: 'claude-sonnet-4-20250514',
      provider: 'anthropic',
      systemPrompt: `You are a routing supervisor. Analyze the request and:
- Route technical questions to 'technical-support'
- Route billing questions to 'billing-support'
- Route general questions to 'general-support'

Respond with ONLY the agent name to route to.`,
    },
    agents: [
      {
        name: 'technical-support',
        model: 'claude-sonnet-4-20250514',
        provider: 'anthropic',
        systemPrompt: 'Provide technical support and troubleshooting.',
        tools: [databaseQueryTool],
      },
      {
        name: 'billing-support',
        model: 'claude-sonnet-4-20250514',
        provider: 'anthropic',
        systemPrompt: 'Handle billing and payment inquiries.',
        tools: [paymentApiTool],
      },
      {
        name: 'general-support',
        model: 'claude-sonnet-4-20250514',
        provider: 'anthropic',
        systemPrompt: 'Provide general customer support.',
      },
    ],
    maxRounds: 3, // Prevent infinite loops
  },
  new AnthropicProvider(),
  new ToolRegistry(),
);

// Supervisor routes to appropriate agent
const result = await workflow.execute(
  'My credit card payment failed',
  context,
);

Error Handling

Configure how workflows handle errors:

typescript
const workflow = WorkflowFactory.create(
  {
    name: 'resilient-workflow',
    type: 'sequential',
    agents: [...],
    errorHandling: {
      strategy: 'continue', // 'stop', 'continue', or 'retry'
      maxRetries: 3,
      retryDelay: 1000, // milliseconds
    },
  },
  provider,
  toolRegistry,
);

try {
  const result = await workflow.execute(input, context);
  console.log(result);
} catch (error) {
  console.error('Workflow failed:', error);
}

Workflow Context

Pass data between agents using workflow context:

typescript
const context = {
  conversationId: 'workflow-123',
  sessionData: {
    userId: '12345',
    userPreferences: {
      language: 'en',
      timezone: 'UTC',
    },
  },
  history: [], // Conversation history
};

// In sequential workflows, output from one agent
// becomes input to the next agent automatically
const result = await workflow.execute('Create a report', context);

// Access workflow metadata
console.log(result.metadata.agentsUsed);
console.log(result.metadata.executionTime);
console.log(result.metadata.tokensUsed);

Streaming Workflows

Stream results in real-time as agents process:

typescript
const stream = await workflow.stream(
  'Analyze this data',
  context,
);

for await (const chunk of stream) {
  if (chunk.type === 'agent_start') {
    console.log(`Starting agent: ${chunk.agentName}`);
  } else if (chunk.type === 'content') {
    process.stdout.write(chunk.content);
  } else if (chunk.type === 'agent_complete') {
    console.log(`\nCompleted agent: ${chunk.agentName}`);
  }
}

Dynamic Agent Selection

Create workflows where agents are selected dynamically:

typescript
import { SupervisorWorkflow } from '@lov3kaizen/agentsea-core';

const workflow = new SupervisorWorkflow(
  {
    name: 'dynamic-workflow',
    supervisor: supervisorAgent,
    agents: [
      codeReviewAgent,
      bugFixAgent,
      documentationAgent,
    ],
    routingStrategy: 'conditional', // or 'round-robin'
    maxRounds: 5,
  },
  provider,
  toolRegistry,
);

// Supervisor will route based on the input
const result = await workflow.execute(
  'Review this pull request and fix any bugs',
  context,
);

Workflow Factory

Use the factory for simplified workflow creation:

typescript
import { WorkflowFactory } from '@lov3kaizen/agentsea-core';

// Factory handles provider and tool registry setup
const workflow = WorkflowFactory.create(
  {
    name: 'my-workflow',
    type: 'sequential', // 'parallel' or 'supervisor'
    agents: [
      // Agent configurations
    ],
  },
  new AnthropicProvider(),
  new ToolRegistry(),
);

// Factory creates appropriate workflow type automatically
// - SequentialWorkflow for type: 'sequential'
// - ParallelWorkflow for type: 'parallel'
// - SupervisorWorkflow for type: 'supervisor'

Use Cases

Sequential Workflows

  • Content creation pipelines (research → write → edit)
  • Data processing (extract → transform → load)
  • Multi-step analysis (collect → analyze → report)

Parallel Workflows

  • Multi-perspective analysis (sentiment + keywords + summary)
  • Competitive research (analyze multiple competitors)
  • A/B testing (generate multiple variations)

Supervisor Workflows

  • Customer support routing
  • Dynamic task delegation
  • Multi-round problem solving

Best Practices

  • Agent Specialization: Give each agent a clear, focused role
  • System Prompts: Write specific system prompts for each agent's task
  • Error Handling: Configure appropriate error strategies for your use case
  • Round Limits: Set maxRounds in supervisor workflows to prevent infinite loops
  • Context Management: Use sessionData to pass relevant context between agents
  • Monitoring: Track workflow execution metrics and token usage
  • Testing: Test workflows with various inputs to ensure proper routing

Next Steps