> Discover all available pages from the documentation index: https://mastra.zisheng.pro/fr/llms.txt # 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` :** ```diff 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 : > > ```bash > 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` :** ```diff 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 : ```diff 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 : ```typescript 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. ```diff - 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 : > > ```bash > 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 : ```diff 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 : > > ```bash > 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. ```diff - 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 : > > ```bash > 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. ```diff 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é. ```diff - 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. ```diff - 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 : > > ```bash > 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. ```diff - 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. ```diff - 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()`. ```diff - const result = await workflow.start({ runId: '123', inputData: { ... } }); + const run = await workflow.createRun({ runId: '123' }); + const result = await run.start({ inputData: { ... } }); ``` ```diff - 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()`. ```diff + 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. ```diff - 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. ```diff - 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.