@botpress/adk-cli/dist/actions-embn8wea.md

Command-line interface for the Botpress Agent Development Kit (ADK)

# Actions

Actions are callable, strongly-typed functions that encapsulate reusable logic accessible throughout your agent. They can be invoked from workflows, conversations, other actions, or exposed as tools for AI.

## Overview

Actions enable you to:

- Create reusable business logic across your bot
- Call integration APIs with type safety
- Expose functionality as AI-callable tools
- Compose complex operations from simple functions
- Test logic independently from conversational flows

## File Location

- **Location**: `src/actions/*.ts`
- **Auto-registration**: Files in this directory automatically become available as `actions.{actionName}`
- **Export pattern**: Both `export const` and `export default` work
  - **`export const`** (Recommended): Enables direct imports and passing to `execute()` as tools
  - **`export default`**: Simpler for single-action files

## Basic Action Structure

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

// Option 1: Named export (recommended)
export const myAction = new Action({
  name: "myAction",
  input: z.object({
    userId: z.string(),
  }),
  output: z.object({
    data: z.string(),
    timestamp: z.string()
  }),
  handler: async ({ input, client }) {
    // Your business logic here
    const result = await fetchData(input.userId);

    return {
      data: result,
      timestamp: new Date().toISOString()
    };
  },
});

// Option 2: Default export (also valid)
export default new Action({
  name: "myAction",
  // ... same configuration
});
```

> **`output` is required.** Declare it as a bare Zui schema (`output: z.object({ ... })`), never `output: { schema: ... }`. Omitting it fails the type check (`adk check` won't catch it).

**Why use `export const`?**

- Enables direct imports: `import { myAction } from "./actions/myAction"`
- Can pass to `execute()`: `tools: [myAction.asTool()]`
- Better for action composition and reusability

## Action Properties

| Property        | Type                     | Required | Description                                                      |
| --------------- | ------------------------ | -------- | ---------------------------------------------------------------- |
| **name**        | `string`                 | Yes      | Unique alphanumeric identifier (no spaces or special characters) |
| **input**       | `z.ZodTypeAny`           | Yes      | Zod schema defining input parameters                             |
| **output**      | `z.ZodTypeAny`           | Yes      | Zod schema defining return type                                  |
| **handler**     | `function`               | Yes      | Async function implementing the action logic                     |
| **title**       | `string`                 | No       | Human-readable display name                                      |
| **description** | `string`                 | No       | Description of the action's functionality                        |
| **attributes**  | `Record<string, string>` | No       | Custom metadata for categorization                               |
| **cached**      | `boolean`                | No       | Enable caching for identical inputs (defaults to `false`)        |

## Handler Syntax

Action handlers receive a props object containing `input` and `client`. Both method syntax and arrow functions are supported.

### Method Syntax (Recommended)

```typescript
export const fetchUser = new Action({
  name: 'fetchUser',
  input: z.object({ userId: z.string() }),
  output: z.object({
    name: z.string(),
    email: z.string(),
  }),

  async handler({ input, client }) {
    // input: validated input matching your input schema
    // client: Botpress API client for making API calls
    const { user } = await client.getUser({ id: input.userId })
    return {
      name: user.name,
      email: user.tags.email,
    }
  },
})
```

### Arrow Function Syntax

```typescript
export const updateUser = new Action({
  name: 'updateUser',
  input: z.object({
    userId: z.string(),
    name: z.string(),
  }),
  output: z.object({ success: z.boolean() }),

  handler: async ({ input, client }) => {
    await client.updateUser({
      id: input.userId,
      name: input.name,
    })
    return { success: true }
  },
})
```

### Common Mistakes

```typescript
// ❌ WRONG - Destructuring input fields directly
export const fetchUser = new Action({
  name: 'fetchUser',
  input: z.object({ userId: z.string() }),
  output: z.object({ name: z.string() }),

  async handler({ userId }) {
    // ❌ Wrong! Must be { input }
    return { name: userId }
  },
})

// ✅ CORRECT - Use { input } wrapper
export const fetchUser = new Action({
  name: 'fetchUser',
  input: z.object({ userId: z.string() }),
  output: z.object({ name: z.string() }),

  async handler({ input }) {
    // ✅ Correct
    const { userId } = input // Destructure inside handler
    return { name: userId }
  },
})
```

**Key points:**

- Handler receives `{ input, client }` props object
- Both method syntax and arrow functions work
- Destructure input fields **inside** the handler body, not in the parameter
- **Actions CANNOT destructure input fields directly** (unlike Tools)
- Omit `client` if not needed: `async handler({ input })`

## Calling Actions

### From Workflows

```typescript
import { Workflow, actions } from '@botpress/runtime'

