Agent Actions

When the agent replies to a chat message, it can return more than text — it can return a list of actions for the SDK to execute against the live UI. This page describes the action model: the action types, their payload shapes, how an action's status changes over time, and how confirmation gating works.

Action types

Every action has a type of one of:

Type	What it does
navigate	Moves the user to a different screen.
form_fill	Fills one or more fields on the current screen, optionally submitting.
ui_interaction	Presses, scrolls, swipes, focuses, or sets the value of a registered UI element.
scroll_list	Scrolls a registered list so off-screen rows are rendered before further actions target them.
confirm	Asks the user to approve or reject a pending action before it runs.
custom	An app-defined action, handled by your own code.

Payload shapes

Each action carries a payload whose shape depends on its type:

Type	Payload fields
navigate	screenName, params?, navigationAction (push | navigate | replace | goBack | reset), path? (parent navigator route names for nested navigators, e.g. ['HomeTab', 'VehiclesTab'])
form_fill	screenName, fields (array of { fieldId, fieldType, value, label? }), submitAfterFill?
ui_interaction	componentId, targetId?, action (press | longPress | scroll | swipe | focus | set_value), value? (numeric, used with set_value for sliders), params?
scroll_list	listId?, toIndex?, direction? (up | down)
confirm	A message and title describing the action awaiting approval

A form_fill field's fieldType is one of text, select, toggle, date, number, or custom.

Status lifecycle

Every action starts as pending. From there it moves through:

pending → executing → completed
                    ↘ failed

An action that fails carries an error string explaining why.

autoExecute vs. confirm

<AppilotsChat autoExecute={true} /> (the default) controls whether non-confirm actions run automatically as soon as they arrive, or wait for the user to tap approve in the chat UI.

• When autoExecute is true, any action that isn't type confirm executes immediately.
• When autoExecute is false, every action waits for explicit user approval before executing.
• confirm actions are the exception in both cases — they always require the user to tap approve or reject in the chat UI, regardless of the autoExecute setting. This is what makes them useful as a gate in front of a risky action: the agent emits a confirm action, and only once the user approves it does the following action run.

What drives a confirmation gate

Screens and actions can carry risk metadata that determines whether a confirm step is inserted before an action runs:

• effect: 'read', 'write', 'destructive', or a custom string
• riskLevel: 'low', 'medium', 'high', or a custom string
• destructive / requiresConfirmation: booleans that mark an action as needing explicit approval

This metadata can be set two ways: at generation time, via static analysis or JSDoc annotations picked up by the CLI, or at runtime via registerScreen({ actions: [{ id, label, type, effect, riskLevel, requiresConfirmation }] }). Both the CLI's --strict-metadata lint and the SDK's own local checks use these fields to decide whether an action needs a confirmation step before it executes — treat them as the primary way you flag "this action shouldn't run silently" for your own screens.

Related pages

• Permissions — constraining which action types and screens the agent may touch at all
• MCP documents — where action metadata comes from
• SDK: registering elements — declaring actions with registerScreen()
• SDK: permissions — applying permissions on the SDK side