Workflow Support

[zrosenbauer]

Overview

This proposal introduces a new Workflow primitive to VoltAgent that enables deterministic, sequential execution of agents and functions. This addresses use cases where the current supervisor/subagent architecture may not be the optimal solution.

Problem Statement

Current challenges with existing patterns:

• Supervisor/Subagent Architecture: While powerful for complex reasoning, it can introduce chaos and waste tokens for deterministic, sequential tasks
• Missing Sequential Execution: Need for ordered, step-by-step workflows with predictable outputs
• Limited Linear Processing: Lack of native support for linear data processing pipelines
• Integration Complexity: Difficulty integrating with external providers and services

Proposed Solution

Core Concept

A Workflow is fundamentally an array of functions that execute sequentially, passing data along and potentially mutating it. Each step in the workflow receives the output of the previous step.

Key Features

1. Chaining API

Use a chaining approach that is similar to other "pipe" like syntaxes and is also a semi-standard syntax for similar libraries.

Example

const workflow = createWorkflow({
  // define strict schemas
  input: z.object({
    something: z.object({
      barfoo: z.string(),
      foobar: z.number(),
    }),
  }),
  output: z.object({
    foo: z.object({
      bar: z.number(),
    }),
  }),
})
  .andThen(agent)
  .andThen(agent)
  .andThen([agent, agent]) // parallel execution
  .andThen(c => combine(c)) // since its parallel above, it will return an array and will need to be combined (most likely)
  .andThen(otherWorkflow)  // workflows can be nested
  .when((data) => isString(data), agent) // conditional execution
  .andFinally((c) => c); // final step and chance to modify the output if function is omitted its just a pass through

const result = await workflow.run({
  something: {
    barfoo: 'barfoo',
    foobar: 1,
  },
});

Optional Functional Approach

const workflow = createWorkflow(
  andThen(agent),
  andThen(agent),
  parallel([agent, agent]),
  andThen(otherWorkflow),
  when((data) => isString(data), agent)
);

2. Flexible Step Types

• Agents: VoltAgent instances
• Workflows: Nested workflows (treated as single steps)
• AsyncFunction: Regular TypeScript functions with uniform I/O
• Parallel Execution: Multiple steps running concurrently

3. Conditional Logic

Allow for "branching" by using "when" and "with" similar to in ts-pattern library.

Example

const workflow = createWorkflow(...)
  .andThen(agent)
  .andThen(apiCallToSomething)
  .with({ input: { type: 'ranger' } }, agent)
  .when(() => true, agent)
  .andThen(agent)
  .andFinally();

4. Workflows as Subagents (OPTIONAL => needs R&D)

A workflow can act as a subagent (FYI will require serious modification of core). This will allow us to create N number of potential flows and create VERY powerful supervisors

Example

import { myWorkflow } from './my-workflow';

new Agent({
  ...
  subagents: [agent1, agent2, myWorkflow]
})

Future: Graph Support

The Workflow primitive could be leveraged to build complex network/graphs of agents that interconnect.

Since each workflow is just a series of functions to execute with a standard output, we could then construct an additional non-linear abstraction.

Note

This section is NOT well thought out more of a recognition of a possible future and why we should think carefully about the design

Use Cases

• Data Processing Pipelines: Sequential transformation of data
• Content Generation: Multi-step content creation workflows
• Integration Workflows: Connecting multiple external services
• Validation Chains: Sequential validation and processing steps

Technical Implementation

Core Architecture

Rough concept:

class Workflow {
  public andThen(input: Agent | Agent[] | Workflow | Function): this
  public when(condition: Function, then: Agent | Workflow): this
  public parallel(steps: (Agent | Workflow | Function)[]): this
  public ready(): WorkflowRunner
}

class WorkflowRunner {
  public async generateObject(options?: { schema?: any }): Promise<any>
  public async generate(): Promise<string>
}

Shared Context

• Each step has access to shared context (similar to operationContext)
• Context is passed through the entire workflow chain
• Type-safe shared state management

Uniform I/O

TBD

Questions for Discussion

1. API Design: Preference between chaining vs. functional approach?
2. Step Types: Should we support all function types or restrict to specific interfaces?
3. Error Handling: How should workflow errors be handled and propagated?
4. State Management: Should shared state be mutable or immutable?
5. Integration: Which external providers should we prioritize for integration?

---

Conversation Summary & Findings from PR #193

NOTE: as generated using Joggr's AI 😉

Key Determinations

Core Philosophy

• Workflows are NOT graphs: The intention is to create a linear, sequential execution primitive, not a graph-based system
• Complementary to Supervisor/Subagent: This is a new VoltAgent primitive that doesn't replace the existing architecture but provides an alternative for appropriate use cases
• Array of Functions: At its core, a workflow is simply an array of functions that execute sequentially and pass data along

API Design Consensus

