Human-in-the-loop

Some tools change data in your systems, for example creating an order or posting a booking. For these tools you can require that the user approves every call. The agent then pauses, shows the user what it is about to do, and only continues after the user confirms.

What users see

1. The agent decides to call a tool that requires approval.
2. The chat shows a dialog with the action and its values, for example the category and priority of a ticket.
3. The user confirms or rejects.
4. If the user confirms, the tool runs. If the user rejects, or does not answer within 5 minutes, the tool does not run and the agent is informed.

Configure approval

Single tools

Set requires_confirmation to true in the tool’s configuration:

{
  "id": "create-ticket",
  "component_type": "tool",
  "config": {
    "name": "create_ticket",
    "description": "Create a support ticket",
    "requires_confirmation": true
  }
}

Toolboxes

For a toolbox, list the operations that need approval. Operations that only read data can stay without approval:

{
  "component_type": "toolbox",
  "config": {
    "requires_confirmation": ["post_downtime", "put_downtime"]
  }
}

Customize the dialog

By default, the dialog shows the tool name as title and the tool’s arguments as the message. A tool can provide its own text with the arguments confirmation_title and confirmation_message. These arguments are not shown in the list of values.

Handle approvals in your own application

If you build your own client, see Streaming events for how to receive approval requests and send the user’s answer.

Tip

Use approval for every tool that creates, changes or deletes data, at least until you trust the agent’s behavior.