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

# 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](https://mastra.zisheng.pro/fr/docs/agents/agent-approval) : 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 :

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

Gérez la suspension et la reprise :

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

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

```typescript
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.

**options.label** (`string`): Court texte d’affichage de cette option. Cette valeur est renvoyée au modèle lorsque l’option est sélectionnée.

**options.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.