Actions: an assistant that acts
Answering is the default; acting is something you switch on deliberately. You register the actions your application allows, the assistant calls them when the user asks for something to be done, and it tells the user what happened.
User: "open the Leads board and prepare a proposal for Gary Orange:
12 hours of consulting at 150 each and 4 licences at 480 each"
→ open_screen(name = "Leads")
→ draft_proposal(lead = "Gary Orange",
items = "Consulting x 12 @ 150\nLicence x 4 @ 480") [confirmed]
Assistant: "I opened the Leads board and filled the draft for Hera Blue, Inc.
with two line items, $3720 in total: check it and press Preview."That is the CRM sample application talking, and you can run it. What the user finds afterwards is the draft, filled and not saved: the customer, the two line items, the total - Preview and Save Proposal are still theirs to press.

Some actions every application would write the same way - read the form the user is on and fill it, press one of its buttons, find a record of its list, show one of its tabs. Those the library has written already, as skills: name them in Settings.Skills and the assistant has them, without a line of code. This page is about the actions only your application knows.
Registering an action
uses HelpChatAI.Actions;
HelpChat.Actions.Add('open_screen',
'Brings one of the application screens to the front.',
[THelpChatActionParam.Create('name',
'Screen name: Dashboard, Accounts, Leads, Sales, Marketing, Calendar or Users.')],
procedure(const AArgs: THelpChatActionArgs; var AResult: string)
var
LTab: TTabSheet;
begin
LTab := FindTab(AArgs.AsString('name'));
if LTab = nil then
raise Exception.CreateFmt('There is no "%s" screen.', // the model is told
[AArgs.AsString('name')]);
PageControl.ActivePage := LTab;
AResult := 'Opened the ' + LTab.Caption + ' screen.'; // and so is this
end);The description and the parameter descriptions are the API the model reads: write them the way you would explain the action to a new colleague, and say what the parameter values look like ("PDF, Excel oppure CSV"). A parameter can be apkString, apkInteger, apkNumber or apkBoolean, required or not.
Reading parameters never raises: AsString, AsInteger, AsFloat, AsBoolean and Has return your default when a model omits an optional one or misspells a name.
Actions of one assistant, actions of all
With several assistants, each one may do what its form is for: the actions registered on a component belong to that assistant alone. The order expert can create an order; the planner cannot, and is not even told the action exists.
Some actions make sense whichever form the user is on - open a screen, find a customer. Register them once, on the application:
HelpChatSharedActions.Add('open_screen', 'Brings a screen of the application to the front.',
[THelpChatActionParam.Create('name', 'Name of the screen')],
procedure(const AArgs: THelpChatActionArgs; var AResult: string)
begin
MainForm.OpenScreen(AArgs.AsString('name'));
AResult := 'Opened.';
end, False);Every assistant offers them after its own, unless its UseSharedActions is False; an own action of the same name redefines the shared one. A shared action is still run by the assistant that was asked: its confirmation dialog, its form, its main thread.
A profile narrows, it never widens. AllowedActions in the configuration lists the actions that assistant may use, own and shared alike:
"Profiles": {
"Orders": { "AllowedActions": ["create_order", "add_order_line", "open_screen"] }
}Empty means all of them. A name nobody registered gives nothing: a deployment can take an action away without recompiling, it can never hand the model one the code did not write - with one exception to know about: Skills. A configuration that names a skill gives the assistant the library's own actions of that skill, and allows them even when AllowedActions is a list. Name a ConfigFileName on the component when the per-user file must not be able to do that. An action left out is not declared to the model and cannot be called either.
Three rules
Only what is registered exists
There is no generic "run this" entry point. The model sees the names, descriptions and parameters you declared and can call nothing else. Keep destructive operations out of the registry, or behind a confirmation.
An action runs on the main thread
Handlers open forms and fill fields, while the model call runs on a worker thread. HelpChatAI queues the call, wakes the host, and the component executes it on the main thread and sends the answer back. You do not deal with any of that — but it is why an action must not block for minutes: the default timeout is 60 seconds (Actions.TimeoutMs), after which the model is told the action did not answer — and it is not run any more, even if the user confirms it afterwards. Cancellation is honoured: a user who stops the reply does not leave a worker parked. And so is a window that was closed: the engine of a profile outlives each assistant that shares it, so a reply may still ask for an action of an assistant that has been deactivated since; it is answered "cancelled" at once instead of waiting for a host that left.
Anything that changes data asks first
An action asks before running unless you say otherwise: Confirm is True by default, and an action that changes nothing — bringing a screen to the front, say — is registered with False:
HelpChat.Actions.Add('open_screen', '...', [...],
procedure(const AArgs: THelpChatActionArgs; var AResult: string)
begin
...
end,
False); // ← changes nothing: no confirmationWho asks is OnActionConfirm when you assign it — your policy, not necessarily a dialog — and otherwise the confirmation dialog of the library, in the VCL and, on the desktop, in FireMonkey. On a mobile platform a modal form answers in a callback later on while the worker is waiting now, so there an action needing confirmation without OnActionConfirm is refused (see The FMX component).
procedure TMainForm.HelpChatActionConfirm(Sender: TObject; const AName: string;
const AArgs: THelpChatActionArgs; var AAllow: Boolean);
begin
AAllow := not FReadOnlyMode; // your policy, not a dialog
end;The confirmation dialog
Vcl.HelpChatAI.ConfirmDialog is a form with a DFM, so it follows the VCL style of the application and the DPI of the monitor it opens on, and it is centred on the host form, not on the window of the chat. FMX.HelpChatAI.ConfirmDialog is its FireMonkey twin, a form with an FMX that follows the style of the application, which the message box of the system does not. It shows what the application wrote — the name of the action as the instruction and its description — and, apart and labelled with the description of each parameter, what the model wrote: the values, one per line, in bold, cut short, under a note saying that the assistant wrote them. The dialog is never taller than the work area of its monitor: values that would not fit scroll, between the question and the buttons, which stay where they are. Yes and No are written in the language of the chat. No is the default button, so Enter cannot run an action nobody read; after 30 seconds (HELPCHAT_CONFIRM_TIMEOUT_MS) without an answer the dialog closes as No, before the timeout of the model call; and there is one dialog at a time per assistant — a second question of the same assistant arriving while one is open dismisses it as No and takes its place, while a question of another assistant opens over the first, which stays and is answered afterwards.
A dialog of your own is a form implementing IVclHelpChatConfirmDialog:
uses Vcl.HelpChatAI.ConfirmDialog;
type
TMyConfirmForm = class(TForm, IVclHelpChatConfirmDialog)
...
public
/// Shows the question modally; True means the user allowed it.
function Execute(const ARequest: TVclHelpChatConfirmRequest): Boolean;
/// Another question arrived: close as No.
procedure Dismiss;
end;
initialization
RegisterVclHelpChatConfirmDialog(TMyConfirmForm);TVclHelpChatConfirmRequest carries the host form, who asks (Asker, the component: what tells the question of one assistant from that of another), the caption, the title, the description, the labelled values (Values, already safe for display), the footer, the timeout, the language, and the THelpChatAction and THelpChatActionArgs themselves for a form that wants the raw values. The component creates the form for each question, owned by the host, and frees it afterwards. In FireMonkey the names are IFmxHelpChatConfirmDialog, TFmxHelpChatConfirmRequest and RegisterFmxHelpChatConfirmDialog, and the request is the same record with a FireMonkey host. HelpChatActionConfirmText builds the same question as plain text, for a message box or for FMX; THelpChatActionArgs.ToDisplayPairs gives the labelled values.
A refusal ends the plan
When the user says no, the model is told not to try again, not to try another way and not to go on with what depended on that action. And the library does not rely on the model agreeing: after a refusal, every later action of the same reply is refused without asking, and the model reads that it was not run because the user refused. Say no to create the company and create the lead is not even proposed.
When something goes wrong
Everything that can happen is told to the model in plain words, so that it explains itself to the user or tries something else:
| Outcome | The model is told |
|---|---|
| done | your AResult, or "the action was executed" |
| denied | the user did not allow it, and the plan stops there — later actions of the same reply are refused without asking |
| unknown | there is no action with that name |
| failed | the message of the exception your handler raised |
| timeout | it did not answer in time |
| cancelled | the reply was cancelled, or the assistant the action belongs to is no longer active |
An exception inside a handler is information, not a crash: raise Exception.Create('Il documento è aperto in modifica') is a perfectly good way to tell the assistant why it could not do what it was asked.
Watching what happens
procedure TMainForm.HelpChatActionExecuted(Sender: TObject; const AName: string;
const AOutcome: THelpChatActionOutcome; const AResult: string);
begin
StatusBar.Panels[3].Text := Format('Azione %s: %s', [AName, GetEnumName(TypeInfo(THelpChatActionOutcome), Ord(AOutcome))]);
Log(AName, AOutcome, AResult);
end;ActionsEnabled := False hides every action from the model without unregistering anything — useful for a read-only mode, a demo, or a user profile without the right to act.
What it needs
- A model provider.
claude,openaiandgeminiall call tools;stubanddocsearchignore them. Up toMaxToolRoundsmodel calls per reply (4 by default), which is what lets the assistant chain two actions and then comment. Running an action takes one more call to tell the model how it went, so withMaxToolRounds = 1no action is declared to the model at all; and when the last call of a reply still asks for one, it is not run and the reply ends with a note saying so, instead of ending as if it had been. The three APIs deliver a call differently - typed blocks, fragments tied by an index, a whole part - and your handler never sees the difference. - A remote engine too. With a remote server the model runs there and the actions still run here: the transport declares them to its session, and each call of the model comes back to the application - handler, main thread and confirmation as above. See Actions on a server for what the server may refuse.
Designing good actions
- One action, one intention.
draft_proposalis better thanset_field(name, value)called five times. - When a step needs a lookup, let the handler do it and let the exception talk. The company of a lead must exist:
create_leadof the CRM sample looks it up — an exact match, else the one name containing the text — and when there is none or more than one it raises an exception written for the model: "There is no account called X. Create it with create_account, then call create_lead again", or "More than one account matches X: A, B. Ask the user which one". The model creates the company (with its own confirmation) or asks the user, and the handler never returns the content of the database to the model. Count the rounds such a chain needs — lookup, create, create again, the answer — and raiseMaxToolRoundsaccordingly (the samples use 6). - An action that writes is idempotent. After a timeout the model may call it again:
create_accountchecks that the company is not there before adding it. - What an action returns is data. It goes back to the model as the result of the tool, and a model reads text. Keep it short and structured — a name, an id, a count — and never return free text typed by somebody else (notes, mail bodies): see Security and privacy.
- Prepare, do not commit. The CRM sample fills the draft with the customer and the line items and computes the total, then stops: Preview and Save Proposal stay with the user.
create_leadis the same idea — the record is written and its window opens, so correcting what the assistant understood is a normal edit. - Return something useful.
AResultis what the model reads to describe what happened; "Opened the Leads screen" produces a better sentence than an empty string. - Say no clearly. An exception message is read by the model and usually reaches the user in its own words.