Client SDK

Client SDK の変更は、ユーティリティの改名、ページネーションの更新、型の命名規則など、Server 側 API の更新に合わせたものです。

変更

messages が @mastra/core/agent の構文と同一に

@mastra/core/agent の NodeJS 版と同様に、messages 引数は generate、stream、network メソッド呼び出しの第 1 引数になりました。

移行するには、messages をメソッド呼び出しの第 1 引数へ移動します。

@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 オプションへ

threadId と resourceId オプションが Agent メソッド呼び出しから削除されました。代わりに、Memory 設定をより簡潔に指定できる memory オプションを使用します。この変更は @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 を使用する場合

useChat Hook に threadId を指定すると、内部で 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
  });

新しい Thread の作成時には、memory オプションで Thread のメタデータも渡せます。

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 を更新します。

- 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 メソッドは、Web のページベースのページネーションに合わせて page/perPage を使用するようになりました。

移行するには、すべての 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() メソッドは、メタデータ（runId、workflowName、resourceId、createdAt、updatedAt）と処理済みの実行状態（status、result、error、payload、steps）の両方を含む、統一された WorkflowState オブジェクトを返すようになりました。これにより、以前は分かれていた 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 型

runExecutionResult() メソッドと GetWorkflowRunExecutionResultResponse 型が @mastra/client-js から削除されました。/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 関数

toAISdkFormat() 関数が @mastra/ai-sdk から削除されました。代わりに、以下に示す Stream 変換ユーティリティを使用してください。

移行するには、代わりに 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 メソッド

Network Memory メソッドが @mastra/client-js から削除されました。NetworkMemoryThread クラスと Network Memory 関連のすべてのメソッドは利用できなくなりました。この変更では、専用の Network Memory 機能を削除して Memory API を簡素化しています。

移行するには、Network Memory の代わりに通常の Memory API を使用します。

- 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 関連の型

Watch 関連の型が @mastra/client-js から削除されました。これには WorkflowWatchResult、WatchEvent、関連する型が含まれます。この変更は、Streaming を優先して Watch API を削除したことに伴うものです。

移行するには、Watch の代わりに Workflow Streaming API を使用します。

- 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 関連メソッドを Workflow インスタンスから直接呼び出せないように変更

Run 関連のメソッドは、Workflow インスタンスから直接呼び出せません。まず 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: { ... } });

非推奨の Stream エンドポイント

一部の Stream エンドポイントは非推奨で、今後削除されます。/api/agents/:agentId/stream/vnext エンドポイントは 410 Gone を返し、/api/agents/:agentId/stream/ui は非推奨です。この変更により、標準の Streaming エンドポイントに統一されます。

移行するには、標準の Stream エンドポイント、または UI メッセージ変換用の @mastra/ai-sdk を使用します。

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

Eval 関連の Client SDK 型

GetEvalsByAgentIdResponse、GetTelemetryResponse、GetTelemetryParams など、Eval 関連の複数の型が Client SDK から削除されました。この変更は、レガシー Eval 機能の削除に伴うものです。

移行するには、レガシー Eval の代わりに新しい Scorer API を使用します。