Skip to main content

​
What are Workflows?

Workflows are powerful multi-step operations that enable your agent to handle complex, long-running tasks that require user interaction, external API calls, or sequential processing. Unlike simple tool calls that execute instantly, workflows can pause execution to wait for user input, show progress updates, and resume from where they left off. This makes them perfect for scenarios like multi-step onboarding processes, complex data analysis pipelines, interactive tutorials, or any task that requires back-and-forth communication with users. Workflows are built using generator functions that can yield status updates and pause for input, making them ideal for creating engaging, interactive agent experiences.

​
Workflow Execution

Workflows are automatically triggered when your AI agent decides to use them during conversations. You don’t manually call workflows; instead, you ask your agent to do something (like “help me swap tokens” or “guide me through onboarding”), and the agent intelligently chooses to use a workflow tool when appropriate. The workflow then executes in the background, can pause for your input, and returns results to continue the conversation.

​
Create Custom Workflows

1

Create Your Workflow File

Note that the config/ folder and example workflow file are created when you run pnpm cli init, and they don’t exist in the initial repository. For more detailed guidelines, check out the GitHub repository.
Create a workflow file in config/workflows/. There is an example config/workflows/example-workflow.ts file provided for reference. The example workflow demonstrates progress updates, user interaction, and multi-step execution:
import type { WorkflowPlugin, WorkflowContext } from '../../src/workflows/types.js';
import { z } from 'zod';

const plugin: WorkflowPlugin = {
  id: 'my-workflow', // Unique identifier for your workflow
  name: 'My Workflow', // Display name
  description: 'A simple workflow example', // What this workflow does
  version: '1.0.0', // Version for tracking changes

  // Define what inputs this workflow expects
  inputSchema: z.object({
    message: z.string(), // Requires a string message parameter
  }),

  // The main workflow execution logic
  async *execute(context: WorkflowContext) {
    const { message } = context.parameters; // Extract the input message

    // Step 1: Show progress to the user
    yield {
      type: 'status',
      status: {
        state: 'working', // Indicates the workflow is processing
        message: {
          kind: 'message',
          messageId: 'processing',
          contextId: context.contextId,
          role: 'agent',
          parts: [{ kind: 'text', text: 'Processing...' }], // Shows "Processing..." to user
        },
      },
    };

    // Step 2: Pause and ask for user confirmation
    const userInput = yield {
      type: 'pause', // Pauses execution to wait for user input
      status: {
        state: 'input-required', // Indicates user input is needed
        message: {
          kind: 'message',
          messageId: 'confirmation',
          contextId: context.contextId,
          role: 'agent',
          parts: [{ kind: 'text', text: 'Continue?' }], // Asks "Continue?" to user
        },
      },
      inputSchema: z.object({
        confirmed: z.boolean(), // Expects a boolean response from user
      }),
    };

    // Step 3: Return the final result
    return { success: true, message }; // Workflow completes successfully
  },
};

export default plugin;
2

Register Your Workflow

To register your workflow, add it to config/workflow.json. This step makes your workflow discoverable by the agent system:
{
  "workflows": {
    "my-workflow": "./workflows/my-workflow.ts"
  }
}
Next, add it to config/agent.manifest.json. This step enables the workflow for your agent:
{
  "enabledWorkflows": ["my-workflow"]
}
3

Test Your Workflow

pnpm cli doctor
pnpm cli run --dev
This step validates your workflow configuration and starts the agent with your new workflow available. Your workflow becomes available as a tool with the naming pattern dispatch_workflow_{workflow_id} (e.g., dispatch_workflow_my_workflow).
⌘I