Actions

Actions are callable functions that can be invoked by workflows, conversations, or other actions. They encapsulate reusable logic and can be called from anywhere in your agent.

Creating an action

Create an action in src/actions/:

import { Action, z } from "@botpress/runtime";

export default new Action({
  name: "myAction",
  input: z.object({}), // Input schema
  output: z.object({}), // Output schema
  handler: async ({}) => {
    // Function logic
    return {}
  },
});

Action input and output

Define input and output schemas using TypeScript types or Zod schemas:

export default new Action({
  name: "calculateTotal",
  input: z.object({
    items: z.array(z.object({
      price: z.number(),
      quantity: z.number(),
    })),
  }),
  output: z.object({
    total: z.number()
  }),
  handler: async (input) => {
    const total = input.items.reduce(
      (sum, item) => sum + item.price * item.quantity,
      0
    );
    return { total };
  },
});

Calling actions

Actions can be called from anywhere in your agent’s source. Just import actions and call them directly:

From a workflow

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

export default new Workflow({
  name: "someWorkflow",
  handler: async ({}) => {
    const result = await actions.doSomething();
      // Other logic
  },
});

As a tool in a conversation

You can provide an action to your agent as a tool using the asTool method:

import { Conversation, actions } from "@botpress/runtime";

export default new Conversation({
  channel: "*",
  handler: async ({ execute }) => {
    await execute({
      instructions: "You are a helpful assistant.",
      tools: [actions.calculateTotal.asTool()]
    });
  },
});

Integration actions

When you install an integration, its actions become available anywhere in your agent’s source:

import { Trigger, actions } from "@botpress/runtime";

export default new Trigger({
  name: "webchatConversationStarted",
  events: [
    "webchat:conversationStarted",
  ],
  handler: async ({ event }) => {
    let conversationId = event.conversationId

    if (conversationId) {
      await actions.webchat.showWebchat({
        conversationId
      })
    }

  },
});

Best practices

• Keep actions focused on a single responsibility
• Use actions for reusable logic that’s needed across multiple parts of your agent

Actions are ideal for business logic that doesn’t need to be part of the conversational flow. They can be tested independently and reused across different parts of your agent.

Reference

Action props

Show Action props

name · string · required

Unique name for the action. Must be alphanumeric with no special characters or spaces.

title · string

Optional display title for the action.

description · string

Optional description of what the action does.

attributes · Record<string, string>

Optional metadata attributes for the action.

input · z.ZodTypeAny · required

Zod schema defining the input parameters for the action.

output · z.ZodTypeAny · required

Zod schema defining the output/return type of the action.

cached · boolean

Whether the action results should be cached. Defaults to false.

handler · (input: any) => Promise<any> · required

Async function that implements the action logic. Receives validated input matching your input schema and returns validated output matching your output schema.

Handler parameters

The handler function receives the validated input parameters based on the input schema:

Show Handler parameters

input · any · required

The validated input object matching the action’s input schema. All properties are typed based on the schema definition.