> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# askUserTool

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

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

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

## 使用示例

将 `askUserTool` 添加到 Agent 的 Tool 集：

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

处理暂停并恢复运行：

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

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

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

## 输入 Schema

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

**question** (`string`): 要向用户提出的问题。不得为空。

**options** (`AskUserOption[]`): 提供给用户的结构化选项。省略时，提示为自由文本。

**options.label** (`string`): 此选项的简短显示文本。选中后，该值会返回给模型。

**options.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[]`。