Actions
The six action kinds a component can carry, and which side of the wire handles each.
Every interactive component in a surface carries actions. The kind decides who handles the interaction.
| Kind | Handled by | Typical use |
|---|---|---|
local | Your app, through a handler registered with registerAction(name, …) | Add to cart, open a product page, start checkout. The SDK reports whether a handler ran so the agent knows. |
agent | The runtime: sent to the model as the user’s next turn, with a label shown in the chat | Quick replies (“Track my order”), “Select flight”. |
submit | The runtime: the form’s values are collected and sent as the user’s turn | Address forms, date pickers, filters. |
confirm | The runtime: approves or declines a paused tool call | “Cancel order ORD-2201?” Yes / No. |
url | Your app’s onOpenUrl, after the URL allowlist check | Terms, tracking page, deep links. |
workflow | The runtime: sent like an agent action carrying workflowId and input. Dispatching to the workflow runner from a live turn is not wired yet. | “Start return”. |
Local actions in detail
A local action names a handler and passes arguments: the component’s declared args merged with anything the widget adds at tap time (form values, the selected option). The handler receives a KletsoActionContext with the BuildContext, the surface and node, the action, and the client. After it runs, the SDK sends reportLocalAction so the conversation log records that the app handled addToCart (or that no handler was registered).
Local actions can also arrive without a tap, as server-initiated app commands (app.command): the agent asks the app to run open_product because the user said “open the trail runner”. This is opt-in (allowServerCommands) and uses the same handler registry. Notification taps use it too (origin: notification).
The “both” pattern
Widgets often want to change app state and tell the agent. Do both: call your own code, then ctx.executeAction('add'). The example app’s product card adds to the local cart and posts the agent action so the model can say “Added. Anything else?”.
Confirmations
Tools marked require confirmation never run directly. The runtime pauses the turn, renders a confirmation surface with two confirm actions, and resumes when the user answers. Declining tells the model the user said no; it does not retry silently.