Skip to main content
When a user’s request matches an action you’ve defined, the agent executes it directly. If no action matches, the agent falls back to searching documentation or escalating to your team.

Action Structure

Every action has a name, description, and optional parameters:
{
    name: "createProject",
    description: "Create a new project with a name and optional description",
    options: {
        name: {
            type: "string",
            description: "Project name",
            required: true,
        },
        description: {
            type: "string",
            description: "Project description",
            required: false,
        },
    },
    approvalRequired: false,
}

Descriptions Matter

The assistant uses descriptions to decide when to call an action. Be specific:
{
    name: "archiveProject",
    description: "Move a project to the archive. The project will no longer appear in the active list but can be restored later.",
}

Discovering Actions

Aim for 20-50+ actions. The more actions you define, the more capable the assistant becomes.

Where to Look

Search your codebase for user interactions:
Look ForExample Actions
ButtonsopenModal, submitForm, toggleSidebar
FormscreateItem, updateSettings, changePassword
Links/NavigationnavigateTo, openPage, goBack
TogglestoggleDarkMode, enableNotifications
Filters/SortingapplyFilter, sortBy, search
Bulk OperationsselectAll, deleteSelected, exportData
Context Menusduplicate, rename, share

Common Action Patterns

const actions = [
    // CRUD operations
    { name: "create", description: "Create a new item" },
    { name: "update", description: "Update an existing item" },
    { name: "delete", description: "Delete an item", approvalRequired: true },

    // Navigation
    { name: "navigateTo", description: "Navigate to a page" },
    { name: "openModal", description: "Open a modal dialog" },
    { name: "closeModal", description: "Close the current modal" },

    // State changes
    { name: "toggleSetting", description: "Toggle a boolean setting" },
    { name: "setTheme", description: "Change the color theme" },

    // Bulk actions
    { name: "selectAll", description: "Select all visible items" },
    { name: "clearSelection", description: "Clear all selections" },

    // Utilities
    { name: "copyToClipboard", description: "Copy text to clipboard" },
    { name: "download", description: "Download a file" },
    { name: "refresh", description: "Refresh the current view" },
]

Option Types

Actions accept three parameter types:

String

options: {
    title: {
        type: "string",
        description: "The item title",
        required: true,
    },
}

Number

options: {
    quantity: {
        type: "number",
        description: "Number of items",
        required: true,
    },
}

Boolean

options: {
    enabled: {
        type: "boolean",
        description: "Whether to enable the feature",
        required: true,
    },
}

Handling Actions

The onAction callback receives executed actions:
onAction: (action) => {
    const { name, options } = action

    switch (name) {
        case "createProject":
            createProject({
                name: options.name as string,
                description: options.description as string,
            })
            break

        case "deleteProject":
            deleteProject(options.id as string)
            break

        case "navigateTo":
            router.push(options.path as string)
            break
    }
}

Approval Required

Mark destructive or irreversible actions with approvalRequired: true:
{
    name: "deleteAccount",
    description: "Permanently delete the user account and all data",
    options: {},
    approvalRequired: true,
}
When the assistant tries to execute this action, the user sees a confirmation dialog before it proceeds.

When to Require Approval

  • Delete operations
  • Sending emails or messages
  • Publishing content
  • Financial transactions
  • Changing permissions
  • Any irreversible action

Next Steps