askUserTool

A built-in, agent-agnostic tool that asks the user a question and waits for their response. The tool supports free-text questions, single-select prompts, and multi-select prompts.

The tool pauses through the native tool suspension primitive: it calls suspend() with the question payload, which makes the agent emit a tool-call-suspended event and persist run state. Resume the run with agent.resumeStream(answer, { runId }).

When executed outside an agent run (no suspend available), the tool returns a readable fallback string containing the question and choices.

Usage example

Add askUserTool to an agent's toolset:

src/mastra/agents/index.ts

import { Agent } from '@mastra/core/agent'
import { askUserTool } from '@mastra/core/tools'

const agent = new Agent({
  id: 'assistant',
  name: 'Assistant',
  instructions: 'Ask the user for clarification when the request is ambiguous.',
  model,
  tools: { askUserTool },
})

Handle the suspension and resume:

src/run.ts

const stream = await agent.stream('Summarize my project')

for await (const chunk of stream.fullStream) {
  if (chunk.type === 'tool-call-suspended') {
    const { question, options, selectionMode } = chunk.payload.suspendPayload
    // Present the question to the user, collect their answer, then resume:
    const resumed = await agent.resumeStream('The main repo', { runId: stream.runId })
    for await (const c of resumed.textStream) process.stdout.write(c)
  }
}

For multi-select prompts, resume with a string array:

await agent.resumeStream(['Add tests', 'Update docs'], { runId: stream.runId })

Input schema

The model calls this tool with the following parameters:

question:

string

The question to ask the user. Must be non-empty.

options?:

AskUserOption[]

Structured choices for the user. When omitted, the prompt is free-text.

AskUserOption

label:

string

Short display text for this option. This value is returned to the model when selected.

description?:

string

Explanation of what this option means.

selectionMode?:

'single_select' | 'multi_select'

Controls how many options the user can select. Defaults to 'single_select' when options are provided. Requires options.

Suspend payload

The tool-call-suspended event carries a suspendPayload with the same shape as the input:

question:

string

The question being asked.

options?:

AskUserOption[]

The structured choices, if any.

selectionMode?:

'single_select' | 'multi_select'

The resolved selection mode. Omitted for free-text prompts.

Resume data

Pass the user's answer to agent.resumeStream():

• Free-text and single-select: A string.
• Multi-select: A string[] of selected option labels.