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 execute handler. Add inputSchema when the action needs arguments: 
{
    name: "createProject",
    description: "Create a new project with a name and optional description",
    inputSchema: {
        name: {
            type: "string",
            description: "Project name",
            required: true,
        },
        description: {
            type: "string",
            description: "Project description",
            required: false,
        },
    },
    approvalRequired: false,
    execute: ({ name, description }) => {
        createProject({ name, description })
    },
}

​
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" },
]
In production code, every action should include an execute handler.

​
Input Schemas

inputSchema supports three formats:
  1. Legacy option schema ({ field: { type, required, description } })
  2. JSON Schema object
  3. Zod schema (z.object(...)) converted to JSON Schema automatically
For legacy option schemas, actions accept three parameter types:

​
String

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

​
Number

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

​
Boolean

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

​
Handling Actions

The onAction callback receives executed actions as a fallback: 
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",
    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

Documentation Assistance

What happens when no action matches

Context

Help the agent understand what’s on screen