SDK client Mastra

Le SDK client Mastra fournit une interface concise et typée pour interagir avec votre serveur Mastra depuis votre environnement client.

Prérequis

Avant de commencer le développement local, assurez-vous de disposer des éléments suivants :

• Node.js v22.13.0 ou version ultérieure
• TypeScript v4.7 ou version ultérieure (si vous utilisez TypeScript)
• votre serveur Mastra local en cours d'exécution (généralement sur le port 4111)

remarque

Le SDK client Mastra est conçu pour les environnements de navigateur et utilise l'API native fetch afin d'envoyer des requêtes HTTP à votre serveur Mastra.

Installation

Pour utiliser le SDK client Mastra, installez les dépendances requises :

npm

npm install @mastra/client-js@latest

pnpm

pnpm add @mastra/client-js@latest

Yarn

yarn add @mastra/client-js@latest

Bun

bun add @mastra/client-js@latest

Initialiser MastraClient

Une fois initialisé avec une baseUrl, MastraClient expose une interface typée permettant d'appeler des agents, des outils et des workflows.

lib/mastra-client.ts

import { MastraClient } from '@mastra/client-js'

export const mastraClient = new MastraClient({
  baseUrl: process.env.MASTRA_API_URL || 'http://localhost:4111',
})

Principales API

Le SDK client Mastra expose toutes les ressources fournies par le serveur Mastra.

• Agents : générez des réponses et diffusez des conversations en streaming.
• A2A : découvrez des agents grâce aux cartes d'agent et utilisez des flux A2A basés sur des tâches.
• Mémoire : gérez les threads de conversation et l'historique des messages.
• Outils : exécutez et gérez des outils.
• Workflows : déclenchez des workflows et suivez leur exécution.
• Vecteurs : utilisez des embeddings vectoriels pour la recherche sémantique.
• Réponses : utilisez les agents Mastra comme une API Responses dotée d'une interface compatible avec OpenAI et reposant sur des agents. Cette API est actuellement expérimentale.
• Conversations : utilisez les threads de conversation stockés et l'historique des éléments qui permettent aux agents Mastra de servir d'API Responses. Cette API est actuellement expérimentale.
• Journaux : consultez les journaux et déboguez le comportement du système.
• Télémétrie : consultez les performances de l'application et l'activité des traces.

Créer et exécuter des workflows dynamiques

Utilisez upsertDynamicWorkflow() pour créer ou remplacer une définition de workflow persistée. Une opération d'upsert réussie valide la définition complète, l'enregistre auprès de l'instance Mastra en cours d'exécution et la rend disponible via l'API standard d'exécution des workflows.

L'exemple suivant présente le cycle de vie complet d'un workflow de mappage, de sa création et de son inspection à son exécution et à sa suppression :

lib/dynamic-workflow.ts

import { MastraClient } from '@mastra/client-js'
import type { UpsertDynamicWorkflowParams } from '@mastra/client-js'

const client = new MastraClient({
  baseUrl: process.env.MASTRA_API_URL || 'http://localhost:4111',
})

const definition = {
  id: 'greeting-workflow',
  description: 'Returns 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: 'mapping',
      id: 'create-greeting',
      mapConfig: JSON.stringify({
        message: { template: 'Hello, ${initData.name}!' },
      }),
    },
  ],
} satisfies UpsertDynamicWorkflowParams

await client.upsertDynamicWorkflow(definition)

const dynamicWorkflow = client.getDynamicWorkflow(definition.id)
const dynamicDefinition = await dynamicWorkflow.details()

const workflow = client.getWorkflow(dynamicDefinition.id)
const run = await workflow.createRun()
const result = await run.startAsync({ inputData: { name: 'Ada' } })

console.log(result)

await dynamicWorkflow.delete()

Utilisez listDynamicWorkflows() pour répertorier les définitions persistées. Appeler de nouveau upsertDynamicWorkflow() avec le même id remplace la définition stockée et l'enregistrement actif du workflow.

attention

Le stockage durable nécessite un adaptateur de stockage configuré qui prend en charge le domaine workflowDefinitions. Sans ce domaine, Core peut enregistrer un workflow en mémoire, mais l'API des workflows dynamiques du serveur ne peut pas le conserver après un redémarrage.

Les définitions stockées prennent en charge les entrées déclaratives d'agent, d'outil, de mappage, de workflow imbriqué, d'exécution parallèle, d'itération, de pause, de pause jusqu'à une date, de condition et de boucle. Elles ne peuvent pas contenir de closures JavaScript. La logique des conditions et des boucles doit utiliser le format de prédicat déclaratif, et les agents, outils et workflows imbriqués référencés doivent déjà être enregistrés.

Les serveurs authentifiés exigent stored-workflows:read ou stored-workflows:write pour les opérations sur les définitions, ainsi que workflows:execute pour exécuter le workflow.

Générer des réponses

Appelez .generate() avec un prompt sous forme de chaîne :

import { mastraClient } from 'lib/mastra-client'

const testAgent = async () => {
  try {
    const agent = mastraClient.getAgent('testAgent')

    const response = await agent.generate('Hello')

    console.log(response.text)
  } catch (error) {
    return 'Error occurred while generating response'
  }
}

info

Vous pouvez également appeler .generate() avec un tableau d'objets de message comprenant role et content. Consultez la référence de .generate() pour plus d'informations.

Diffuser des réponses en streaming

Utilisez .stream() pour obtenir des réponses en temps réel à partir d'un prompt sous forme de chaîne :

import { mastraClient } from 'lib/mastra-client'

const testAgent = async () => {
  try {
    const agent = mastraClient.getAgent('testAgent')

    const stream = await agent.stream('Hello')

    stream.processDataStream({
      onTextPart: text => {
        console.log(text)
      },
    })
  } catch (error) {
    return 'Error occurred while generating response'
  }
}