export default new Workflow({
  name: 'processOrder',
  input: z.object({ orderId: z.string() }),

  handler: async ({ input }) => {
    // Call your custom actions
    const order = await actions.fetchOrder({ orderId: input.orderId })
    const result = await actions.processPayment({ order })

    return result
  },
})
```

### From Other Actions

```typescript
import { Action, actions, z } from '@botpress/runtime'

export default new Action({
  name: 'compositeAction',
  input: z.object({ userId: z.string() }),
  output: z.object({ success: z.boolean() }),

  async handler({ input }) {
    // Compose multiple actions
    const userData = await actions.fetchUser({ userId: input.userId })
    const profile = await actions.buildProfile({ user: userData })
    return { success: true }
  },
})
```

### Integration Actions

Call integration actions from within your actions:

```typescript
import { actions } from '@botpress/runtime'

// Inside action handler
await actions.slack.sendMessage({
  channel: '#general',
  text: 'Message from bot',
})

await actions.linear.issueList({ first: 10 })
```

See **[Integration Actions](./integration-actions.md)** for complete guide.

## Accessing Additional Context

Actions can access additional runtime context through **direct imports** or the **Context API**.

Direct imports are best for the global proxies that actually exist at runtime, such as `user`, `bot`, `configuration`, and `adk`. For optional per-request values like `conversation` and `message`, use the Context API.

### Method 1: Direct Imports (Global Context Proxies)

```typescript
import { Action, z, user, bot, adk } from '@botpress/runtime'
import { context } from '@botpress/runtime'

export default new Action({
  name: 'updateUserProfile',
  input: z.object({ name: z.string() }),
  output: z.object({ success: z.boolean() }),

  async handler({ input }) {
    // Access user state directly (when in conversation context)
    user.state.profileName = input.name
    user.tags.profileComplete = 'true'

    // Access bot state
    bot.state.totalUsers += 1

    // Access conversation (when in conversation context)
    const conversation = context.get('conversation', { optional: true })
    console.log(conversation?.id)

    // Use ADK utilities
    const extracted = await adk.zai.extract(input.name, z.object({ firstName: z.string(), lastName: z.string() }))

    return { success: true }
  },
})
```

### Method 2: Context API (Explicit Retrieval)

```typescript
import { Action, z, context } from '@botpress/runtime'

export default new Action({
  name: 'checkContext',
  input: z.object({}),
  output: z.object({ hasUser: z.boolean() }),

  async handler({ input }) {
    // Optional context (may not be available in all scenarios)
    const user = context.get('user', { optional: true })
    const conversation = context.get('conversation', { optional: true })
    const message = context.get('message', { optional: true })

    // Always available
    const client = context.get('client')
    const citations = context.get('citations')

    if (user) {
      console.log(`User: ${user.id}`)
    }

    return { hasUser: !!user }
  },
})
```

**Which method to use?**

- **Direct imports**: Use for `user`, `bot`, `adk` when you know they're available (simpler syntax)
- **Context API**: Use for optional context (`user`, `conversation`, `message`) or when you need `client` and `citations`

**Always available:** `bot`, `adk`, `client`, `context`
**Conditionally available:** `user`, `conversation`, `message` (only in conversation context)

See **[Context API](./context-api.md)** for complete details on all context keys and availability.

## Advanced Action Patterns

### Pattern 1: Integration Wrapper Pattern

**Purpose:** Wrap integration actions with bot-specific logic, data transformation, and local persistence.

**When to use:**

- Syncing external resources (products, issues, orders) to local tables
- Normalizing data from different integrations
- Adding business logic or validation
- Maintaining local cache of external data

**Abstract Structure:**

```typescript
export default new Action({
  name: 'syncResource',
  description: 'Fetch and sync external resource to local storage',

  input: z.object({
    resourceId: z.string().describe('External resource identifier'),
  }),

  output: BotResourceSchema, // Your normalized schema

  async handler({ input }) {
    // 1. Call integration action
    const externalData = await actions.integration.getResource({
      id: input.resourceId,
    })

    // 2. Transform to bot schema
    const normalizedData = transformToBotSchema(externalData)

    // 3. Persist to table (prevents duplicates)
    await ResourceTable.upsertRows({
      rows: [normalizedData],
      keyColumn: 'id', // Unique identifier
    })

    // 4. Return normalized data
    return normalizedData
  },
})
```

**Real Example - Shopify: Sync Products**

```typescript
import { Action, actions, z } from '@botpress/runtime'
import { ProductsTable } from '../tables/shopify'

