ask

Pauses the agent and asks the user for one or more inputs. When the user answers, the agent resumes at this command, with the answers as the command's result.

Fields

Each element of inputs describes one control:

How a pause works

The agent's position, every function, loop and tool call in progress, is saved with the conversation. The run then ends with a result that tells the UI, or the chat bot, what to ask. The user's next message on the conversation carries the answers. The agent resumes at the same position, and the ask command returns a dict of the answers keyed by input name. Execution then continues. Inputs the user did not answer are asked for again. Hidden inputs are sent back by the application without being shown. Variables set before the pause keep their values. When several branches of a parallel command ask, the run pauses once, with every branch's questions.

Example

"ask": {
  "message": "A few details to book the trip:",
  "inputs": [
    { "name": "departure", "type": "str", "label": "Departure city" },
    { "name": "seat", "type": "chooseOne", "label": "Seat",
      "options": ["aisle", "window"], "default": "aisle" },
    { "name": "notes", "type": "text", "label": "Anything else", "description": "Optional" }
  ]
},
"var": { "answers": "{ result }" },
"progress": "{ f'Booking from {answers['departure']}, {answers['seat']} seat' }"

Rules

• An input cannot be named query.
• ask is not allowed inside a for block or in error handling, nor in any function called from those places. The agent fails validation.
• ask is allowed in a function run by parallel. The command waits for every branch, sends the questions of all the paused branches together, and resumes each branch with its own answers.
• ask is allowed inside a function that the LLM calls as a tool. The tool loop resumes where the agent paused.
• Values typed as password are masked in the UI but are ordinary strings to the agent. Keep them out of agent and conversation variables.