> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt # Client SDK Client SDK 变更与 Server 端 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`，以匹配基于页的 Web 分页。 迁移时，请更新所有 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 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 端点 包括 `/api/memory/network/*` 在内的 Network Memory API 端点已移除。此变更简化了 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。