info

Vous pouvez également appeler .stream() avec un tableau d'objets de message comprenant role et content. Consultez la référence de .stream() pour plus d'informations.

Options de configuration

MastraClient accepte des paramètres facultatifs tels que retries, backoffMs et headers pour contrôler le comportement des requêtes. Ces paramètres permettent de configurer les nouvelles tentatives et d'inclure des métadonnées de diagnostic.

lib/mastra-client.ts

import { MastraClient } from '@mastra/client-js'

export const mastraClient = new MastraClient({
  retries: 3,
  backoffMs: 300,
  maxBackoffMs: 5000,
  headers: {
    'X-Development': 'true',
  },
})

Consultez la référence de MastraClient pour découvrir d'autres options de configuration.

Identifiants et cookies de session

Authentifiez les appels à l'API Mastra avec des cookies de session lorsque votre interface utilisateur et l'API Mastra n'ont pas la même origine, c'est-à-dire qu'elles utilisent un hôte, un sous-domaine ou un port différent (par exemple, Mastra Studio sur un port et un serveur personnalisé sur un autre). Ajoutez credentials: 'include' à MastraClient afin que chaque requête transmette les cookies dont l'utilisateur dispose déjà après sa connexion. Si vous omettez cette option, vous recevrez souvent des réponses 401 de Mastra, même si la connexion a réussi dans le navigateur.

lib/mastra-client.ts

import { MastraClient } from '@mastra/client-js'

export const mastraClient = new MastraClient({
  baseUrl: process.env.MASTRA_API_URL || 'http://localhost:4111',
  credentials: 'include',
})

Autorisez les requêtes inter-origines avec identifiants sur votre serveur ; consultez CORS : requêtes avec identifiants. Vous devez définir une valeur concrète pour Access-Control-Allow-Origin (et non *) ainsi que Access-Control-Allow-Credentials: true, sans quoi le navigateur bloquera l'appel avant qu'il n'atteigne Mastra.

Vous utilisez @mastra/react ? Enveloppez votre application avec MastraReactProvider, définissez baseUrl et apiPrefix pour qu'ils correspondent à votre serveur et utilisez la valeur par défaut credentials: 'include'. Ne modifiez credentials que si vous souhaitez le comportement same-origin ou omit.

Ajouter l'annulation des requêtes

MastraClient prend en charge l'annulation des requêtes grâce à l'API standard Node.js AbortSignal. Cette fonctionnalité est utile pour annuler des requêtes en cours, par exemple lorsqu'un utilisateur interrompt une opération, ou pour nettoyer des appels réseau obsolètes.

Transmettez un AbortSignal au constructeur du client pour activer l'annulation de toutes les requêtes.

lib/mastra-client.ts

import { MastraClient } from '@mastra/client-js'

export const controller = new AbortController()

export const mastraClient = new MastraClient({
  baseUrl: process.env.MASTRA_API_URL || 'http://localhost:4111',
  abortSignal: controller.signal,
})

Utiliser AbortController

L'appel de .abort() annule toutes les requêtes en cours associées à ce signal.

import { mastraClient, controller } from 'lib/mastra-client'

const handleAbort = () => {
  controller.abort()
}

Outils côté client

Définissez des outils directement dans les applications côté client à l'aide de la fonction createTool(). Transmettez-les aux agents via le paramètre clientTools dans les appels à .generate() ou .stream().

Cela permet aux agents de déclencher des fonctionnalités côté navigateur, comme la manipulation du DOM, l'accès au stockage local ou à d'autres API Web. Les outils peuvent ainsi s'exécuter dans l'environnement de l'utilisateur plutôt que sur le serveur.

import { createTool } from '@mastra/client-js'
import { z } from 'zod'

const handleClientTool = async () => {
  try {
    const agent = mastraClient.getAgent('colorAgent')

    const colorChangeTool = createTool({
      id: 'color-change-tool',
      description: 'Changes the HTML background color',
      inputSchema: z.object({
        color: z.string(),
      }),
      outputSchema: z.object({
        success: z.boolean(),
      }),
      execute: async inputData => {
        const { color } = inputData

        document.body.style.backgroundColor = color
        return { success: true }
      },
    })

    const response = await agent.generate('Change the background to blue', {
      clientTools: { colorChangeTool },
    })

    console.log(response)
  } catch (error) {
    console.error(error)
  }
}

Agent utilisant l'outil côté client

Il s'agit d'un agent Mastra standard configuré pour renvoyer des codes de couleur hexadécimaux et conçu pour fonctionner avec l'outil côté client dans le navigateur défini ci-dessus.

src/mastra/agents/color-agent

import { Agent } from '@mastra/core/agent'

export const colorAgent = new Agent({
  id: 'color-agent',
  name: 'Color Agent',
  instructions: `You are a helpful CSS assistant.
  You can change the background color of web pages.
  Respond with a hex reference for the color requested by the user`,
  model: 'openai/gpt-5.6-sol',
})

Utiliser MastraClient sur le serveur

Vous pouvez également utiliser MastraClient dans des environnements côté serveur tels que des routes d'API, des fonctions serverless ou des actions. Son utilisation reste identique, mais vous devrez peut-être recréer la réponse destinée à votre client :

export async function action() {
  const agent = mastraClient.getAgent('testAgent')

  const stream = await agent.stream('Hello')

  return new Response(stream.body)
}

Bonnes pratiques

1. Gestion des erreurs : utilisez la gestion des erreurs dans vos scénarios de développement.
2. Variables d'environnement : utilisez des variables d'environnement pour la configuration.
3. Débogage : activez une journalisation détaillée lorsque cela est nécessaire.
4. Performances : suivez les performances de l'application, la télémétrie et les traces.