> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-HK/llms.txt # Client SDK Client SDK 的變更配合伺服器端 API 更新，包括工具函式重新命名、分頁更新及類型命名慣例。 ## 已變更 ### `messages` 現與 `@mastra/core/agent` 語法相同 `messages` 引數現為 `generate`、`stream` 及 `network` 方法呼叫的第一個引數，與 `@mastra/core/agent` 的 NodeJS 版本相似。 如要遷移，請將 `messages` 移至方法呼叫的第一個引數： **使用 `@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([...], { }); ``` > **Codemod:** 你可以使用 Mastra 的 codemod CLI 自動更新程式碼： > > ```bash > 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`：** ```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', + }, }); ``` #### 使用 `@mastra/react` `useChat` hook 當你提供 `threadId` 時，`useChat` hook 會在內部傳遞 Memory 選項。如果你使用 hook 的內置 Memory 處理功能，無需變更元件程式碼。不過，如果你原本手動將選項傳給 `sendMessage`，請相應更新： ```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 }); ``` 建立新對話串時，`memory` 選項亦支援傳入對話串中繼資料： ```typescript 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*` 模式。這項變更使類型名稱與方法命名慣例一致。 如要遷移，請更新類型匯入，改用新的命名模式。 ```diff - import type { - GetWorkflowRunsParams, - GetWorkflowRunsResponse, - GetMemoryThreadParams, - } from '@mastra/client-js'; + import type { + ListWorkflowRunsParams, + ListWorkflowRunsResponse, + ListMemoryThreadsParams, + } from '@mastra/client-js'; ``` > **Codemod:** 你可以使用 Mastra 的 codemod CLI 自動更新程式碼： > > ```bash > npx @mastra/codemod@latest v1/client-sdk-types . > ``` ### 分頁參數從 `offset/limit` 改為 `page/perPage` 所有原本使用 `offset/limit` 的 Client SDK 方法現在都改用 `page/perPage`，以配合按頁面的網頁分頁方式。 如要遷移，請更新所有 Client SDK 方法呼叫中的分頁參數。例如： ```diff client.memory.listMessages({ threadId: 'thread-123', - offset: 0, - limit: 20, + page: 0, + perPage: 20, }); ``` > **Codemod:** 你可以使用 Mastra 的 codemod CLI 自動更新程式碼： > > ```bash > npx @mastra/codemod@latest v1/client-offset-limit . > ``` ### `getMemoryThread` 參數結構 `getMemoryThread` 方法的參數結構已更新。這項變更讓各個 Memory 方法採用更一致的 API。 如要遷移，請以新的參數結構更新方法呼叫。具體變更請查閱最新 API 文件。 ```diff - const thread = await client.getMemoryThread(threadId, agentId); + const thread = await client.getMemoryThread({ threadId, agentId }); ``` > **Codemod:** 你可以使用 Mastra 的 codemod CLI 自動更新程式碼： > > ```bash > 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 物件，方便最佳化效能。 ```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 } ``` ## 已移除 ### `runExecutionResult` 方法和 `GetWorkflowRunExecutionResultResponse` 類型 `@mastra/client-js` 已移除 `runExecutionResult()` 方法及 `GetWorkflowRunExecutionResultResponse` 類型，亦已移除 `/execution-result` API 端點。 如要遷移，請改用 `runById()`；它現在會傳回相同的統一 `WorkflowState`，當中同時包含中繼資料及已處理的執行狀態。 ```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 + }); ``` ### `toAISdkFormat` 函式 `@mastra/ai-sdk` 已移除 `toAISdkFormat()` 函式。請改用下方所示的串流轉換工具。 如要遷移，請改用 `toAISdkStream()`。 ```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' }); ``` > **Codemod:** 你可以使用 Mastra 的 codemod CLI 自動更新程式碼： > > ```bash > 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。 ```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(); ``` ### Watch 相關類型 `@mastra/client-js` 已移除 Watch 相關類型，包括 `WorkflowWatchResult`、`WatchEvent` 及相關類型。這項變更反映 Watch API 已移除，改用串流。 如要遷移，請使用 Workflow 串流 API，而非 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); + } ``` ### 無法直接在 Workflow 實例上呼叫執行相關方法 無法直接在 Workflow 實例上呼叫執行相關方法。你必須先使用 `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: { ... } }); ``` ### `streamVNext`、`resumeStreamVNext` 和 `observeStreamVNext` 方法 實驗性的 `streamVNext()`、`resumeStreamVNext()` 和 `observeStreamVNext()` 方法已移除。這些方法現已成為標準實作，並更新了事件結構及傳回類型。 如要遷移，請分別改用標準的 `stream()`、`resumeStream()` 和 `observeStream()` 方法。 ```diff + 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 訊息。 ```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 ``` ### Network Memory API 端點 Network Memory API 端點已移除，包括 `/api/memory/network/*`。這項變更簡化了 Memory API 介面。 如要遷移，請使用一般 Memory API 端點。 ```diff - 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。