Ask the user
ask_user lets an AI Agent stop and ask the person it’s working with for information only they have — a missing detail, a choice, a confirmation. The agent’s run pauses, the user answers in the chat, and the agent continues with the answers. Category: Action · Setup: none.
The agent doesn’t just ask one free-text question. It can show a form: several questions at once, each with the right input — buttons, a dropdown, a date picker, a star rating, and so on.
ask_user is AI Agent only, and the agent only uses it when you attach it to a skill. See Attach tools.
How the form is decided
You don’t design the form in advance. At run time the agent reads the user’s request, works out what it still needs, and describes the questions in its ask_user call. qRaptor turns that into the form.
For example, if a user writes “Book a flight to Goa”, the agent might ask in one form for:
- a travel date (date picker)
- the number of travellers (number box)
- the cabin class (one of three buttons, with Recommended on Economy)
- meal preferences (pick up to two)
When the agent needs only one thing, it can ask a plain question instead. The user then gets a single text box.
Question types
| Question type | What the user sees |
|---|---|
| Short text, long text | A one-line or multi-line text box |
| Email, phone, web link | A text box that checks the format |
| Number, slider, star rating | A number box, a slider, or 1–N stars |
| Pick one option | Buttons, a radio list or a dropdown — with optional Recommended badge and Other… box |
| Pick several options | Chips, checkboxes or a searchable list |
| Yes / No | A switch, a tick box or Yes/No buttons |
| Date, time, date and time, date range | Date and time pickers |
| List of items | Rows with Add another |
| Agreement tick box | A box the user must tick to submit |
| Info note | Read-only text inside the form |
| File upload | A file picker — only when file upload is turned on for the agent |
A form can also:
- group questions under section headings
- use two columns on wide screens
- show a question only when an earlier answer matches — for example, “New date” appears only after the user picks “Change the date”
- offer a Skip button
Required questions are checked before the form is sent. Each problem shows under its question.
Set limits for an agent
In a skill’s tool configuration for Ask the user, the Ask user forms panel sets limits the agent can’t go beyond:
| Setting | Default | What it does |
|---|---|---|
| Allowed question types | All except file upload | Question types the agent may use. |
| Max questions per form | 10 | 1 to 20. |
| Skip button | Agent decides | Or always show, or never show. |
| Default layout | Single column | Used when the agent doesn’t choose one. |
| Answer timeout (hours) | 24 | How long a question waits for a reply. |
| File upload | Off | Turn on to allow file questions. Then set Max files per question (1–5) and Max file size (1–10 MB). |
If the agent asks for something outside these limits, the form isn’t shown. The agent is told what to change and asks again, so the user never sees a broken form.
Make the forms predictable
The agent picks the questions itself, so the same request can give slightly different forms. When you need a specific form every time, describe it in the skill’s System prompt. For example:
When the user wants to book a flight, call ask_user once with these fields:
travel_date (date, today or later), travellers (number, 1–9),
cabin (pick one: Economy, Premium economy, Business; recommend Economy)
and meal (pick up to two, optional).Test the form
On the tool’s Test tab, and on the Test Tool side of a skill’s tool configuration, you see the form itself instead of JSON:
- Describe the questions in the labelled fields, or pick one of the examples.
- Click Preview form. The form appears exactly as it will in chat. If it can’t be shown, you see the message the agent would get.
- Fill it in and submit (or skip). What the agent receives shows the answers with their labels, and the raw tool result.
Nothing you enter on the Test side is saved to the skill.
What the agent receives
The tool result gives the agent:
answers— the values by question, ready to pass to other tools.answers_readable— each question’s label and the answer as the user saw it (for example “Business”, not “biz”).answer— a one-line summary. For a single question, this is the reply itself.skipped—truewhen the user pressed Skip. The agent continues on its own judgement.
After the user submits, the form collapses to a short summary of their answers.
Where it works
The form appears in:
- the AI Agent’s preview chat
- a deployed Copilot
- each agent’s tab when several agents in a multi-agent system ask at once
If the user reopens the conversation before answering, the form is still there.
The floating Copilot embedded inside a generated app, and Copilot pages inside a generated app, don’t show ask_user forms yet.
Good to know
- No passwords or card numbers.
ask_userrefuses questions that ask for passwords, API keys or card details, because answers are stored in the conversation. Users add credentials in Configuration & secrets instead. - Unattended runs. On a scheduled, triggered or API run there’s nobody to answer. A multi-agent system follows its When nobody is available to approve setting — see Loops, failures & approvals.
Common issues
- The user only gets one text box — The agent asked a single question. If you need a form, describe it in the skill’s system prompt (see above).
- A file question never appears — File upload is off by default. Turn it on in the skill’s Ask user forms settings.
- The agent never asks anything — Check that Ask the user is attached to the active skill and its HIL setting isn’t Off.
ask_useronly works with HIL on.