export default new Action({
  name: 'syncProduct',
  description: 'Sync a Shopify product to local database',

  input: z.object({
    productId: z.string().describe('Shopify product ID'),
    includeVariants: z.boolean().default(true),
  }),

  output: z.object({
    id: z.string(),
    title: z.string(),
    price: z.number(),
    inventory: z.number(),
    lastSynced: z.string(),
  }),

  async handler({ input }) {
    // 1. Fetch from Shopify
    const shopifyProduct = await actions.shopify.getProduct({
      id: input.productId,
      fields: ['id', 'title', 'variants', 'inventory'],
    })

    // 2. Transform to bot schema
    const product = {
      id: shopifyProduct.id,
      title: shopifyProduct.title,
      price: shopifyProduct.variants[0].price,
      inventory: shopifyProduct.variants.reduce((sum, v) => sum + v.inventory_quantity, 0),
      lastSynced: new Date().toISOString(),
    }

    // 3. Upsert to table
    await ProductsTable.upsertRows({
      rows: [product],
      keyColumn: 'id',
    })

    return product
  },
})
```

**Key Benefits:**

- **Consistency**: All external data follows your bot's schema
- **Performance**: Local table queries are faster than API calls
- **Reliability**: Works even if integration is temporarily unavailable
- **Extensibility**: Easy to add business logic or validation

### Pattern 2: Resource State Management

**Purpose:** Update external resource state and keep local cache in sync.

**Real Example - Linear: Update Issue Status**

```typescript
import { Action, actions, z } from '@botpress/runtime'
import { IssuesTable } from '../tables/linear'

export default new Action({
  name: 'updateIssueStatus',

  input: z.object({
    issueId: z.string(),
    stateId: z.string(),
    comment: z.string().optional(),
  }),

  output: z.object({
    id: z.string(),
    title: z.string(),
    state: z.string(),
    updatedAt: z.string(),
  }),

  async handler({ input }) {
    // 1. Update in Linear
    const issue = await actions.linear.updateIssue({
      id: input.issueId,
      stateId: input.stateId,
      ...(input.comment && {
        commentBody: input.comment,
      }),
    })

    // 2. Transform and sync to table
    const normalized = {
      id: issue.id,
      title: issue.title,
      state: issue.state.name,
      updatedAt: new Date().toISOString(),
    }

    await IssuesTable.upsertRows({
      rows: [normalized],
      keyColumn: 'id',
    })

    return normalized
  },
})
```

**When to use this pattern:**

- Tracking order fulfillment status
- Managing ticket/issue lifecycle
- Handling conversation states
- Any resource with state transitions

## Schema Design Best Practices

**Core Principles:**

```typescript
import { z } from '@botpress/runtime'

// 1. Always export both type and schema
export type Product = z.infer<typeof ProductSchema>
export const ProductSchema = z.object({
  id: z.string(),
  name: z.string(),
  price: z.number(),
})

// 2. Use .describe() on every field (helps AI tools)
const schema = z.object({
  productId: z.string().describe('Unique product identifier'),
  price: z.number().describe('Price in cents'),
  inStock: z.boolean().describe('Whether product is available'),
})

// 3. ISO strings for dates (NOT z.date())
const timeFields = z.object({
  createdAt: z.string().describe('Creation date as ISO 8601 string'),
  updatedAt: z.string().optional().describe('Last update date'),
})

// 4. Use .optional() for optional fields
const optionalFields = z.object({
  name: z.string(), // Required
  description: z.string().optional(), // Optional
  metadata: z.record(z.unknown()).optional(),
})

// 5. Use .passthrough() for external API data
const externalData = z
  .object({
    id: z.string(),
    // Allow unknown fields from external API
  })
  .passthrough()

