Workflows dynamiques

beta

Cette fonctionnalité est en bêta. Des changements incompatibles peuvent survenir sans hausse de version majeure tant que l’API n’est pas stable.

Les Workflows dynamiques sont des définitions de Workflow exprimées sous forme de données plutôt que de code. Une définition est un document JSON qui décrit les schémas du Workflow et son graphe d’étapes. Mastra valide la définition, l’enregistre comme Workflow exécutable, puis la conserve dans le stockage afin qu’elle survive aux redémarrages du processus.

Comme une définition ne contient aucune fermeture JavaScript, tout système capable de produire du JSON peut créer un Workflow : client HTTP, LLM, éditeur visuel ou vos propres Tools. Une fois enregistré, un Workflow dynamique s’exécute via la même API qu’un Workflow défini dans le code.

Quand utiliser des Workflows dynamiques

Utilisez les Workflows dynamiques lorsque des utilisateurs, Agents, éditeurs visuels ou systèmes externes doivent créer des Workflows sans modifier le code de l’application ni effectuer un nouveau déploiement.

Continuez à définir les Workflows avec createWorkflow() lorsqu’ils appartiennent au code source de votre application ou nécessitent des fonctions d’étape personnalisées. Les Workflows dynamiques peuvent appeler des Agents, Tools et Workflows déjà enregistrés sur l’instance Mastra.

Démarrage rapide

L’exemple suivant enregistre un Tool et l’appelle depuis un Workflow dynamique, avant d’exécuter ce dernier. LibSQLStore conserve la définition dans mastra.db, ce qui permet à Mastra de la restaurer après un redémarrage.

src/dynamic-workflow.ts

import { Mastra } from '@mastra/core/mastra'
import { createTool } from '@mastra/core/tools'
import { LibSQLStore } from '@mastra/libsql'
import { z } from 'zod'

const greetingTool = createTool({
  id: 'create-greeting',
  description: 'Create a greeting for a name',
  inputSchema: z.object({
    name: z.string(),
  }),
  outputSchema: z.object({
    message: z.string(),
  }),
  execute: async ({ name }) => ({
    message: `Hello, ${name}!`,
  }),
})

const mastra = new Mastra({
  storage: new LibSQLStore({
    id: 'mastra-storage',
    url: 'file:./mastra.db',
  }),
  tools: { 'create-greeting': greetingTool },
})

await mastra.addDynamicWorkflow({
  id: 'greeting-workflow',
  description: 'Create a greeting for the supplied name',
  inputSchema: {
    type: 'object',
    properties: {
      name: { type: 'string' },
    },
    required: ['name'],
  },
  outputSchema: {
    type: 'object',
    properties: {
      message: { type: 'string' },
    },
    required: ['message'],
  },
  graph: [
    {
      type: 'tool',
      id: 'greet',
      toolId: 'create-greeting',
    },
  ],
})

const workflow = mastra.getWorkflow('greeting-workflow')
const run = await workflow.createRun()
const result = await run.start({
  inputData: { name: 'Ada' },
})

if (result.status === 'success') {
  console.log(result.result.message)
}

Le Workflow affiche Hello, Ada!. L’appel à addDynamicWorkflow() valide la définition avant toute modification du stockage ou du registre actif des Workflows.

La définition utilise JSON Schema, car elle doit supporter un aller-retour en JSON. Le graph décrit les composants enregistrés à appeler et la circulation des données entre eux. Consultez la référence des définitions de Workflow dynamique pour découvrir chaque champ et chaque entrée du graphe.

Créer et mettre à jour les définitions

Une définition peut provenir de toute source qui produit du JSON. Par exemple, une route d’API peut accepter une définition créée par un éditeur visuel et l’enregistrer directement :

const definition = await request.json()
await mastra.addDynamicWorkflow(definition)

Enregistrer d’abord les dépendances

Enregistrez les composants référencés sur la même instance Mastra avant d’ajouter le Workflow dynamique. Les entrées d’Agent et de Workflow imbriqué utilisent leurs ID intrinsèques. Une entrée de Tool utilise sa clé dans l’objet Mastra nommé tools ; le démarrage rapide enregistre donc le Tool sous create-greeting avant de référencer cette clé avec toolId.

Utilisez une entrée mapping lorsque la sortie d’une étape ne correspond pas à l’entrée de l’étape suivante. Les entrées de mapping peuvent lire les données de l’entrée du Workflow et les résultats des étapes précédentes, ainsi que l’état du Workflow et le contexte de requête. La référence des définitions répertorie les descripteurs de mapping pris en charge.

Remplacer un Workflow

Ajoutez une nouvelle définition avec le même id pour remplacer la définition conservée et l’enregistrement actif :

await mastra.addDynamicWorkflow(updatedDefinition)

Les nouvelles exécutions utilisent le graphe mis à jour. Celles qui ont déjà démarré poursuivent leur graphe d’origine.

Ajouter ensemble des Workflows imbriqués

Lorsqu’un Workflow racine référence des Workflows auxiliaires qui ne sont pas encore enregistrés, ajoutez l’ensemble complet avec addDynamicWorkflows() :

await mastra.addDynamicWorkflows([rootDefinition, helperDefinition])

Mastra valide le lot comme une unité et détermine l’ordre d’enregistrement à partir des dépendances. Si la validation échoue, aucune définition n’est enregistrée.

Gérer les définitions via HTTP

Les applications n’ont pas besoin d’accéder directement à l’instance Mastra pour gérer les Workflows dynamiques. Utilisez l’une des interfaces suivantes :

• API des Workflows du SDK client : appelez upsertDynamicWorkflow() depuis un client JavaScript ou TypeScript.
• Routes du serveur : envoyez les définitions à POST /api/stored/workflows.

Sur les serveurs authentifiés, la gestion des Workflows dynamiques nécessite les autorisations stored-workflows:read et stored-workflows:write. L’exécution du Workflow enregistré nécessite workflows:execute.

Conserver les définitions

Les définitions conservées utilisent le domaine de stockage workflowDefinitions. Au démarrage, Mastra charge les définitions actives depuis le stockage et les enregistre dans l’ordre de leurs dépendances.

Sans adaptateur de stockage prenant ce domaine en charge, addDynamicWorkflow() enregistre toujours le Workflow en mémoire, mais sa définition est perdue au redémarrage du processus. Consultez la référence du stockage pour connaître les adaptateurs compatibles.

Pages connexes

• Définition des Workflows dynamiques
• Mastra.addDynamicWorkflow()
• Mastra.addDynamicWorkflows()
• API des Workflows du SDK client
• Routes du serveur