Ask before an action runs

For actions with consequences, such as placing an order, refunding one or messaging someone, have the agent ask the visitor first. Add consequentialHint: true:

HelpAI('registerTool', {
  name: 'refund_order',
  description: "Refund one of the visitor's orders. Use it only when the visitor asks for a refund.",
  inputSchema: {
    type: 'object',
    properties: { orderId: { type: 'string', description: 'The order number' } },
    required: ['orderId'],
  },
  annotations: { consequentialHint: true },
  execute: ({ orderId }) => requestRefund(orderId), // your own code
});

What the visitor sees#

1. When the agent wants to run the tool, the visitor gets an approval card showing what it will do with which input, with Reject and Approve.
2. Approve: the tool runs in their browser, and the agent continues with the result.
3. Reject: the tool never runs. The card reads Denied, and the agent learns that the visitor declined.

Approval cards need Visitor approvals, which is on by default in the deployment's Chat widget tab → Features. With it off, a tool that asks first can't be approved, so it never runs.

help.ai keeps the approval with the call and accepts the tool's result only after the visitor approved it, so a page can't skip the question.

Stop and new messages#

• While a tool runs, the send button turns into Stop. Selecting it ends the tool: your execute sees its signal abort, nothing goes to the agent, and the card reads Not completed. A stopped call never runs again, even after a reload.
• If the visitor sends another message while a tool runs, the tool ends the same way and the agent answers the new message.
• There's no time limit: the agent waits for your tool. Long-running tools should pass the signal on, so they stop when the visitor does:

async execute({ query }, { signal }) {
  const response = await fetch(`/api/search?q=${encodeURIComponent(query)}`, { signal });
  return response.json();
},

Reloads#

If the page reloads while a tool runs, it isn't run again. The card reads Not completed, and the agent is told the page reloaded, so the tool may or may not have taken effect, and checks with the visitor before trying again. A result that was ready but not yet sent is sent after the reload.