Search2oSearch2o
Docs / Command reference

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

FieldTypeDefaultDescription
inputslist of input objectThe inputs to ask the user for.
messagedynamic string"Please provide these inputs"Shown to the user above the input fields.

Each element of inputs describes one control:

FieldTypeDefaultDescription
namerequiredstringThe name of the input. The user's answer is returned under this name.
labelstringThe label shown next to the input.
descriptionstringHelp text shown to the user under the input.
optionslist of stringThe values the user chooses from, for chooseOne and chooseMany.
defaultstringThe value the input starts with.
hiddenbooleanfalseSent back from the UI without being shown to the user.

How a pause works

commandsrunaskpauseposition savedwith the conversationUI shows a formuser answers laterthe answers arrive as the next messageaskresumes hereresult = answerskeyed by input namerest of the agentvariables restoredCommands before the pause are not re-executed; a function, loop or LLM tool loop in progress continues where it was.
Pausing on ask and resuming with the answers

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 what to ask. The user's next message on the conversation carries the answers. The agent resumes at the same position, which 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 come back with their default. Variables set before the pause keep their values.

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, in error handling, or in a function run by parallel, nor in any function called from those places. The agent fails validation.
  • 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. They are best not stored in agent or conversation variables.