Client SDK

Client SDK 的變更配合伺服器端 API 更新，包括工具函式重新命名、分頁更新及類型命名慣例。

已變更

messages 現與 @mastra/core/agent 語法相同

messages 引數現為 generate、stream 及 network 方法呼叫的第一個引數，與 @mastra/core/agent 的 NodeJS 版本相似。

如要遷移，請將 messages 移至方法呼叫的第一個引數：

使用 @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([...], {
  });

Codemod

你可以使用 Mastra 的 codemod CLI 自動更新程式碼：

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

threadId 和 resourceId 改用 memory 選項

Agent 方法呼叫已移除 threadId 及 resourceId 選項。請改用 memory 選項，令 Memory 設定 API 更簡潔。這項變更同時適用於 @mastra/client-js 和 @mastra/react 套件。

如要遷移，請將 threadId 和 resourceId 移至 memory 選項：

使用 @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',
+   },
  });

使用 @mastra/react useChat hook

當你提供 threadId 時，useChat hook 會在內部傳遞 Memory 選項。如果你使用 hook 的內置 Memory 處理功能，無需變更元件程式碼。不過，如果你原本手動將選項傳給 sendMessage，請相應更新：

  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
  });

建立新對話串時，memory 選項亦支援傳入對話串中繼資料：

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

Client SDK 類型從 Get* 改為 List*

Client SDK 類型已從 Get* 模式重新命名為 List* 模式。這項變更使類型名稱與方法命名慣例一致。

如要遷移，請更新類型匯入，改用新的命名模式。

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

Codemod

你可以使用 Mastra 的 codemod CLI 自動更新程式碼：

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

分頁參數從 offset/limit 改為 page/perPage

所有原本使用 offset/limit 的 Client SDK 方法現在都改用 page/perPage，以配合按頁面的網頁分頁方式。

如要遷移，請更新所有 Client SDK 方法呼叫中的分頁參數。例如：

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

Codemod

你可以使用 Mastra 的 codemod CLI 自動更新程式碼：

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

getMemoryThread 參數結構

getMemoryThread 方法的參數結構已更新。這項變更讓各個 Memory 方法採用更一致的 API。

如要遷移，請以新的參數結構更新方法呼叫。具體變更請查閱最新 API 文件。

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

Codemod

你可以使用 Mastra 的 codemod CLI 自動更新程式碼：

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

Workflow 執行統一使用 runById API

runById() 方法現在傳回統一的 WorkflowState 物件，當中包含中繼資料（runId、workflowName、resourceId、createdAt、updatedAt）及已處理的執行狀態（status、result、error、payload、steps）。這項變更將以往分開的 runById() 和 runExecutionResult() 方法合併。

此方法亦接受包含選填 fields 及 withNestedWorkflows 參數的 options 物件，方便最佳化效能。

  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 }

已移除

runExecutionResult 方法和 GetWorkflowRunExecutionResultResponse 類型

@mastra/client-js 已移除 runExecutionResult() 方法及 GetWorkflowRunExecutionResultResponse 類型，亦已移除 /execution-result API 端點。

如要遷移，請改用 runById()；它現在會傳回相同的統一 WorkflowState，當中同時包含中繼資料及已處理的執行狀態。

- 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
+ });

toAISdkFormat 函式

@mastra/ai-sdk 已移除 toAISdkFormat() 函式。請改用下方所示的串流轉換工具。

如要遷移，請改用 toAISdkStream()。

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

Codemod

你可以使用 Mastra 的 codemod CLI 自動更新程式碼：

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

Network Memory 方法

@mastra/client-js 已移除 Network Memory 方法。NetworkMemoryThread 類別及所有 Network Memory 相關方法已不再提供。這項變更移除專用的 Network Memory 功能，令 Memory API 更簡潔。

如要遷移，請使用一般 Memory API，而非 Network Memory。

- 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();

Watch 相關類型

@mastra/client-js 已移除 Watch 相關類型，包括 WorkflowWatchResult、WatchEvent 及相關類型。這項變更反映 Watch API 已移除，改用串流。

如要遷移，請使用 Workflow 串流 API，而非 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);
+ }

無法直接在 Workflow 實例上呼叫執行相關方法

無法直接在 Workflow 實例上呼叫執行相關方法。你必須先使用 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: { ... } });

streamVNext、resumeStreamVNext 和 observeStreamVNext 方法

實驗性的 streamVNext()、resumeStreamVNext() 和 observeStreamVNext() 方法已移除。這些方法現已成為標準實作，並更新了事件結構及傳回類型。

如要遷移，請分別改用標準的 stream()、resumeStream() 和 observeStream() 方法。

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

已棄用的串流端點

部分串流端點已棄用並將會移除。/api/agents/:agentId/stream/vnext 端點會傳回 410 Gone，而 /api/agents/:agentId/stream/ui 亦已棄用。這項變更統一採用標準串流端點。

如要遷移，請使用標準串流端點，或使用 @mastra/ai-sdk 轉換 UI 訊息。

- 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

Network Memory API 端點

Network Memory API 端點已移除，包括 /api/memory/network/*。這項變更簡化了 Memory API 介面。

如要遷移，請使用一般 Memory API 端點。

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

Evals 相關 Client SDK 類型

Client SDK 已移除多個 Evals 相關類型，包括 GetEvalsByAgentIdResponse、GetTelemetryResponse 和 GetTelemetryParams。這項變更反映舊版 Evals 功能已移除。

如要遷移，請使用新的 scorer API，而非舊版 Evals。