// 6. Define nested objects explicitly
const structured = z.object({
  product: z.object({
    // ✅ Explicit structure
    id: z.string(),
    name: z.string(),
  }),
  metadata: z.record(z.unknown()), // ❌ Use only when structure is truly unknown
})
```

**Key Patterns:**

1. **Export both type and schema** - TypeScript type from `z.infer<>`
2. **Describe every field** - Helps AI tools and documentation
3. **ISO strings for dates** - Use `z.string()` not `z.date()`
4. **Optional vs nullable** - Use `.optional()` for optional fields
5. **Passthrough for external APIs** - Use `.passthrough()` when structure varies
6. **Separate schemas file** - Keep complex schemas in `src/schemas.ts`
7. **Explicit nested objects** - Define structure instead of `z.unknown()`

## Converting Actions to Tools

Actions can be converted to AI-callable tools using the `.asTool()` method. This allows AI agents to autonomously call your actions during conversations.

### Basic Usage

```typescript
import { actions, Conversation } from '@botpress/runtime'

export default new Conversation({
  handler: async ({ execute }) => {
    await execute({
      instructions: 'Help the user with their request',
      tools: [
        // Convert existing actions to tools
        actions.fetchUser.asTool(),
        actions.sendEmail.asTool(),
        actions.searchDatabase.asTool(),
      ],
    })
  },
})
```

### Tool Patterns: Blocking vs Non-Blocking

#### Pattern Comparison

| Pattern              | Returns      | Execution    | Example           |
| -------------------- | ------------ | ------------ | ----------------- |
| **Direct Action**    | Final result | Synchronous  | `fetchUser()`     |
| **Workflow Wrapper** | Workflow ID  | Asynchronous | `startIndexing()` |

#### 1. Direct Actions

Actions that complete and return results immediately:

```typescript
import { Action, z } from '@botpress/runtime'

export default new Action({
  name: 'calculateShipping',
  description: 'Calculate shipping cost for an order',

  input: z.object({
    weight: z.number(),
    destination: z.string(),
  }),

  output: z.object({
    cost: z.number(),
    estimatedDays: z.number(),
  }),

  async handler({ input }) {
    // Business logic that completes immediately
    const baseRate = 5.99
    const perKg = 2.5
    const cost = baseRate + input.weight * perKg

    const estimatedDays = input.destination === 'domestic' ? 3 : 7

    return { cost, estimatedDays }
  },
})

// Use as tool - AI can call this during conversation
await execute({
  instructions: 'Help the user with shipping',
  tools: [actions.calculateShipping.asTool()],
})
```

#### 2. Workflow Wrappers

Actions that start workflows and return workflow ID:

```typescript
import { Action, z } from '@botpress/runtime'
import { DataAnalysisWorkflow } from '../workflows/data-analysis'

export default new Action({
  name: 'startDataAnalysis',
  description: 'Start data analysis workflow',

  input: z.object({
    datasetId: z.string(),
  }),

  output: z.object({
    workflowId: z.string(),
  }),

  async handler({ input }) {
    // Calls workflow.start() - returns immediately
    const instance = await DataAnalysisWorkflow.start({
      datasetId: input.datasetId,
    })
    return { workflowId: instance.id }
  },
})

// Companion action to check status
export const checkAnalysisStatus = new Action({
  name: 'checkAnalysisStatus',
  description: 'Check workflow status',

  input: z.object({
    workflowId: z.string(),
  }),

  output: z.object({
    status: z.string(),
  }),

  async handler({ input, client }) {
    const { workflow } = await client.getWorkflow({ id: input.workflowId })
    return { status: workflow.status }
  },
})

// Use both as tools
await execute({
  instructions: 'Help the user',
  tools: [actions.startDataAnalysis.asTool(), actions.checkAnalysisStatus.asTool()],
})
```

### Custom Tool Conversion

```typescript
// Basic conversion
const shippingTool = actions.calculateShipping.asTool()

