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

# Tools

Les signatures d’exécution des Tools ont été mises à jour pour utiliser des paramètres d’entrée et de contexte distincts, avec des propriétés de contexte réorganisées.

## Modifications

### Signature d’exécution de `createTool` au format `(inputData, context)`

Toutes les fonctions d’exécution de `createTool` utilisent désormais une signature avec les paramètres distincts `inputData` et `context`, au lieu d’un seul objet déstructuré. Les entrées du Tool et le contexte d’exécution sont maintenant transmis indépendamment.

Cette modification de signature s’applique uniquement à `createTool`. Pour les appels `createStep` des Workflows, conservez la signature `async (inputData, context)`.

Pour migrer, mettez à jour les signatures `createTool` afin d’utiliser `inputData` comme premier paramètre, typé à partir de `inputSchema`, et `context` comme second paramètre.

```diff
createTool({
    id: 'weather-tool',
-   execute: async ({ context, requestContext, mastra }) => {
-     const location = context.location;
-     const userTier = requestContext.get('userTier');
-     return getWeather(location, userTier);
-   },
+   execute: async (inputData, context) => {
+     const location = inputData.location;
+     const userTier = context?.requestContext?.get('userTier');
+     return getWeather(location, userTier);
+   },
  });
```

### Organisation des propriétés de contexte de `createTool`

Les propriétés de contexte de `createTool` sont désormais organisées en espaces de noms. Les propriétés propres aux Agents se trouvent sous `context.agent`, celles propres aux Workflows sous `context.workflow` et celles propres à MCP sous `context.mcp`. Cette modification améliore l’organisation et clarifie la surface de l’API.

Pour les Tools exécutés dans un Agent, accédez aux propriétés propres à l’Agent via `context.agent`.

```diff
createTool({
    id: 'suspendable-tool',
    suspendSchema: z.object({ message: z.string() }),
    resumeSchema: z.object({ approval: z.boolean() }),
-   execute: async ({ context, suspend, resumeData }) => {
-     if (!resumeData) {
-       return await suspend({ message: 'Waiting for approval' });
-     }
-     if (resumeData.approval) {
-       return { success: true };
-     }
-   },
+   execute: async (inputData, context) => {
+     if (!context?.agent?.resumeData) {
+       return await context?.agent?.suspend({
+         message: 'Waiting for approval',
+       });
+     }
+     if (context.agent.resumeData.approval) {
+       return { success: true };
+     }
+   },
  });
```

Pour les Tools exécutés dans un Workflow, accédez aux propriétés propres au Workflow via `context.workflow`.

```diff
createTool({
    id: 'workflow-tool',
-   execute: async ({ workflowId, runId, state, setState }) => {
-     const currentState = state;
-     setState({ step: 'completed' });
-     return { result: 'done' };
-   },
+   execute: async (inputData, context) => {
+     const currentState = context?.workflow?.state;
+     context?.workflow?.setState({ step: 'completed' });
+     return { result: 'done' };
+   },
  });
```

Le `suspendPayload` est validé par rapport à `suspendSchema` lors de l’exécution du Tool. Si le suspendPayload ne correspond pas à `suspendSchema`, un avertissement est consigné et l’erreur est retournée comme sortie du Tool, mais la suspension se poursuit. De même, lorsque le Tool reprend, `resumeData` est validé par rapport à `resumeSchema`. Si resumeData ne correspond pas à `resumeSchema`, le Tool retourne une `ValidationError`, ce qui empêche la reprise du Tool.

Pour ignorer la validation de `suspendSchema` ou `resumeSchema`, ne définissez pas `suspendSchema` ni `resumeSchema` lors de la création du Tool.

