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

# askUserTool

這是一個不限定 Agent 的內建 Tool，會向使用者提問並等待回覆。此 Tool 支援自由文字問題、單選提示與多選提示。

此 Tool 透過原生的 [Tool 暫停](https://mastra.zisheng.pro/zh-TW/docs/agents/agent-approval)機制暫停執行：它會使用問題 payload 呼叫 `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'`): 控制使用者可選取的選項數量。提供 options 時，預設為 'single\_select'。必須同時提供 options。

## 暫停 payload

`tool-call-suspended` 事件會攜帶 `suspendPayload`，其結構與輸入相同：

**question** (`string`): 目前向使用者提出的問題。

**options** (`AskUserOption[]`): 結構化選項（如有）。

**selectionMode** (`'single_select' | 'multi_select'`): 解析後的選取模式。自由文字提示會省略此欄位。

## 繼續執行的資料

將使用者的回答傳給 `agent.resumeStream()`：

- **自由文字與單選：** 一個 `string`。
- **多選：** 由所選選項標籤組成的 `string[]`。