Skip to main content

​
What it does

The Ask User Question tool lets your agent pause mid-conversation to gather information from the user through an interactive question UI. The agent presents questions with predefined options or free text input, waits for the user’s response, then continues with full context of their answers. This is a human-in-the-loop tool — it only works in interactive chat sessions, not in scheduled tasks or automated workflows.

​
Key features

  • Interactive question UI with clickable option buttons
  • Support for single or multiple questions in one tool call
  • Client-side pagination for multi-question flows (no extra API round-trips)
  • Free text input with optional predefined options
  • Skip/dismiss option for each question
  • Compact answered state after user responds

​
Parameters

​
Single question mode

ParameterTypeRequiredDescription
questionstringYes*The question to ask the user
optionsarrayNoPredefined options with label (required) and description (optional)
allow_free_textbooleanNoShow free text input. Defaults to true when no options, false when options provided

​
Multiple questions mode

ParameterTypeRequiredDescription
questionsarrayYes*Array of question objects, each with question, options, and allow_free_text
Use either question (single) or questions (multiple), not both.

​
Common use cases

​
Gathering preferences before a task

{
  "questions": [
    {
      "question": "What's your budget?",
      "options": [
        {"label": "Under $1000"},
        {"label": "$1000-$3000"},
        {"label": "$3000+"}
      ]
    },
    {
      "question": "Do you prefer beach or mountains?",
      "options": [
        {"label": "Beach"},
        {"label": "Mountains"}
      ]
    }
  ]
}
Ask multiple questions at once with pagination — all answers submitted together.

​
Quick clarification with options

{
  "question": "Which format would you like the report in?",
  "options": [
    {"label": "PDF", "description": "Best for sharing"},
    {"label": "PowerPoint", "description": "Best for presenting"},
    {"label": "Google Sheet", "description": "Best for collaboration"}
  ]
}
Single question with descriptive options.

​
Open-ended input

{
  "question": "What specific topics should I focus on in the analysis?"
}
Free text input when predefined options don’t make sense.

​
Options with optional elaboration

{
  "question": "What's your experience level with this topic?",
  "options": [
    {"label": "Beginner"},
    {"label": "Intermediate"},
    {"label": "Expert"}
  ],
  "allow_free_text": true
}
User can select an option and optionally add more detail, or just click Next/Submit with their selection.

​
How it works

  1. Agent calls ask_user_question with question(s) and options
  2. Agent execution pauses — no follow-up text is generated
  3. The chat UI renders an interactive question component
  4. For multiple questions, the user pages through each one client-side
  5. After answering the last question, all answers are sent as a single user message
  6. The agent receives the answers and continues naturally

​
Best practices

  • Use predefined options when possible — they’re faster for users and produce cleaner answers for the agent
  • Keep questions concise and specific
  • Use the questions array to batch related questions instead of calling the tool multiple times
  • Add description to options when the label alone might be ambiguous
  • Use allow_free_text: true with options when you want the user to be able to elaborate

​
Limitations

  • Only works in interactive chat sessions (not scheduled tasks, email triggers, or API calls)
  • The agent fully stops after calling this tool — it cannot do other work while waiting
  • On page reload, previously answered questions show as “(answered)” without the specific answer text
  • Call Agent - Delegate tasks to other agents after gathering user preferences
  • Send Email - Send results based on user choices
  • Schedule Task - Set up recurring tasks based on user preferences