Workflows

Workflows are long-running processes that handle complex, multi-step operations or scheduled tasks. Unlike conversations, workflows can run independently on a schedule or be triggered by events.

While workflows in the ADK are similar in concept to Workflows in Botpress Studio, they behave differently and shouldn’t be treated as equivalent.

Creating a workflow

Create a workflow in src/workflows/:

import { Workflow } from "@botpress/runtime";

export default new Workflow({
  name: "my-workflow",
  description: "A workflow that processes data",
  handler: async ({}) => {
    // Workflow logic
  },
});

Scheduled workflows

Workflows can run on a schedule using cron syntax:

import { WebsiteKB } from '../knowledge/docs'

export default new Workflow({
  name: "periodic-indexing",
  description: "Indexes knowledge base every 6 hours",
  schedule: "0 */6 * * *", // Every 6 hours
  handler: async ({}) => {
    await WebsiteKB.refresh();
  },
});

Workflow steps

Use the step function to create checkpoints in long-running workflows:

export default new Workflow({
  name: "data-processing",
  handler: async ({ step }) => {
    // Step 1: Fetch data
    const data = await step("fetch-data", async () => {
      return await fetchDataFromAPI();
    });

    // Step 2: Process data
    const processed = await step("process-data", async () => {
      return processData(data);
    });

    // Step 3: Store results
    await step("store-results", async () => {
      await saveResults(processed);
    });
  },
});

Steps are persisted, so if a workflow is interrupted, it can resume from the last completed step.

Reference

Workflow props

Show Workflow props

name · string · required

Unique name for the workflow. Used to identify and reference the workflow.

description · string

Optional description of what the workflow does.

input · z.ZodTypeAny

Optional Zod schema defining the input parameters for the workflow. Defaults to an empty object if not provided.

output · z.ZodTypeAny

Optional Zod schema defining the output/return type of the workflow. Defaults to an empty object if not provided.

state · z.ZodTypeAny

Optional Zod schema defining the workflow state structure. Defaults to an empty object if not provided.

requests · object

Optional object mapping request names to their Zod schemas. Each key is a request name and value is a Zod schema for the request data.

handler · (props: object) => Promise<any> | any · required

Handler function that implements the workflow logic. See handler parameters below for details.

schedule · string

Optional cron expression for scheduled workflows (e.g., “0 */6 * * *” for every 6 hours).

timeout · '{number}s' | '{number}m' | '{number}h'

Optional timeout for workflow execution (e.g., “5m”, “1h”). Defaults to “5m”.

Handler parameters

The handler function receives workflow context and provides step management:

Show Handler parameters

input · any · required

The validated input object matching the workflow’s input schema. Typed based on your input schema.

state · any · required

Workflow state object that persists across workflow executions and steps. Typed based on your state schema.

step · object · required

Step function for creating checkpoints. Also provides methods like listen, fail, progress, abort, sleep, sleepUntil, waitForWorkflow, executeWorkflow, map, forEach, batch, and request.

client · object · required

Botpress client for making API calls (tables, events, etc.).

execute · (props: object) => Promise<any> · required

Function to execute autonomous AI logic. Used to run the agent with instructions, tools, knowledge bases, etc.

Show Execute props

instructions · string | (() => string) | (() => Promise<string>) · required

Instructions for the AI agent. Can be a string or a function that returns a string.

tools · object[]

Optional array of tools the agent can use.

objects · object[]

Optional array of objects the agent can interact with.

exits · Record<string, object>

Optional record of exit handlers.

signal · AbortSignal

Optional abort signal to cancel execution.

hooks · object

Optional hooks for customizing behavior (onBeforeTool, onAfterTool, onTrace, etc.).

temperature · number | (() => number) | (() => Promise<number>)

Optional temperature for the AI model. Defaults to 0.7.

model · string | string[] | (() => string | string[]) | (() => Promise<string | string[]>)

Optional model name(s) to use. Can be a string, array of strings, or a function that returns either.

knowledge · object[]

Optional array of knowledge bases to use.

iterations · number

Optional maximum number of iterations (loops). Defaults to 10.