// With custom description
const analysisTool = actions.startDataAnalysis.asTool({
  description: 'Analyze dataset and return workflow ID',
})
```

> **See Also:** [Exposing Workflows as Tools](./workflows.md#exposing-workflows-as-tools-non-blocking-pattern) for comprehensive workflow wrapper patterns and tracking examples.

## Best Practices

1. **Use descriptive names**: `fetchUserProfile` not `getUser`
2. **Validate inputs thoroughly**: Use Zod's validation features
3. **Handle errors gracefully**: Catch and wrap errors with context
4. **Keep actions focused**: One action = one responsibility
5. **Document complex logic**: Add comments for non-obvious operations
6. **Use caching wisely**: Enable `cached: true` for deterministic operations

```typescript
export default new Action({
  name: 'fetchUserProfile',
  description: 'Fetches complete user profile with preferences',

  input: z.object({
    userId: z.string().uuid(), // Validate UUID format
    includePreferences: z.boolean().default(false),
  }),

  output: z.object({
    user: z.object({
      id: z.string(),
      name: z.string(),
      email: z.string().email(),
    }),
    preferences: z
      .object({
        language: z.string(),
        timezone: z.string(),
      })
      .optional(),
  }),

  cached: true, // Cache for performance

  async handler({ input, client }) {
    // Validate user exists
    const { user } = await client.getUser({ id: input.userId })
    if (!user) {
      throw new Error(`User ${input.userId} not found`)
    }

    // Conditionally fetch preferences
    const preferences = input.includePreferences ? await fetchUserPreferences(input.userId) : undefined

    return {
      user: {
        id: user.id,
        name: user.name,
        email: user.tags.email,
      },
      preferences,
    }
  },
})
```

## Common Patterns

### Composition Pattern

Combine multiple actions for complex operations:

```typescript
export default new Action({
  name: 'processOrder',
  input: z.object({ orderId: z.string() }),
  output: z.object({ success: z.boolean() }),

  async handler({ input }) {
    // Compose multiple actions
    const order = await actions.fetchOrder({ id: input.orderId })
    const validated = await actions.validateOrder({ order })

    if (validated.isValid) {
      await actions.chargePayment({
        amount: order.total,
        customerId: order.customerId,
      })
      await actions.sendConfirmation({ order })
      await actions.updateInventory({ items: order.items })
    }

    return { success: validated.isValid }
  },
})
```

### Error Recovery Pattern

Handle failures gracefully with retries:

```typescript
export default new Action({
  name: 'resilientFetch',
  input: z.object({ url: z.string().url() }),
  output: z.object({ data: z.unknown() }),

  async handler({ input }) {
    const maxRetries = 3
    let lastError

    for (let attempt = 1; attempt <= maxRetries; attempt++) {
      try {
        const response = await fetch(input.url)
        if (!response.ok) {
          throw new Error(`HTTP ${response.status}`)
        }
        return { data: await response.json() }
      } catch (error) {
        lastError = error
        if (attempt < maxRetries) {
          // Exponential backoff
          await new Promise((r) => setTimeout(r, 1000 * Math.pow(2, attempt)))
        }
      }
    }

    throw new Error(`Failed after ${maxRetries} attempts: ${lastError.message}`)
  },
})
```

## Troubleshooting

### Common Issues

1. **"Cannot destructure property" error**
   - **Cause**: Destructuring input fields directly in Action handler parameter
   - **Wrong**: `async handler({ userId }) { ... }`
   - **Correct**: `async handler({ input }) { const { userId } = input; ... }`
   - **Note**: Tools can destructure directly, but Actions cannot

2. **"user is not defined" or context errors**
   - **Cause**: Accessing conversation context outside of conversation context
   - **Solution**: Use `context.get("user", { optional: true })` to check availability
   - **Note**: `user`, `conversation`, `message` are only available in conversation contexts

3. **Action not found**
   - Verify file is in `src/actions/` directory
   - Check import: `import { actions } from "@botpress/runtime"`
   - Ensure action name matches file export

4. **Type errors with inputs/outputs**
   - Verify Zod schemas match actual data
   - Use `.optional()` for optional fields
   - Check for typos in property names

5. **State properties undefined**
   - **Cause**: State properties must be defined in `agent.config.ts` schemas
   - **Solution**: Add properties to `user.state` or `bot.state` schema in config
   - **Example**: Can't use `user.state.characterName` unless defined in config

6. **Caching issues**
   - **Issue**: Cached results not updating when expected
   - **Solution**: Only use `cached: true` for deterministic functions
   - **Tip**: Avoid caching for time-sensitive or user-specific data

## See Also

- [Tools](./tools.md) - AI-callable tools for autonomous execution
- [Workflows](./workflows.md) - Multi-step processes with state management
- [Context API](./context-api.md) - Access runtime context and services
- [Integration Actions](./integration-actions.md) - Using integration actions
- [Patterns & Common Mistakes](./patterns-mistakes.md) - Best practices for Zod schemas