使用者端 SDK
使用者端 SDK 變更與伺服器端 API 更新一致，包括重新命名公用程式、更新分頁方式與型別命名慣例。
已變更「已變更」的直接連結
messages 現在與 @mastra/core/agent 語法相同「messages-is-now-identical-to-mastracoreagent-syntax」的直接連結
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([...], {
});
你可以使用 Mastra 的 codemod CLI 自動更新程式碼：
npx @mastra/codemod@latest v1/client-msg-function-args .
threadId 與 resourceId 改為 memory 選項「threadid-and-resourceid-to-memory-option」的直接連結
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「using-mastrareact-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',
},
});
使用者端 SDK 型別從 Get* 改為 List*「client-sdk-types-from-get-to-list」的直接連結
使用者端 SDK 型別已從 Get* 重新命名為 List* 模式。這項變更讓型別名稱與方法命名慣例一致。
遷移時，請更新型別匯入，改用新的命名模式。
- import type {
- GetWorkflowRunsParams,
- GetWorkflowRunsResponse,
- GetMemoryThreadParams,
- } from '@mastra/client-js';
+ import type {
+ ListWorkflowRunsParams,
+ ListWorkflowRunsResponse,
+ ListMemoryThreadsParams,
+ } from '@mastra/client-js';
你可以使用 Mastra 的 codemod CLI 自動更新程式碼：
npx @mastra/codemod@latest v1/client-sdk-types .
分頁參數從 offset/limit 改為 page/perPage「pagination-parameters-from-offsetlimit-to-pageperpage」的直接連結
所有原本使用 offset/limit 的使用者端 SDK 方法現在都改用 page/perPage，以符合以頁面為基礎的網頁分頁方式。
遷移時，請更新所有使用者端 SDK 方法呼叫中的分頁參數。例如：
client.memory.listMessages({
threadId: 'thread-123',
- offset: 0,
- limit: 20,
+ page: 0,
+ perPage: 20,
});
你可以使用 Mastra 的 codemod CLI 自動更新程式碼：
npx @mastra/codemod@latest v1/client-offset-limit .
getMemoryThread 參數結構「getmemorythread-parameter-structure」的直接連結
getMemoryThread 方法的參數結構已更新。這項變更讓各個 Memory 方法的 API 更一致。
遷移時，請使用新的參數結構更新方法呼叫。請查看更新後的 API 文件，瞭解具體變更。
- const thread = await client.getMemoryThread(threadId, agentId);
+ const thread = await client.getMemoryThread({ threadId, agentId });
你可以使用 Mastra 的 codemod CLI 自動更新程式碼：
npx @mastra/codemod@latest v1/client-get-memory-thread .
Workflow run 統一使用 runById API「unified-runbyid-api-for-workflow-runs」的直接連結
runById() 方法現在會傳回統一的 WorkflowState 物件，其中同時包含中繼資料（runId、workflowName、resourceId、createdAt、updatedAt）與處理後的執行狀態（status、result、error、payload、steps）。這會整合先前分開的 runById() 與 runExecutionResult() 方法。
此方法也接受具有選填 fields 與 withNestedWorkflows 參數的選項物件，以最佳化效能。
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 型別「runexecutionresult-method-and-getworkflowrunexecutionresultresponse-type」的直接連結
@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 函式「toaisdkformat-function」的直接連結
@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' });
你可以使用 Mastra 的 codemod CLI 自動更新程式碼：
npx @mastra/codemod@latest v1/client-to-ai-sdk-format .
Network Memory 方法「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 相關型別「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 執行個體上呼叫 run 相關方法「無法直接在 Workflow 執行個體上呼叫 run 相關方法」的直接連結
無法直接在 Workflow 執行個體上呼叫 run 相關方法。你必須先使用 createRun() 方法建立 run 執行個體。
- 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-and-observestreamvnext-methods」的直接連結
實驗性的 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 端點」的直接連結
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 相關使用者端 SDK 型別「Evals 相關使用者端 SDK 型別」的直接連結
使用者端 SDK 已移除數個 Evals 相關型別，包括 GetEvalsByAgentIdResponse、GetTelemetryResponse 與 GetTelemetryParams。這項變更反映舊版 Evals 功能已移除。
遷移時，請使用新的 scorer API，而非舊版 Evals。