客户端 SDK

🌐 Client SDK

客户端 SDK 的更改与服务器端 API 更新保持一致，包括重命名的工具、更新的分页以及类型命名规范。

🌐 Client SDK changes align with server-side API updates including renamed utilities, updated pagination, and type naming conventions.

已更改

🌐 Changed

messages 现在与 @mastra/core/agent 语法相同

🌐 messages is now identical to @mastra/core/agent syntax

messages 参数现在是 generate、stream 和 network 方法调用的第一个参数，类似于 @mastra/core/agent 中的 NodeJS 版本。

🌐 The messages argument is now the first argument of the generate, stream and network method calls, similar to the NodeJS version in @mastra/core/agent.

要迁移，请将 messages 移动到方法调用的第一个参数位置：

🌐 To migrate, move messages to the first argument of the method call:

使用 @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 来自动更新你的代码：

🌐 You can use Mastra's codemod CLI to update your code automatically:

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

threadId 和 resourceId 到 memory 选项

🌐 threadId and resourceId to memory option

threadId 和 resourceId 选项已从代理方法调用中移除。请改用 memory 选项，它为内存配置提供了更简洁的 API。这适用于 @mastra/client-js 和 @mastra/react 包。

🌐 The threadId and resourceId options have been removed from agent method calls. Use the memory option instead, which provides a cleaner API for memory configuration. This applies to both @mastra/client-js and @mastra/react packages.

要迁移，请将 threadId 和 resourceId 移动到 memory 选项中：

🌐 To migrate, move threadId and resourceId into the memory option:

使用 @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 钩子：

useChat 钩子在你提供 threadId 时会在内部传递 memory 选项。如果你使用钩子内置的 memory 处理功能，则无需更改组件代码。但是，如果你手动向 sendMessage 传递选项，请相应地更新它们：

🌐 The useChat hook internally passes the memory option when you provide a threadId. No changes are needed in your component code if you're using the hook's built-in memory handling. However, if you were manually passing options to sendMessage, update them accordingly:

  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 选项在创建新线程时也支持传递线程元数据：

🌐 The memory option also supports passing thread metadata when creating new threads:

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* 模式。此更改使类型名称与方法命名约定一致。

🌐 Client SDK types have been renamed from Get* to List* pattern. This change aligns type names with the method naming convention.

要进行迁移，请更新类型导入以使用新的命名模式。

🌐 To migrate, update type imports to use the new naming pattern.

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

Codemod

你可以使用 Mastra 的 codemod CLI 来自动更新你的代码：

🌐 You can use Mastra's codemod CLI to update your code automatically:

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

offset/limit 到 page/perPage 的分页参数

🌐 Pagination parameters from offset/limit to page/perPage

所有使用 offset/limit 的客户端 SDK 方法现在都改为使用 page/perPage。此更改提供了与网页分页模式一致的、更直观的分页模型。

🌐 All client SDK methods that used offset/limit now use page/perPage. This change provides a more intuitive pagination model aligned with web pagination patterns.

要进行迁移，请在所有客户端 SDK 方法调用中更新分页参数。示例：

🌐 To migrate, update pagination parameters in all client SDK method calls. Example:

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

Codemod

你可以使用 Mastra 的 codemod CLI 来自动更新你的代码：

🌐 You can use Mastra's codemod CLI to update your code automatically:

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

getMemoryThread 参数结构

🌐 getMemoryThread parameter structure

getMemoryThread 方法的参数结构已更新。此更改为内存方法提供了更一致的 API。

🌐 The getMemoryThread method parameter structure has been updated. This change provides a more consistent API across memory methods.

要进行迁移，请使用新的参数结构更新方法调用。有关具体更改，请查看更新后的 API 文档。

🌐 To migrate, update the method call with the new parameter structure. Check the updated API documentation for the specific changes.

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

Codemod

你可以使用 Mastra 的 codemod CLI 来自动更新你的代码：

🌐 You can use Mastra's codemod CLI to update your code automatically:

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

用于工作流运行的统一 runById API

🌐 Unified runById API for workflow runs

runById() 方法现在返回一个统一的 WorkflowState 对象，包含元数据（runId、workflowName、resourceId、createdAt、updatedAt）以及处理后的执行状态（status、result、error、payload、steps）。这将之前分开的 runById() 和 runExecutionResult() 方法统一起来。

🌐 The runById() method now returns a unified WorkflowState object containing both metadata (runId, workflowName, resourceId, createdAt, updatedAt) and processed execution state (status, result, error, payload, steps). This unifies the previously separate runById() and runExecutionResult() methods.

该方法还接受一个包含可选 fields 和 withNestedWorkflows 参数的选项对象，用于性能优化。

🌐 The method also accepts an options object with optional fields and withNestedWorkflows parameters for performance optimization.

  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 }

已移除

🌐 Removed

