Answering a question and doing something are different risks. A wrong answer can be corrected in the next message. A booking made twice, or an email sent to the wrong person, cannot be taken back by the assistant.
In Pragence, anything with an effect outside the conversation is an action. Actions that need a person’s approval wait for it, run once, and leave a receipt. This post explains each part and the rules behind them.
Off, then simulated, then real
Actions are switched off by default (ENABLE_ACTIONS=false). When you switch them on, they start in dry-run mode (ACTION_DRY_RUN=true). In dry-run mode an action is described and recorded but never executed. The receipt the person sees is marked as test mode, and nothing is handed off to your CRM, because nothing was committed.
You leave dry-run mode by changing the setting yourself. Actions that call external web addresses can only reach host names on an allow-list you configure.
Step 1: the assistant proposes
When the assistant decides an action would help, it first checks the arguments against that action’s schema. It then writes a proposal: which action, with which details, described in plain language. The conversation pauses at a saved checkpoint.
On the website widget and in the portal, the person sees a confirmation card that says “Please check these details before I send anything.” They can confirm or decline.
Step 2: the approval is bound to the exact proposal
The server issues the approval. The client only returns it. Each proposal gets an approval window of fifteen minutes from the moment it is issued. The window does not refresh.
The server also computes an approval token. It is a hash over the saved checkpoint and everything that defines the proposal: the organization, project, person and thread, the agent, the published configuration revision, the exact proposed actions and their arguments, whether it is a dry run, and the window’s start and end times.
To approve, the client must send back that exact token. If the proposal changed in the meantime, the tokens no longer match and the server answers with HTTP 409 and “Review the current proposal before confirming”. A client cannot invent a token, widen the window or swap in different arguments. An expired or malformed window is not treated as consent.
If the person declines, the reply is “No problem, nothing was sent.”
Step 3: the action runs once
Approval alone does not stop an action from running twice. Networks retry. Workers restart. So before any effect, Pragence writes an execution record to the database and commits it. The record holds:
- an operation key built from the action, project, person, thread and the action’s idempotency key;
- a hash of the arguments;
- a status of “running” and a five-minute lease for the worker that owns it.
When the same operation arrives again, the record decides what happens:
- If it already succeeded, the stored result is returned and the effect is not repeated.
- If the arguments differ from the first attempt, it is refused.
- If another worker is still running it, it is reported as in progress.
- If the lease has expired with no result, the status becomes “uncertain” and no other worker takes over.
Step 4: the receipt
When the action finishes, its result is written to the same record as the receipt, with success or failure. For supported actions whose effect is the receipt itself, the receipt and any follow-up delivery to your systems commit in one database transaction. Either both are saved or neither is.
The person sees a short summary. A success reads “Done.” followed by the action’s output. A failure tells them it did not go through and suggests trying again or asking to talk to a person.
When a committed action should reach your CRM, Pragence queues a hand-off to a signed webhook or to HubSpot. Each hand-off event has an ID derived from the organization, thread, action and idempotency key, so a replayed action queues nothing new.
When the outcome is uncertain
A timeout does not tell you whether the other system acted. The payment may have gone through and the response may have been lost. Retrying blindly can charge twice. That is why an expired lease becomes “uncertain” and stays that way.
A person resolves uncertain executions. Pragence does not retry them. A project administrator can list the executions and their receipts, then record a reconciliation. The request must state:
- the status they expect the record to have (running, uncertain or failed);
- the resolution, succeeded or cancelled;
- evidence of what actually happened, such as a reference from the other system;
- an explicit confirmation that the worker was stopped and can no longer apply the effect.
Reconciliation records the verified outcome. It never runs the action, its compensation or a delivery. If the outcome was a success, the administrator can choose to queue the original hand-off at that point.
Phone calls are stricter
On a phone call, the backend holds the voice session, so there is no screen for a confirmation card. Actions that require confirmation are declared to the voice model as unavailable by policy. They are never confirmed automatically on a call. Only actions that do not need approval can run there.
What approval does not mean
An approval covers one proposal, in one conversation, for a short time. It is not a standing permission. It also does not turn a review into a decision. In Pragence Admissions, for example, staff review applications, and the institution’s authorized people keep every admission decision.
If you are planning which actions to enable, start in dry-run mode. Read the proposals the assistant makes against real conversations, check that each one describes exactly what would happen, and switch to live execution only for the actions you are happy to approve one at a time.