> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ja/llms.txt # Client SDK Client SDK の変更は、ユーティリティの改名、ページネーションの更新、型の命名規則など、Server 側 API の更新に合わせたものです。 ## 変更 ### `messages` が `@mastra/core/agent` の構文と同一に `@mastra/core/agent` の NodeJS 版と同様に、`messages` 引数は `generate`、`stream`、`network` メソッド呼び出しの第 1 引数になりました。 移行するには、`messages` をメソッド呼び出しの第 1 引数へ移動します。 **`@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` オプションへ `threadId` と `resourceId` オプションが Agent メソッド呼び出しから削除されました。代わりに、Memory 設定をより簡潔に指定できる `memory` オプションを使用します。この変更は `@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 を使用する場合 `useChat` Hook に `threadId` を指定すると、内部で 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 }); ``` 新しい Thread の作成時には、`memory` オプションで Thread のメタデータも渡せます。 ```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*` パターンに改名されました。この変更により、型名とメソッドの命名規則が一致します。 移行するには、新しい命名パターンの型を使用するよう import を更新します。 ```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 メソッドは、Web のページベースのページネーションに合わせて `page/perPage` を使用するようになりました。 移行するには、すべての 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()` メソッドは、メタデータ（runId、workflowName、resourceId、createdAt、updatedAt）と処理済みの実行状態（status、result、error、payload、steps）の両方を含む、統一された `WorkflowState` オブジェクトを返すようになりました。これにより、以前は分かれていた `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` 型 `runExecutionResult()` メソッドと `GetWorkflowRunExecutionResultResponse` 型が `@mastra/client-js` から削除されました。`/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` 関数 `toAISdkFormat()` 関数が `@mastra/ai-sdk` から削除されました。代わりに、以下に示す Stream 変換ユーティリティを使用してください。 移行するには、代わりに `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 メソッド Network Memory メソッドが `@mastra/client-js` から削除されました。`NetworkMemoryThread` クラスと Network Memory 関連のすべてのメソッドは利用できなくなりました。この変更では、専用の Network Memory 機能を削除して Memory API を簡素化しています。 移行するには、Network Memory の代わりに通常の Memory API を使用します。 ```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 関連の型 Watch 関連の型が `@mastra/client-js` から削除されました。これには `WorkflowWatchResult`、`WatchEvent`、関連する型が含まれます。この変更は、Streaming を優先して Watch API を削除したことに伴うものです。 移行するには、Watch の代わりに Workflow Streaming API を使用します。 ```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); + } ``` ### Run 関連メソッドを Workflow インスタンスから直接呼び出せないように変更 Run 関連のメソッドは、Workflow インスタンスから直接呼び出せません。まず `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: { ... } }); ``` ### 非推奨の Stream エンドポイント 一部の Stream エンドポイントは非推奨で、今後削除されます。`/api/agents/:agentId/stream/vnext` エンドポイントは 410 Gone を返し、`/api/agents/:agentId/stream/ui` は非推奨です。この変更により、標準の Streaming エンドポイントに統一されます。 移行するには、標準の Stream エンドポイント、または UI メッセージ変換用の `@mastra/ai-sdk` を使用します。 ```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'); ``` ### Eval 関連の Client SDK 型 `GetEvalsByAgentIdResponse`、`GetTelemetryResponse`、`GetTelemetryParams` など、Eval 関連の複数の型が Client SDK から削除されました。この変更は、レガシー Eval 機能の削除に伴うものです。 移行するには、レガシー Eval の代わりに新しい Scorer API を使用します。