askUserTool

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

此 Tool 透過原生的 Tool 暫停機制暫停執行：它會使用問題 payload 呼叫 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'

控制使用者可選取的選項數量。提供 options 時，預設為 'single_select'。必須同時提供 options。

暫停 payload

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

question:

string

目前向使用者提出的問題。

options?:

AskUserOption[]

結構化選項（如有）。

selectionMode?:

'single_select' | 'multi_select'

解析後的選取模式。自由文字提示會省略此欄位。

繼續執行的資料

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

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