> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-TW/llms.txt # 使用者端 SDK 使用者端 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', }, }); ``` ### 使用者端 SDK 型別從 `Get*` 改為 `List*` 使用者端 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` 的使用者端 SDK 方法現在都改用 `page/perPage`，以符合以頁面為基礎的網頁分頁方式。 遷移時，請更新所有使用者端 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 run 統一使用 `runById` API `runById()` 方法現在會傳回統一的 `WorkflowState` 物件，其中同時包含中繼資料（runId、workflowName、resourceId、createdAt、updatedAt）與處理後的執行狀態（status、result、error、payload、steps）。這會整合先前分開的 `runById()` 與 `runExecutionResult()` 方法。 此方法也接受具有選填 `fields` 與 `withNestedWorkflows` 參數的選項物件，以最佳化效能。 ```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 執行個體上呼叫 run 相關方法 無法直接在 Workflow 執行個體上呼叫 run 相關方法。你必須先使用 `createRun()` 方法建立 run 執行個體。 ```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 相關使用者端 SDK 型別 使用者端 SDK 已移除數個 Evals 相關型別，包括 `GetEvalsByAgentIdResponse`、`GetTelemetryResponse` 與 `GetTelemetryParams`。這項變更反映舊版 Evals 功能已移除。 遷移時，請使用新的 scorer API，而非舊版 Evals。