askUserTool

这是一个内置且与 Agent 无关的 Tool，用于向用户提问并等待回答。该 Tool 支持自由文本问题、单选提示和多选提示。

该 Tool 通过原生的 Tool 暂停机制实现暂停：它会使用问题载荷调用 suspend()，使 Agent 发出 tool-call-suspended 事件并持久化运行状态。使用 agent.resumeStream(answer, { runId }) 恢复运行。

在 Agent 运行之外执行时（没有可用的 suspend），该 Tool 会返回一个易读的回退字符串，其中包含问题和选项。

使用示例

将 askUserTool 添加到 Agent 的 Tool 集：

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 },
})

处理暂停并恢复运行：

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)
  }
}

对于多选提示，使用字符串数组恢复运行：

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

输入 Schema

模型调用此 Tool 时使用以下参数：

question:

string

要向用户提出的问题。不得为空。

options?:

AskUserOption[]

提供给用户的结构化选项。省略时，提示为自由文本。

AskUserOption

label:

string

此选项的简短显示文本。选中后，该值会返回给模型。

description?:

string

此选项含义的说明。

selectionMode?:

'single_select' | 'multi_select'

控制用户可以选择多少个选项。提供选项时默认为 'single_select'。必须同时提供选项。

暂停载荷

tool-call-suspended 事件携带一个 suspendPayload，其结构与输入相同：

question:

string

正在询问的问题。

options?:

AskUserOption[]

结构化选项（如果有）。

selectionMode?:

'single_select' | 'multi_select'

解析后的选择模式。自由文本提示会省略此项。

恢复数据

将用户的回答传给 agent.resumeStream()：

• 自由文本和单选： 一个 string。
• 多选： 一个由所选选项标签组成的 string[]。