askUserTool

Tool intégré indépendant de l’Agent, qui pose une question à l’utilisateur et attend sa réponse. Il prend en charge les questions en texte libre ainsi que les invites à sélection unique ou multiple.

Le Tool se met en pause au moyen de la primitive native de suspension des Tools : il appelle suspend() avec le payload de la question, ce qui amène l’Agent à émettre un événement tool-call-suspended et à conserver l’état de l’exécution. Reprenez l’exécution avec agent.resumeStream(answer, { runId }).

Lorsqu’il est exécuté en dehors de l’exécution d’un Agent, sans suspend disponible, le Tool renvoie une chaîne de repli lisible contenant la question et les choix.

Exemple d’utilisation

Ajoutez askUserTool à l’ensemble de Tools d’un Agent :

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

Gérez la suspension et la reprise :

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

Pour les invites à sélection multiple, reprenez l’exécution avec un tableau de chaînes :

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

Schéma d’entrée

Le modèle appelle ce Tool avec les paramètres suivants :

question:

string

Question à poser à l’utilisateur. Ne doit pas être vide.

options?:

AskUserOption[]

Choix structurés proposés à l’utilisateur. En cas d’omission, l’invite accepte du texte libre.

AskUserOption

label:

string

Court texte d’affichage de cette option. Cette valeur est renvoyée au modèle lorsque l’option est sélectionnée.

description?:

string

Explication de la signification de cette option.

selectionMode?:

'single_select' | 'multi_select'

Détermine le nombre d’options que l’utilisateur peut sélectionner. La valeur par défaut est 'single_select' lorsque des options sont fournies. Nécessite des options.

Payload de suspension

L’événement tool-call-suspended transporte un suspendPayload ayant la même structure que l’entrée :

question:

string

Question posée.

options?:

AskUserOption[]

Choix structurés, le cas échéant.

selectionMode?:

'single_select' | 'multi_select'

Mode de sélection résolu. Omis pour les invites en texte libre.

Données de reprise

Transmettez la réponse de l’utilisateur à agent.resumeStream() :

• Texte libre et sélection unique : une valeur string.
• Sélection multiple : une valeur string[] contenant les libellés des options sélectionnées.