runExecutionResult 方法和 GetWorkflowRunExecutionResultResponse 类型

🌐 runExecutionResult method and GetWorkflowRunExecutionResultResponse type

runExecutionResult() 方法和 GetWorkflowRunExecutionResultResponse 类型已从 @mastra/client-js 中移除。/execution-result API 端点也已被移除。

🌐 The runExecutionResult() method and GetWorkflowRunExecutionResultResponse type have been removed from @mastra/client-js. The /execution-result API endpoints have also been removed.

要迁移，请改用 runById()，它现在返回相同的统一 WorkflowState，包括元数据和处理后的执行状态。

🌐 To migrate, use runById() instead, which now returns the same unified WorkflowState with both metadata and processed execution state.

- 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

toAISdkFormat() 函数已从 @mastra/ai-sdk 中移除。此更改为流转换工具提供了更清晰的命名。

🌐 The toAISdkFormat() function has been removed from @mastra/ai-sdk. This change provides clearer naming for stream conversion utilities.

要迁移，请改用 toAISdkStream()。

🌐 To migrate, use toAISdkStream() instead.

- 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 来自动更新你的代码：

🌐 You can use Mastra's codemod CLI to update your code automatically:

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

网络内存方法

🌐 Network memory methods

@mastra/client-js 中的网络内存方法已被移除。NetworkMemoryThread 类及所有与网络内存相关的方法不再可用。此更改通过移除专用的网络内存功能简化了内存 API。

🌐 Network memory methods have been removed from @mastra/client-js. The NetworkMemoryThread class and all network memory-related methods are no longer available. This change simplifies the memory API by removing specialized network memory functionality.

要进行迁移，请使用常规内存 API，而不是网络内存。

🌐 To migrate, use regular memory APIs instead of 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-related types

与监视相关的类型已从 @mastra/client-js 中移除。这包括 WorkflowWatchResult、WatchEvent 及相关类型。此更改反映了为了支持流式传输而移除监视 API。

🌐 Watch-related types have been removed from @mastra/client-js. This includes WorkflowWatchResult, WatchEvent, and related types. This change reflects the removal of the watch API in favor of streaming.

要进行迁移，请使用工作流流式 API，而不是 watch。

🌐 To migrate, use workflow streaming APIs instead of 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);
+ }

不能直接在工作流实例上调用与运行相关的方法

🌐 Run-related methods cannot be called directly on workflow instance

与运行相关的方法不能直接在工作流实例上调用。你需要先使用 createRun() 方法创建一个运行实例。

🌐 Run-related methods cannot be called directly on workflow instance. You need to create a run instance first using createRun() method.

- 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() 方法已被移除。这些方法现在是具有更新事件结构和返回类型的标准实现。

🌐 The experimental streamVNext(), resumeStreamVNext(), and observeStreamVNext() methods have been removed. These methods are now the standard implementation with updated event structures and return types.

要进行迁移，请改用标准的 stream()、resumeStream() 和 observeStream() 方法。

🌐 To migrate, use the standard stream(), resumeStream(), and observeStream() methods instead.

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

已弃用的流端点

🌐 Deprecated stream endpoints

某些流端点已被弃用并将被移除。/api/agents/:agentId/stream/vnext 端点返回 410 Gone，而 /api/agents/:agentId/stream/ui 已被弃用。此更改将统一使用标准流式端点。

🌐 Some stream endpoints are deprecated and will be removed. The /api/agents/:agentId/stream/vnext endpoint returns 410 Gone, and /api/agents/:agentId/stream/ui is deprecated. This change consolidates on standard streaming endpoints.

要进行迁移，请使用标准流端点或用于 UI 消息转换的 @mastra/ai-sdk。

🌐 To migrate, use the standard stream endpoint or @mastra/ai-sdk for UI message transformations.

- 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

网络内存 API 端点

🌐 Network memory API endpoints

网络内存 API 端点已被移除，包括 /api/memory/network/*。此更改简化了内存 API 的使用界面。

🌐 Network memory API endpoints have been removed including /api/memory/network/*. This change simplifies the memory API surface.

要进行迁移，请使用常规内存 API 端点。

🌐 To migrate, use regular memory API endpoints.

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

与评估相关的客户端 SDK 类型

🌐 Eval-related client SDK types

客户端 SDK 中已移除多个与 eval 相关的类型，包括 GetEvalsByAgentIdResponse、GetTelemetryResponse 和 GetTelemetryParams。此更改反映了对传统 eval 功能的移除。

🌐 Several eval-related types have been removed from the client SDK including GetEvalsByAgentIdResponse, GetTelemetryResponse, and GetTelemetryParams. This change reflects the removal of legacy evals functionality.

要进行迁移，请使用新的评分器 API，而不是旧的评估。

🌐 To migrate, use the new scorers API instead of legacy evals.