Agents et Tools

Les étapes d’un Workflow peuvent appeler des Agents afin d’exploiter le raisonnement d’un LLM, ou appeler des Tools pour appliquer une logique avec typage sûr. Vous pouvez les invoquer depuis la fonction execute() d’une étape ou les composer directement sous forme d’étapes au moyen de createStep().

Utiliser des Agents dans les Workflows

Utilisez des Agents dans les étapes d’un Workflow lorsque vous avez besoin de raisonnement, de génération de langage ou d’autres tâches fondées sur un LLM. Appelez-les depuis la fonction execute() d’une étape pour mieux contrôler l’appel de l’Agent, par exemple afin de suivre l’historique des messages ou de renvoyer une sortie structurée. Composez les Agents sous forme d’étapes lorsque vous n’avez pas besoin de modifier leur mode d’invocation.

Appeler des Agents

Appelez les Agents dans la fonction execute() d’une étape à l’aide de .generate() ou .stream(). Vous pouvez ainsi modifier l’appel de l’Agent et traiter sa réponse avant de la transmettre à l’étape suivante.

src/mastra/workflows/test-workflow.ts

const step1 = createStep({
  execute: async ({ inputData, mastra }) => {
    const { message } = inputData

    const testAgent = mastra.getAgent('testAgent')
    const response = await testAgent.generate(
      `Convert this message into bullet points: ${message}`,
      {
        memory: {
          thread: 'user-123',
          resource: 'test-123',
        },
      },
    )

    return {
      list: response.text,
    }
  },
})

Utiliser des Agents comme étapes

Composez un Agent sous forme d’étape au moyen de createStep() lorsque vous n’avez pas besoin de modifier son appel. Utilisez .map() pour transformer la sortie de l’étape précédente en un prompt que l’Agent peut utiliser.

src/mastra/workflows/test-workflow.ts

import { testAgent } from '../agents/test-agent'
const step1 = createStep(testAgent)

export const testWorkflow = createWorkflow({})
  .map(async ({ inputData }) => {
    const { message } = inputData
    return {
      prompt: `Convert this message into bullet points: ${message}`,
    }
  })
  .then(step1)
  .then(step2)
  .commit()

Consultez la section Mappage des données d’entrée pour en savoir plus.

Lorsqu’aucune option structuredOutput n’est fournie, les Agents Mastra utilisent un schéma par défaut qui attend une chaîne prompt en entrée et renvoie une chaîne text en sortie :

{
  inputSchema: {
    prompt: string
  },
  outputSchema: {
    text: string
  }
}

Agents avec sortie structurée

Lorsque l’Agent doit renvoyer des données structurées plutôt que du texte brut, transmettez l’option structuredOutput à createStep(). Le schéma de sortie de l’étape correspondra au schéma fourni, ce qui permettra un enchaînement avec typage sûr vers les étapes suivantes.

src/mastra/workflows/test-workflow.ts

const articleSchema = z.object({
  title: z.string(),
  summary: z.string(),
  tags: z.array(z.string()),
})

const agentStep = createStep(testAgent, {
  structuredOutput: { schema: articleSchema },
})

// Next step receives typed structured data
const processStep = createStep({
  id: 'process',
  inputSchema: articleSchema, // Matches agent's outputSchema
  outputSchema: z.object({ tagCount: z.number() }),
  execute: async ({ inputData }) => ({
    tagCount: inputData.tags.length, // Fully typed
  }),
})

export const testWorkflow = createWorkflow({})
  .map(async ({ inputData }) => ({
    prompt: `Generate an article about: ${inputData.topic}`,
  }))
  .then(agentStep)
  .then(processStep)
  .commit()

L’option structuredOutput.schema accepte tout schéma JSON standard. L’Agent génère une sortie conforme à ce schéma et l’outputSchema de l’étape est automatiquement configuré pour lui correspondre. Consultez la section Sortie structurée pour découvrir d’autres options, comme les stratégies de gestion des erreurs et le streaming avec sortie structurée.

Le raccourci .agent()

Ajoutez directement un Agent avec .agent() au lieu de l’encapsuler dans createStep(). Cette méthode accepte les mêmes options que createStep(agent, options), ainsi qu’une chaîne d’identifiant d’Agent à la place de l’instance :

src/mastra/workflows/test-workflow.ts

import { testAgent } from '../agents/test-agent'

export const testWorkflow = createWorkflow({})
  .map(async ({ inputData }) => ({
    prompt: `Generate an article about: ${inputData.topic}`,
  }))
  .agent(testAgent, { structuredOutput: { schema: articleSchema } })
  .commit()

.agent() enregistre une entrée déclarative dans le graphe du Workflow plutôt qu’une étape opaque. Les Workflows ainsi construits peuvent donc être conservés sous forme de Workflows dynamiques. Consultez Workflow.agent() pour connaître tous les paramètres.

Utiliser des Tools dans les Workflows

Utilisez des Tools dans les étapes d’un Workflow afin de réemployer une logique de Tool existante. Appelez-les depuis la fonction .execute() d’une étape lorsque vous devez préparer le contexte ou traiter les réponses. Composez les Tools sous forme d’étapes lorsque vous n’avez pas besoin de modifier leur mode d’utilisation.

Appeler des Tools

Appelez les Tools dans la fonction .execute() d’une étape. Vous pouvez ainsi mieux contrôler le contexte d’entrée du Tool ou traiter sa réponse avant de la transmettre à l’étape suivante.

src/mastra/workflows/test-workflow.ts

import { testTool } from '../tools/test-tool'

const step2 = createStep({
  execute: async ({ inputData, requestContext }) => {
    const { text } = inputData

    const response = await testTool.execute({ text }, { requestContext })

    return {
      emphasized: response.emphasized,
    }
  },
})

Utiliser des Tools comme étapes

Composez un Tool sous forme d’étape au moyen de createStep() lorsque la sortie de l’étape précédente correspond au contexte d’entrée du Tool. Dans le cas contraire, vous pouvez utiliser .map() pour transformer la sortie de l’étape précédente.

src/mastra/workflows/test-workflow.ts

import { testTool } from '../tools/test-tool'

const step2 = createStep(testTool)

export const testWorkflow = createWorkflow({})
  .then(step1)
  .map(async ({ inputData }) => {
    const { formatted } = inputData
    return {
      text: formatted,
    }
  })
  .then(step2)
  .commit()

Consultez la section Mappage des données d’entrée pour en savoir plus.

Le raccourci .tool()

Ajoutez directement un Tool avec .tool() au lieu de l’encapsuler dans createStep(). Cette méthode accepte une instance de Tool ou la chaîne d’identifiant d’un Tool enregistré, ainsi que les options retries et metadata propres à l’étape :

src/mastra/workflows/test-workflow.ts

import { testTool } from '../tools/test-tool'

export const testWorkflow = createWorkflow({}).then(step1).tool(testTool).commit()

Comme .agent(), .tool() enregistre une entrée déclarative ; le Workflow peut donc être conservé sous forme de Workflow dynamique. Consultez Workflow.tool() pour connaître tous les paramètres.

Voir aussi

• Utiliser des Agents
• Présentation de MCP