Client SDK

Client SDK 变更与 Server 端 API 更新保持一致，包括重命名工具函数、更新分页以及类型命名约定。

已变更

messages 现在与 @mastra/core/agent 语法一致

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([...], {
  });

Codemod

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

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：

  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 传递选项，请相应更新：

  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',
  },
});

Client SDK 类型从 Get* 改为 List*

Client SDK 类型已从 Get* 模式重命名为 List* 模式。此变更让类型名称与方法命名约定保持一致。

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

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

Codemod

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

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

分页参数从 offset/limit 改为 page/perPage

所有使用 offset/limit 的 Client SDK 方法现在都使用 page/perPage，以匹配基于页的 Web 分页。

迁移时，请更新所有 Client SDK 方法调用中的分页参数。示例：

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

Codemod

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

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

getMemoryThread 参数结构

getMemoryThread 方法的参数结构已更新。此变更让各个 Memory 方法的 API 更加一致。

迁移时，请使用新的参数结构更新方法调用。具体变更请查阅更新后的 API 文档。

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

Codemod

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

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 参数，用于优化性能。

  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，同时包含元数据和处理后的执行状态。

- 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()。

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

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。

- 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。

- 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 实例。

- 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() 和 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 端点

包括 /api/memory/network/* 在内的 Network Memory API 端点已移除。此变更简化了 Memory API 界面。

迁移时，请使用常规 Memory API 端点。

- 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。