askUserTool

ユーザーに質問し、その回答を待つ、Agent に依存しない組み込み Tool です。自由入力形式の質問、単一選択形式のプロンプト、複数選択形式のプロンプトをサポートします。

この Tool は、ネイティブのTool 中断プリミティブを介して処理を一時停止します。質問のペイロードを渡して suspend() を呼び出すと、Agent は tool-call-suspended イベントを発行し、実行状態を永続化します。agent.resumeStream(answer, { runId }) で実行を再開します。

Agent の実行外（suspend が利用できない場合）で実行すると、質問と選択肢を含む読みやすいフォールバック文字列を返します。

使用例

Agent の Tool セットに askUserTool を追加します。

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

入力スキーマ

モデルは、次のパラメーターを指定してこの Tool を呼び出します。

question:

string

ユーザーへの質問。空の文字列は指定できません。

options?:

AskUserOption[]

ユーザー向けの構造化された選択肢。省略すると、自由入力形式のプロンプトになります。

AskUserOption

label:

string

この選択肢に表示する短いテキスト。選択されると、この値がモデルに返されます。

description?:

string

この選択肢の意味を示す説明。

selectionMode?:

'single_select' | 'multi_select'

ユーザーが選択できる選択肢の数を制御します。選択肢が指定されている場合のデフォルトは 'single_select' です。options の指定が必要です。

中断ペイロード

tool-call-suspended イベントには、入力と同じ形式の suspendPayload が含まれます。

question:

string

ユーザーに提示される質問。

options?:

AskUserOption[]

構造化された選択肢（存在する場合）。

selectionMode?:

'single_select' | 'multi_select'

確定した選択モード。自由入力形式のプロンプトでは省略されます。

再開データ

ユーザーの回答を agent.resumeStream() に渡します。

• 自由入力および単一選択： string。
• 複数選択： 選択された選択肢のラベルを格納した string[]。