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

# SDK client Mastra

Le SDK client Mastra fournit une interface concise et typée pour interagir avec votre [serveur Mastra](https://mastra.zisheng.pro/fr/docs/server/mastra-server) 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**:

```bash
npm install @mastra/client-js@latest
```

**pnpm**:

```bash
pnpm add @mastra/client-js@latest
```

**Yarn**:

```bash
yarn add @mastra/client-js@latest
```

**Bun**:

```bash
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.

```typescript
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](https://mastra.zisheng.pro/fr/reference/client-js/agents)** : générez des réponses et diffusez des conversations en streaming.
- **[A2A](https://mastra.zisheng.pro/fr/docs/agents/a2a)** : découvrez des agents grâce aux cartes d'agent et utilisez des flux A2A basés sur des tâches.
- **[Mémoire](https://mastra.zisheng.pro/fr/reference/client-js/memory)** : gérez les threads de conversation et l'historique des messages.
- **[Outils](https://mastra.zisheng.pro/fr/reference/client-js/tools)** : exécutez et gérez des outils.
- **[Workflows](https://mastra.zisheng.pro/fr/reference/client-js/workflows)** : déclenchez des workflows et suivez leur exécution.
- **[Vecteurs](https://mastra.zisheng.pro/fr/reference/client-js/vectors)** : utilisez des embeddings vectoriels pour la recherche sémantique.
- **[Réponses](https://mastra.zisheng.pro/fr/reference/client-js/responses)** : 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](https://mastra.zisheng.pro/fr/reference/client-js/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](https://mastra.zisheng.pro/fr/reference/client-js/logs)** : consultez les journaux et déboguez le comportement du système.
- **[Télémétrie](https://mastra.zisheng.pro/fr/reference/client-js/telemetry)** : 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 :

```typescript
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 :

```typescript
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()](https://mastra.zisheng.pro/fr/reference/client-js/agents) 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 :

```typescript
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()](https://mastra.zisheng.pro/fr/reference/client-js/agents) 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.

```typescript
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](https://mastra.zisheng.pro/fr/reference/client-js/mastra-client) 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.

```typescript
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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS#requests_with_credentials). 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.

```typescript
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.

```typescript
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.

```typescript
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](https://mastra.zisheng.pro/fr/docs/agents/overview) 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.

```typescript
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 :

```typescript
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](https://mastra.zisheng.pro/fr/reference/client-js/error-handling) 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](https://mastra.zisheng.pro/fr/reference/client-js/logs) détaillée lorsque cela est nécessaire.
4. **Performances** : suivez les performances de l'application, la [télémétrie](https://mastra.zisheng.pro/fr/reference/client-js/telemetry) et les traces.