> **Remarque:** Pour les changements de contexte de Tool propres à MCP, consultez le [guide de migration MCP](https://mastra.zisheng.pro/fr/guides/migrations/upgrade-to-v1/mcp).

### De `RuntimeContext` à `RequestContext`

La classe `RuntimeContext` a été renommée `RequestContext` dans l’ensemble du contexte d’exécution des Tools. Ce nouveau nom identifie la classe comme des données propres à une requête.

Pour migrer, remplacez les références à `runtimeContext` par `requestContext` dans les fonctions d’exécution des Tools.

```diff
createTool({
    id: 'my-tool',
    execute: async (inputData, context) => {
-     const userTier = context?.runtimeContext?.get('userTier');
+     const userTier = context?.requestContext?.get('userTier');
      return { result: userTier };
    },
  });
```

> **Codemod:** Vous pouvez utiliser la CLI codemod de Mastra pour mettre à jour automatiquement vos imports :
>
> ```bash
> npx @mastra/codemod@latest v1/runtime-context .
> ```

Cela s’applique à toutes les exécutions de Tools, qu’elles soient appelées directement ou par l’intermédiaire d’Agents et de Workflows. Le rétrécissement de type garantit que vous gérez les erreurs de validation de façon appropriée et évite les erreurs d’exécution lors de l’accès aux propriétés de sortie.

### Validation de la sortie d’un Tool avec `outputSchema`

Les Tools ayant un `outputSchema` valident désormais leurs valeurs de retour à l’exécution. Auparavant, `outputSchema` était uniquement utilisé pour l’inférence de types : la sortie n’était jamais validée.

Si votre Tool retourne des données qui ne correspondent pas à son `outputSchema`, il retourne désormais une `ValidationError` au lieu des données non valides.

Pour corriger les erreurs de validation, assurez-vous que la sortie du Tool correspond à la définition du schéma :

```diff
const getUserTool = createTool({
    id: "get-user",
    outputSchema: z.object({
      id: z.string(),
      name: z.string(),
      email: z.string().email(),
    }),
    execute: async (inputData) => {
-     return { id: "123", name: "John" }; // Missing email
+     return { id: "123", name: "John", email: "john@example.com" };
    },
  });
```

Lorsque la validation échoue, le Tool retourne une `ValidationError` :

```diff
+ // Before v1 - invalid output would silently pass through
  await getUserTool.execute({});
- // { id: "123", name: "John" } - missing email
+ // {
+ //   error: true,
+ //   message: "Tool output validation failed for get-user. The tool returned invalid output:\n- email: Required\n\nReturned output: {...}",
+ //   validationErrors: { ... }
+ // }
```

### Le type de retour de `tool.execute` inclut `ValidationError`

Le type de retour de `tool.execute` inclut désormais `ValidationError` pour gérer les échecs de validation. Vous devez réduire le type du résultat avant d’accéder aux propriétés du schéma de sortie afin de satisfaire la vérification de types de TypeScript.

Lorsque vous appelez `tool.execute`, vérifiez si le résultat contient une erreur avant d’accéder aux propriétés de sortie :

```typescript
const result = await getUserTool.execute({})

// Type-safe check for validation errors
if ('error' in result && result.error) {
  console.error('Validation failed:', result.message)
  console.error('Details:', result.validationErrors)
  return
}

// TypeScript knows result is valid here
console.log(result.id, result.name, result.email)
```

Vous pouvez aussi mettre à jour `outputSchema` pour qu’il corresponde à votre sortie réelle, ou supprimer complètement `outputSchema` si vous n’avez pas besoin de validation.

### Exécution directe d’un Tool

La propriété `tool.execute` est facultative dans le système de types afin de prendre en charge les définitions de Tools côté client, où la logique d’exécution est gérée séparément. Lorsque vous appelez `execute` directement sur une instance de Tool, plutôt que par l’intermédiaire d’Agents ou de Workflows, utilisez le chaînage facultatif ou l’assertion non nulle :

```typescript
// Optional chaining (recommended)
const result = await weatherTool.execute?.({ location: 'New York' }, {})

// Non-null assertion (when you know execute exists)
const result = await weatherTool.execute!({ location: 'New York' }, {})
```