• Chaining Preferred: The chaining API (createWorkflow().andThen()) is the preferred approach over functional composition
• Uniform I/O: All steps (agents, workflows, functions) should have uniform input/output interfaces
• Type Safety: Full TypeScript support with type-safe shared context access

Technical Decisions

• Shared Context: Each step should have access to the same context (similar to operationContext)
• Flexible Step Types: Support for agents, workflows, and regular functions
• Provider Integration: Need solid integration with external providers (e.g., Vercel's dataWriter)

Community Feedback Themes

Positive Reception

• @omeraplak: "Cool feature set, looks solid for a first version"
• General consensus: Need for deterministic, sequential workflows acknowledged

Concerns & Comparisons

• ouj: Expressed concerns based on negative experience with Mastra workflows, particularly around graph complexity
• Community preference: Avoid the complexity that made Mastra workflows difficult to use

Feature Requests

• Conditional Logic: Support for when conditions and routing
• Parallel Execution: Ability to run multiple steps in parallel
• Regular Functions: Support for non-agent functions in workflows
• Nested Workflows: Ability to compose workflows within workflows

Architecture Questions

• @baseballyama: Questioned distinction between "step" and "parallel" - suggested always accepting arrays
• @vikyw89: Advocated for LangGraph-style shared state management
• General discussion: How to handle input/output matching between steps

[zrosenbauer]

@omeraplak @vikyw89 @baseballyama @ouj any additional thoughts?

My plan is to start executing on this next week or week after. Most likely it will be something I build internally @joggrdocs but will extract into something reusable.

[omeraplak]

Sounds like a solid plan to me! Thank you

[vikyw89]

I just saw this,

this proposal looks good !

[baseballyama]

Overall, I propose an alternative API from two perspectives:

• Tree-shakeable API
• Leveraging native JavaScript APIs

By minimizing the API surface of VoltAgent as much as possible, users gain greater flexibility with minimal additional learning cost.
Additionally, the following proposal treats the data structure itself as a tree.

const workflow = createWorkflow([
  // basic usage
  agent,
  // with current context
  (context) => agent2(context),
  // condition step
  () => {
    if (foo) return workflow1;
    // early return from the workflow
    return end();
  },
  // parallel step. every array items run in parallel.
  parallel([
    agent,
    (context) => agent(context),
    // nested parallel
    parallel([tool1, too12]),
  ]),
  // loop
  (context) => {
    return context.items.map((item) => {
      return tool3(item)
    }
  },
  // parallel loop
  (context) => {
    return parallel(
      context.items.map((item) => {
        return tool3(item)
      }
    )
  },
  // Advanced: Tree-structured Workflow
  // agent -- tool1 - tool2 - 
  //       |                 |- tool5 - tool6
  //       |- tool3 - tool4 -
  [
    agent,
    () => {
      if (foo) return [tool1, tool2, subTree];
      return [tool3, tool4, subTree]
    }
  ]
]);

const subTree = [tool5, tool6];

• API Design: Preference between chaining vs. functional approach?

To enable tree-shaking, I prefer a functional approach.

• Step Types: Should we support all function types or restrict to specific interfaces?

As a general principle, as long as it’s type-safe, I feel it shouldn’t be restricted.

• Error Handling: How should workflow errors be handled and propagated?

It seems sufficient to simply throw like a VoltAgentWorkflowError and handle it with try/catch in userland.

• State Management: Should shared state be mutable or immutable?

To make debugging easier, I believe it should be immutable. That way, we can review the result of each step afterward and easily trace where things went wrong.

• Integration: Which external providers should we prioritize for integration?

As for this part, I’m not sure how difficult it is to support each provider. If it’s very challenging, it might make sense to prioritize based on factors like each package’s npm download count.
Speaking personally, I’d like to get it working with Azure OpenAI Service first.

[baseballyama]

Workflows are inherently tree-structured, so I feel that method chaining has limitations in terms of expressiveness.
Alternatively, one possible approach could be to provide a tree-shakable API as a first-class citizen and offer a method-chaining API as a wrapper around it.
In any case, completely giving up on tree-shaking feels like a huge waste.

[zrosenbauer]

@omeraplak @baseballyama I actually don't mind this approach at all...

[zrosenbauer]

@baseballyama one thing though from the above approach, I really think we should force the definition of the I / O aka output / input schema.

Otherwise we're passing the type checking to the end user

[vikyw89]

I don't quite understand in depth about tree-shaking. From what I understand it's a concern for browser / client type package - and esm modules are treeshakeable by default.

On the other hand, volt agent is meant to be run server side - tree shakeable is not a priority, right ?

Also I kinda prefer using . for chaining instead of functional. Simply because the lsp support for . chaining is better than the support for class import (if there's any).

[zrosenbauer]

@vikyw89 there is not reason we can't support both APIs as the class is just a wrapper for chaining.

[omeraplak]

The big day is here! The workflow is live!
https://voltagent.dev/docs/workflows/overview/

We're awaiting your feedback! Thank you everyone!