Workflow Support

[omeraplak]

1. Overview:*

Enable users to define, execute, and monitor complex, multi-step processes involving multiple agents. Workflows allow orchestrating agents where the output of one agent step can serve as the input for subsequent steps, potentially involving conditional logic, branching, and parallel execution. This feature will significantly enhance the capability of voltagent to handle sophisticated tasks requiring agent collaboration.

2. Goals:

• Provide a clear and flexible mechanism for defining workflows (e.g., using a declarative format like YAML/JSON or a programmatic API).
• Implement a robust Workflow Engine capable of parsing definitions and managing the execution lifecycle of workflow instances.
• Enable seamless data passing between different agent steps within a workflow.
• Offer comprehensive monitoring and logging for workflow execution, status, and potential errors.
• Integrate workflow management into the existing voltagent ecosystem (e.g., VoltAgent, AgentRegistry, AgentEventEmitter).
• Ensure fault tolerance and provide basic error handling strategies (e.g., retry, failure notification).

3. Proposed Architecture & Components:

• WorkflowDefinition: A data structure (or class) representing the static definition of a workflow. This will include:
  • Workflow ID and metadata.
  • A graph or sequence of WorkflowStep nodes.
  • Definitions for data flow between steps (input/output mapping).
  • Conditional logic definitions (if applicable).
• WorkflowStep: Represents a single unit of work within a workflow, typically involving a call to a specific Agent. Contains:
  • Step ID.
  • Target Agent ID (to be resolved via AgentRegistry).
  • Input mapping configuration (how to construct the agent's input from workflow state or previous step outputs).
  • Output mapping configuration (how to store the agent's output in the workflow state).
  • Error handling configuration (e.g., retry count, fallback step).
• WorkflowManager: A central service (potentially integrated with VoltAgent or running independently) responsible for:
  • Loading and validating WorkflowDefinitions.
  • Instantiating and executing workflows (WorkflowInstance).
  • Managing the lifecycle and state of active WorkflowInstances.
  • Interacting with AgentRegistry to locate and invoke agents.
  • Persisting workflow state (potentially leveraging or extending MemoryManager or using a dedicated store).
• WorkflowInstance: Represents a single, running execution of a WorkflowDefinition. Contains:
  • Instance ID.
  • Reference to the WorkflowDefinition.
  • Current execution state (e.g., current step, status - running, completed, failed).
  • Intermediate data and outputs from completed steps.
  • Execution history/log.
• Workflow Events: Extend AgentEventEmitter or create a dedicated event stream for workflow-specific events (e.g., workflow_started, step_started, step_completed, step_failed, workflow_completed, workflow_failed). This integrates with the existing monitoring infrastructure.

4. Affected Core Modules:

• AgentRegistry: Will be used by WorkflowManager to look up agents.
• Agent: Agent methods will be invoked by the workflow engine. Input/output consistency is crucial.
• AgentEventEmitter: Needs to be extended or used to emit workflow-level events for monitoring.
• MemoryManager: Might be leveraged for storing intermediate workflow data or state.
• server: API endpoints for workflow management will be added.

5. Acceptance Criteria (Initial MVP):

• Users can define a simple sequential workflow involving two agents using a YAML or JSON format.
• The WorkflowManager can parse the definition and execute the workflow.
• Data output from the first agent step is correctly passed as input to the second agent step.
• Workflow start, step completion, and workflow completion/failure events are emitted via AgentEventEmitter.
• The final status (completed/failed) of the workflow instance can be retrieved.
• Basic documentation outlines how to create and run a two-step workflow.

6. Potential Challenges & Considerations:

• Designing a schema that is both powerful (supporting branching, parallelism) and easy to use.
• Efficiently managing state for potentially long-running or numerous concurrent workflows.
• Robust error handling, retry mechanisms, and compensation logic.
• Providing effective debugging and monitoring tools for complex workflows.
• Ensuring security when workflows involve agents with different permissions or access to tools.

[zrosenbauer]

@omeraplak is this something where you would be open to a PR or series of PRs? I'm betting it would take some serious changes but I'm currently putting together using effect in our own app to support agents workflows. I'd rather adopt something but I need both workflows and graph (and I don't love langchain ecosystem).

[omeraplak]

Hey @zrosenbauer , Absolutely, we’re definitely open to PRs on this! Using effect to manage workflows sounds like an awesome idea. Would love to see what you’re working on ⚡️

[zrosenbauer]

Sweet!

Well we just launched updated site joggr.io now we need to finish building out the agent(s)!

I'm jumping back into this tomorrow and this weekend & I'll take a look then.

[omeraplak]

Joggr actually sounds really interesting might even be useful for us too! I’ll definitely take a look. By the way, are you building the agents with VoltAgent or using a different framework?

[zrosenbauer]

Vercel SDK currrently + custom, I pinged you on discord to chat more on the details

[ouj]

I am glad to see that static workflow is in the roadmap. Many simple tasks will benefit from having static workflows for better control and a lower token budget.

We were evaluating mastra.ai. Their workflow support is very hard to use. LangGraph is even worse.

[omeraplak]

Totally agree! static workflows will be super helpful for simpler tasks where you want more control and tighter token usage.

Thanks for sharing your experience with Mastra and LangGraph too. We’ve heard similar feedback a lot of flexibility, but hard to use in practice.
If you have thoughts on what an ideal workflow experience would look like, we’d love to hear it!

[ouj]

I only worked on this area for a short time. I don't know if my experience is as valuable as that of other veterans, but here you go:

I am looking for a workflow engine that offers good DAG visualization. I like the idea of VoltAgent to focus on observability. That is the thing I care about a lot. That should carry forward to static workflows.

I think Mastra is on the right track in terms of the vision, but the execution seemed off, resulting in a syntax that is very hard to use. To some extent, I am unsure what they were trying to optimize for (readability, efficiency, or type checking?).

I also like the idea of https://github.com/callstackincubator/flows-ai to follow Anthropic's agent patterns. But their implementation is too basic. Good for a proof of concept, but good enough for production use.

[ouj]

In my opinion, LLM excels in two things.

Reasoning: That is why we want to use LLM as an orchestration agent to build fully agentic, dynamic workflows.

Parsing fuzzy data: In this case, we just want to use LLM as a step in a data pipeline, nothing more than an async function.

[zrosenbauer]

So far I'm a big fan of the SuperVisor <> Agents model but I'd love an actual primitive we could use =>

const workflow  = (new Workflow())
  .andThen(agent1)
  .andThen(agent2)
  .execute();

Mastra AI has this => https://mastra.ai/en/reference/workflows/workflow

for now though I'm going to use either remeda or effect to do this (I need to test async with remeda, I know it works with effect) =>

import * as R from 'remeda';

const result = R.pipe(
   callAgent(agent1),
   callAgent(agent2)
);

[omeraplak]

Would you like to open a simple PR? I think it would be a great starting point and we can improve it together with the community 🍻 @zrosenbauer @ouj