SDK client

Les changements apportés au SDK client s'alignent sur les mises à jour de l'API côté serveur, notamment le renommage des utilitaires, la mise à jour de la pagination et les conventions de nommage des types.

Modifications

La syntaxe de messages est désormais identique à celle de @mastra/core/agent

L'argument messages est désormais le premier argument des appels aux méthodes generate, stream et network, comme dans la version NodeJS de @mastra/core/agent.

Pour effectuer la migration, placez messages en premier argument de l'appel de méthode :

Avec @mastra/client-js :

  const agent = client.getAgent('my-agent');

-  await agent.generate({
-    messages: [...]
+  await agent.generate([...], {
  });

-  await agent.stream({
-    messages: [...]
+  await agent.stream([...], {
  });

-  await agent.network({
-    messages: [...]
+  await agent.network([...], {
  });

Migration automatisée

Vous pouvez utiliser la CLI codemod de Mastra pour mettre à jour votre code automatiquement :

npx @mastra/codemod@latest v1/client-msg-function-args .

Remplacement de threadId et resourceId par l'option memory

Les options threadId et resourceId ont été supprimées des appels aux méthodes des agents. Utilisez plutôt l'option memory, qui offre une API plus claire pour configurer la mémoire. Ce changement concerne les packages @mastra/client-js et @mastra/react.

Pour effectuer la migration, déplacez threadId et resourceId dans l'option memory :

Avec @mastra/client-js :

  const agent = client.getAgent('my-agent');

  await agent.generate([...], {
-   threadId: 'thread-123',
-   resourceId: 'user-456',
+   memory: {
+     thread: 'thread-123',
+     resource: 'user-456',
+   },
  });

+  await agent.stream([...], {
-   threadId: 'thread-123',
-   resourceId: 'user-456',
+   memory: {
+     thread: 'thread-123',
+     resource: 'user-456',
+   },
  });

Avec @mastra/react et le hook useChat

Le hook useChat transmet l'option de mémoire en interne lorsque vous fournissez un threadId. Si vous utilisez la gestion de la mémoire intégrée au hook, aucune modification du code de votre composant n'est nécessaire. En revanche, si vous transmettiez manuellement des options à sendMessage, mettez-les à jour en conséquence :

  const { sendMessage } = useChat({ agentId: 'my-agent' });

  await sendMessage({
    message: 'Hello',
    mode: 'stream',
-   threadId: 'thread-123',
+   threadId: 'thread-123', // Still works - internally converted to memory option
  });

L'option memory permet également de transmettre les métadonnées du thread lors de la création de nouveaux threads :

await agent.generate([...], {
  memory: {
    thread: {
      id: 'thread-123',
      title: 'Support conversation',
      metadata: { category: 'billing' },
    },
    resource: 'user-456',
  },
});

Types du SDK client renommés de Get* en List*

Les types du SDK client ont été renommés du modèle Get* vers le modèle List*. Ce changement aligne leurs noms sur la convention de nommage des méthodes.

Pour effectuer la migration, modifiez les imports de types afin d'utiliser le nouveau modèle de nommage.

- import type {
-   GetWorkflowRunsParams,
-   GetWorkflowRunsResponse,
-   GetMemoryThreadParams,
- } from '@mastra/client-js';
+ import type {
+   ListWorkflowRunsParams,
+   ListWorkflowRunsResponse,
+   ListMemoryThreadsParams,
+ } from '@mastra/client-js';

Migration automatisée

Vous pouvez utiliser la CLI codemod de Mastra pour mettre à jour votre code automatiquement :

npx @mastra/codemod@latest v1/client-sdk-types .

Paramètres de pagination renommés de offset/limit en page/perPage

Toutes les méthodes du SDK client qui utilisaient offset/limit utilisent désormais page/perPage, conformément à la pagination web par pages.

Pour effectuer la migration, mettez à jour les paramètres de pagination dans tous les appels aux méthodes du SDK client. Exemple :

  client.memory.listMessages({
    threadId: 'thread-123',
-   offset: 0,
-   limit: 20,
+   page: 0,
+   perPage: 20,
  });

Migration automatisée

Vous pouvez utiliser la CLI codemod de Mastra pour mettre à jour votre code automatiquement :

npx @mastra/codemod@latest v1/client-offset-limit .

Structure des paramètres de getMemoryThread

La structure des paramètres de la méthode getMemoryThread a été mise à jour. Ce changement rend l'API plus cohérente entre les différentes méthodes de mémoire.

Pour effectuer la migration, adaptez l'appel de méthode à la nouvelle structure des paramètres. Consultez la documentation mise à jour de l'API pour connaître les changements précis.

- const thread = await client.getMemoryThread(threadId, agentId);
+ const thread = await client.getMemoryThread({ threadId, agentId });

Migration automatisée

Vous pouvez utiliser la CLI codemod de Mastra pour mettre à jour votre code automatiquement :

npx @mastra/codemod@latest v1/client-get-memory-thread .

API runById unifiée pour les exécutions de Workflow

La méthode runById() renvoie désormais un objet WorkflowState unifié qui contient à la fois les métadonnées (runId, workflowName, resourceId, createdAt, updatedAt) et l'état d'exécution traité (status, result, error, payload, steps). Elle regroupe ainsi les méthodes runById() et runExecutionResult(), auparavant distinctes.

La méthode accepte également un objet d'options avec les paramètres facultatifs fields et withNestedWorkflows afin d'optimiser les performances.

  const workflow = client.getWorkflow('my-workflow');

- // Previously: runById returned raw WorkflowRun with snapshot
- const run = await workflow.runById(runId, requestContext);
- // Separately: runExecutionResult returned processed execution state
- const result = await workflow.runExecutionResult(runId);

+ // Now: Single method returns unified WorkflowState
+ const run = await workflow.runById(runId, {
+   requestContext,  // Optional request context
+   fields: ['status', 'result'],  // Optional: request only specific fields
+   withNestedWorkflows: false,  // Optional: skip nested workflow data for performance
+ });
+ // Returns: { runId, workflowName, resourceId, createdAt, updatedAt, status, result, error, payload, steps }

Suppressions

Méthode runExecutionResult et type GetWorkflowRunExecutionResultResponse

La méthode runExecutionResult() et le type GetWorkflowRunExecutionResultResponse ont été supprimés de @mastra/client-js. Les endpoints d'API /execution-result ont également été supprimés.

Pour effectuer la migration, utilisez plutôt runById(), qui renvoie désormais le même WorkflowState unifié comprenant les métadonnées et l'état d'exécution traité.

- import type { GetWorkflowRunExecutionResultResponse } from '@mastra/client-js';
-
- const workflow = client.getWorkflow('my-workflow');
- const result = await workflow.runExecutionResult(runId);

+ const workflow = client.getWorkflow('my-workflow');
+ const result = await workflow.runById(runId);
+ // Or with options for performance optimization:
+ const result = await workflow.runById(runId, {
+   fields: ['status', 'result'],  // Only fetch specific fields
+   withNestedWorkflows: false,     // Skip expensive nested workflow data
+ });

Fonction toAISdkFormat

La fonction toAISdkFormat() a été supprimée de @mastra/ai-sdk. Utilisez plutôt les utilitaires de conversion de flux présentés ci-dessous.

Pour effectuer la migration, utilisez toAISdkStream() à la place.

- import { toAISdkFormat } from '@mastra/ai-sdk';
- const stream = toAISdkFormat(agentStream, { from: 'agent' });
+ import { toAISdkStream } from '@mastra/ai-sdk';
+ const stream = toAISdkStream(agentStream, { from: 'agent' });

Migration automatisée

Vous pouvez utiliser la CLI codemod de Mastra pour mettre à jour votre code automatiquement :

npx @mastra/codemod@latest v1/client-to-ai-sdk-format .

Méthodes de mémoire réseau

Les méthodes de mémoire réseau ont été supprimées de @mastra/client-js. La classe NetworkMemoryThread et toutes les méthodes liées à la mémoire réseau ne sont plus disponibles. Ce changement simplifie l'API de mémoire en supprimant les fonctionnalités spécialisées de mémoire réseau.

Pour effectuer la migration, utilisez les API de mémoire standard à la place de la mémoire réseau.

- import { MastraClient } from '@mastra/client-js';
- 
- const client = new MastraClient({ baseUrl: '...' });
- const networkThread = client.networkMemory.getThread('thread-id');
- const networkThread = client.memory.networkThread('thread-id', 'network-id');
- await networkThread.get();
- await networkThread.getMessages();

+ // Use regular memory thread APIs instead
+ const client = new MastraClient({ baseUrl: '...' });
+ const thread = client.memory.getThread('thread-id');
+ await thread.get();
+ const messages = await thread.listMessages();

Types liés à Watch

Les types liés à Watch ont été supprimés de @mastra/client-js, notamment WorkflowWatchResult, WatchEvent et les types associés. Ce changement reflète la suppression de l'API Watch au profit du streaming.

Pour effectuer la migration, utilisez les API de streaming des Workflows à la place de Watch.

- import type { WorkflowWatchResult, WatchEvent } from '@mastra/client-js';
- 
- const workflow = client.getWorkflow('my-workflow');
- const run = await workflow.createRun();
- await run.watch((event: WatchEvent) => {
-   console.log('Event:', event);
- });

+ const workflow = client.getWorkflow('my-workflow');
+ const run = await workflow.createRun();
+ const stream = await run.stream({ inputData: { ... } });
+ for await (const chunk of stream) {
+   console.log('Event:', chunk);
+ }

Les méthodes liées à l'exécution ne peuvent pas être appelées directement sur une instance de Workflow

Les méthodes liées à l'exécution ne peuvent pas être appelées directement sur une instance de Workflow. Vous devez d'abord créer une instance d'exécution à l'aide de la méthode createRun().

- const result = await workflow.start({ runId: '123', inputData: { ... } });
+ const run = await workflow.createRun({ runId: '123' });
+ const result = await run.start({ inputData: { ... } });

- const result = await workflow.stream({ runId: '123', inputData: { ... } });
+ const run = await workflow.createRun({ runId: '123' });
+ const stream = await run.stream({ inputData: { ... } });

Méthodes streamVNext, resumeStreamVNext et observeStreamVNext

Les méthodes expérimentales streamVNext(), resumeStreamVNext() et observeStreamVNext() ont été supprimées. Elles constituent désormais l'implémentation standard, avec des structures d'événements et des types de retour mis à jour.

Pour effectuer la migration, utilisez à la place les méthodes standard stream(), resumeStream() et observeStream().

+ const run = await workflow.createRun({ runId: '123' });
- const stream = await run.streamVNext({ inputData: { ... } });
+ const stream = await run.stream({ inputData: { ... } });

Endpoints de streaming obsolètes

Certains endpoints de streaming sont obsolètes et seront supprimés. L'endpoint /api/agents/:agentId/stream/vnext renvoie une erreur 410 Gone, tandis que /api/agents/:agentId/stream/ui est obsolète. Ce changement recentre l'API sur les endpoints de streaming standard.

Pour effectuer la migration, utilisez l'endpoint de streaming standard ou @mastra/ai-sdk pour transformer les messages d'interface utilisateur.

- const response = await fetch('/api/agents/my-agent/stream/vnext', {
-   method: 'POST',
-   body: JSON.stringify({ messages: [...] }),
- });

+ const response = await fetch('/api/agents/my-agent/stream', {
+   method: 'POST',
+   body: JSON.stringify({ messages: [...] }),
+ });
+ 
+ // Or use @mastra/ai-sdk for UI message transformations

Endpoints de l'API de mémoire réseau

Les endpoints de l'API de mémoire réseau, notamment /api/memory/network/*, ont été supprimés. Ce changement simplifie la surface de l'API de mémoire.

Pour effectuer la migration, utilisez les endpoints standard de l'API de mémoire.

- const networkThread = await fetch('/api/memory/network/threads/thread-123');
+ const thread = await fetch('/api/memory/threads/thread-123');

Types du SDK client liés aux Evals

Plusieurs types liés aux Evals ont été supprimés du SDK client, notamment GetEvalsByAgentIdResponse, GetTelemetryResponse et GetTelemetryParams. Ce changement reflète la suppression des anciennes fonctionnalités d'Evals.

Pour effectuer la migration, utilisez la nouvelle API de scorers à la place des anciennes Evals.