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.

  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.

  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.

  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.

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.

  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 :

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 :

  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 :

+ // 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 :

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 :

// 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' }, {})