actions.mdx

title	Actions

Actions are callable functions that can be invoked by workflows, conversations, other actions, and external API clients. 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 ({ input }) => {
    // 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:

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

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

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

export default new Trigger({
  name: "webchatConversationStarted",
  events: [
    "webchat:conversationStarted",
  ],
  handler: async ({ event }) => {
    const result = await actions.doSomething()
    // Other logic
  },
});

import { Autonomous, actions, z } from "@botpress/runtime"

export default new Autonomous.Tool({
    name: "someTool",
    description: "A tool that does something",
    input: z.object({}),
    output: z.object({ result: z.string() }),
    handler: async () => {
        const result = await actions.doSomething()
        return { result }
    },
})

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

Unique name for the action. Must be alphanumeric with no special characters or spaces. Optional display title for the action. Optional description of what the action does. Optional metadata attributes for the action. Zod schema defining the input parameters for the action. Zod schema defining the output/return type of the action. Whether the action results should be cached. Defaults to false. Async function that implements the action logic. Receives an object with `input` (validated input matching your input schema) and `client` (the Botpress client for making API calls), and returns validated output matching your output schema.

Handler parameters

The handler function receives an object with input and client properties:

The validated input object matching the action's input schema. All properties are typed based on the schema definition. The Botpress client instance that can be used to make API calls and interact with the Botpress platform.