> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-TW/llms.txt # Agent 類別 Agent 類別已更新，包括重新組織 Voice 方法、更新屬性存取模式，以及精簡串流 API。 ## 已變更 ### `getAgents` 改為 `listAgents` `mastra.getAgents()` 方法已重新命名為 `mastra.listAgents()`。這項變更與整個 API 使用的命名慣例一致：回傳多筆資料的 getter 方法會使用 `list` 前綴。 遷移時，請將所有 `mastra.getAgents()` 呼叫替換成 `mastra.listAgents()`。 ```diff - const agents = mastra.getAgents(); + const agents = mastra.listAgents(); ``` > **Codemod:** 你可以使用 Mastra 的 codemod CLI 自動更新程式碼： > > **npm**: > > ```bash > npx @mastra/codemod@latest v1/mastra-plural-apis . > ``` > > **pnpm**: > > ```bash > pnpm dlx @mastra/codemod@latest v1/mastra-plural-apis . > ``` > > **Yarn**: > > ```bash > yarn dlx @mastra/codemod@latest v1/mastra-plural-apis . > ``` > > **Bun**: > > ```bash > bun x @mastra/codemod@latest v1/mastra-plural-apis . > ``` ### `RuntimeContext` 改為 `RequestContext` 整個程式碼庫中的 `RuntimeContext` 類別已重新命名為 `RequestContext`。新名稱表示此類別包含特定請求的資料，並符合網頁框架慣例。 遷移時，請將所有匯入與參數名稱從 `RuntimeContext`／`runtimeContext` 更新為 `RequestContext`／`requestContext`。 ```diff - import { RuntimeContext } from '@mastra/core/runtime-context'; + import { RequestContext } from '@mastra/core/request-context'; - const runtimeContext = new RuntimeContext(); - runtimeContext.set('userTier', 'enterprise'); + const requestContext = new RequestContext(); + requestContext.set('userTier', 'enterprise'); - await agent.generate(messages, { runtimeContext }); + await agent.generate(messages, { requestContext }); ``` > **Codemod:** 你可以使用 Mastra 的 codemod CLI 自動更新程式碼： > > ```bash > npx @mastra/codemod@latest v1/runtime-context . > ``` ### 直接屬性存取改為 getter 方法 已棄用直接存取 `agent.llm`、`agent.tools` 與 `agent.instructions` 屬性的方式。這項變更能提供更好的封裝，並與更廣泛的 API 設計保持一致。 遷移時，請使用對應的 getter 方法取代屬性存取。 ```diff - const llm = agent.llm; - const tools = agent.tools; - const instructions = agent.instructions; + const llm = agent.getLLM(); + const tools = agent.getTools(); + const instructions = agent.getInstructions(); ``` > **Codemod:** 你可以使用 Mastra 的 codemod CLI 自動更新程式碼： > > ```bash > npx @mastra/codemod@latest v1/agent-property-access . > ``` ### Voice 方法移至 `agent.voice` 命名空間 Voice 相關方法已從 Agent 類別移至 `agent.voice` 命名空間，將 Voice API 集中於一處。 遷移時，請更新 Voice 方法呼叫，改用 `agent.voice` 命名空間。 ```diff - await agent.speak('Hello'); - await agent.listen(); - const speakers = agent.getSpeakers(); + await agent.voice.speak('Hello'); + await agent.voice.listen(); + const speakers = agent.voice.getSpeakers(); ``` > **Codemod:** 你可以使用 Mastra 的 codemod CLI 自動更新程式碼： > > ```bash > npx @mastra/codemod@latest v1/agent-voice . > ``` ### `agent.fetchMemory()` 改為 `(await agent.getMemory()).recall()` `fetchMemory()` 方法已由明確呈現非同步 Memory 存取方式的 API 取代。 遷移時，請使用新 API 取代 `fetchMemory()` 呼叫。 ```diff - const messages = await agent.fetchMemory({ threadId: 'thread-123' }); + const memory = await agent.getMemory(); + const result = await memory.recall({ threadId: 'thread-123' }); + const messages = result.messages; ``` ### 處理器方法名稱從 `get*` 改為 `list*` Agent 處理器方法已從 `get*` 重新命名為 `list*` 模式，以與更廣泛的 API 保持一致。這項變更符合 `list*` 方法傳回集合的慣例。 遷移時，請更新處理器方法名稱。 ```diff - const inputProcessors = await agent.getInputProcessors(runtimeContext); - const outputProcessors = await agent.getOutputProcessors(runtimeContext); + const inputProcessors = await agent.listInputProcessors(requestContext); + const outputProcessors = await agent.listOutputProcessors(requestContext); ``` > **Codemod:** 你可以使用 Mastra 的 codemod CLI 自動更新程式碼： > > ```bash > npx @mastra/codemod@latest v1/agent-processor-methods . > ``` ### 繼續支援 Zod v3 與 v4 結構化輸出結構描述 Mastra v1 的公開 Agent API 只要接受結構化輸出結構描述，就會繼續同時接受 Zod v3 與 Zod v4 結構描述，包括 `agent.generateLegacy()`、`agent.streamLegacy()` 等方法與相關選項型別。 如果已將 Zod 結構描述傳給 Agent API，不需為 Zod 版本相容性進行遷移。請保留現有的結構描述匯入： ```ts import { z as z3 } from 'zod/v3' import { z as z4 } from 'zod/v4' await agent.generateLegacy({ prompt: 'Summarize this ticket', output: z3.object({ summary: z3.string() }), }) await agent.streamLegacy({ prompt: 'Extract contact info', output: z4.object({ email: z4.string().email() }), }) ``` 只有在想讓整個應用程式統一使用單一 Zod 版本時，才需要更新匯入。 ### AI SDK 版本的預設選項方法重新命名 預設選項方法已重新命名，以區分舊版（AI SDK v4）API 與 AI SDK v5+ API。方法名稱現在會指出其目標 AI SDK 版本。 遷移時，請依使用的 AI SDK 版本更新方法名稱。 ```diff // For legacy AI SDK v4 - const options = await agent.getDefaultGenerateOptions(); - const streamOptions = await agent.getDefaultStreamOptions(); + const options = await agent.getDefaultGenerateOptionsLegacy(); + const streamOptions = await agent.getDefaultStreamOptionsLegacy(); // For new AI SDK v5+ (default) const streamOptions = await agent.getDefaultStreamOptions(); ``` ### `modelSettings.abortSignal` 改為頂層 `abortSignal` `abortSignal` 選項已從 `modelSettings` 移至 stream 與 generate 選項的頂層。執行控制現在位於模型專屬設定之外。 遷移時，請將 `abortSignal` 從 `modelSettings` 移至頂層。 ```diff agent.stream('Hello', { - modelSettings: { - abortSignal: abortController.signal, - }, + abortSignal: abortController.signal, }); ``` > **Codemod:** 你可以使用 Mastra 的 codemod CLI 自動更新程式碼： > > ```bash > npx @mastra/codemod@latest v1/agent-abort-signal . > ``` ### `output` 改為 `structuredOutput.schema` 已棄用的 `output` 與 `experimental_output` 選項已移除。這項變更統一使用單一穩定的結構化輸出 API。 遷移時，請將 `output` 或 `experimental_output` 更新為 `structuredOutput.schema`。 ```diff agent.stream('Hello', { - output: z.object({ result: z.string() }), + structuredOutput: { + schema: z.object({ result: z.string() }), + }, }); ``` ### Agent 現在必須使用 `id` 欄位 建立 Agent 時現在必須提供 `id` 欄位。先前可以建立沒有明確 ID 的 Agent，但現在已不再支援。 遷移時，請在所有 Agent 設定中新增 `id` 欄位。 ```diff const agent = new Agent({ + id: 'my-agent', name: 'My Agent', instructions: 'You are a helpful assistant', model: 'openai/gpt-5.6-sol', }); ``` `id` 可以與 `name` 相同，也可以使用其他識別碼。呼叫 `mastra.getAgentById()` 時會使用此 ID，而且在 Mastra 執行個體中必須是唯一值。 ```typescript // Register agent with Mastra const mastra = new Mastra({ agents: { myAgent: agent, // key can differ from id }, }) // Retrieve by ID const agent = mastra.getAgentById('my-agent') ``` ### 串流 API 回應現在會遮蔽敏感資料 Mastra Server 現在會自動遮蔽 Agent 串流回應中的敏感資訊，避免在 `step-start`、`step-finish` 與 `finish` 串流區塊中意外洩漏系統提示詞、Tool 定義與 API 金鑰。 **遮蔽的內容：** - 包含 LLM 請求承載資料的 `request.body`（系統提示詞、Tool 結構描述） - 步驟結果中的 `metadata.request` - 巢狀步驟資料中的 `output.steps[].request` 這項行為預設為啟用。如果需要存取完整請求資料（例如進行偵錯或用於內部服務），直接使用 Server 轉接器（例如 `@mastra/hono` 或 `@mastra/express`）時可以停用遮蔽。 ## 已移除 ### `generateVNext` 與 `streamVNext` 方法 已棄用的 `generateVNext()` 與 `streamVNext()` 方法已移除。這些方法先前用於相容 AI SDK v5+，但現在已成為標準實作。 遷移時，請使用標準的 `generate()` 與 `stream()` 方法。 ```diff - const result = await agent.generateVNext('Hello'); - const stream = await agent.streamVNext('Hello'); + const result = await agent.generate('Hello'); + const stream = await agent.stream('Hello'); ``` > **Codemod:** 你可以使用 Mastra 的 codemod CLI 自動更新程式碼： > > ```bash > npx @mastra/codemod@latest v1/agent-generate-stream-v-next . > ``` ### `stream()` 與 `generate()` 的 `format` 參數 `agent.stream()` 與 `agent.generate()` 方法已移除 `format` 參數。AI SDK 串流轉換現在由 `@mastra/ai-sdk` 套件處理。這項變更將 AI SDK 專屬程式碼移至專用套件，改善 tree-shaking。 遷移時，請使用 `@mastra/ai-sdk` 的 `toAISdkStream()` 函式進行 AI SDK 格式轉換。 ```diff - const stream = await agent.stream(messages, { - format: 'aisdk', - }); + import { toAISdkStream } from '@mastra/ai-sdk'; + + const stream = await agent.stream(messages); + const aiSdkStream = toAISdkStream(stream, { from: 'agent' }); ``` ### `agent.toStep()` 方法 Agent 類別已移除 `toStep()` 方法。現在可以直接將 Agent 新增至 Workflow 步驟，不需明確轉換。 遷移時，請直接將 Agent 新增至 Workflow 步驟。Workflow 會自動處理轉換。 ```diff - const step = agent.toStep(); - const workflow = new Workflow({ - steps: [step], - }); + const workflow = new Workflow({ + steps: [agent], + }); ``` ### Agent 的 `TMetrics` 泛型參數 `AgentConfig` 與 `Agent` 建構函式已移除 `TMetrics` 泛型參數。指標／scorer 現在使用 scorer API 設定，不再屬於 Agent 型別系統的一部分。 遷移時，請移除 `TMetrics` 泛型參數，並使用新 API 設定 scorer。 ```diff - const agent = new Agent({ + const agent = new Agent({ // ... }); ``` ### Tripwire 回應格式變更 Tripwire 回應格式已從個別的 `tripwire` 與 `tripwireReason` 欄位，變更為包含所有相關資料的單一 `tripwire` 物件。 遷移時，請更新程式碼，從新物件結構存取 tripwire 資料。 ```diff const result = await agent.generate('Hello'); - if (result.tripwire) { - console.log(result.tripwireReason); - } + if (result.tripwire) { + console.log(result.tripwire.reason); + // New fields available: + // result.tripwire.retry - whether this step should be retried + // result.tripwire.metadata - additional metadata from the processor + // result.tripwire.processorId - which processor triggered the tripwire + } ``` 對於串流回應： ```diff for await (const chunk of stream.fullStream) { if (chunk.type === 'tripwire') { - console.log(chunk.payload.tripwireReason); + console.log(chunk.payload.reason); + // New fields available: + // chunk.payload.retry + // chunk.payload.metadata + // chunk.payload.processorId } } ``` 步驟結果現在也包含 tripwire 資訊： ```diff const result = await agent.generate('Hello'); for (const step of result.steps) { - // No tripwire info on steps + if (step.tripwire) { + console.log('Step was blocked:', step.tripwire.reason); + } } ``` ### `prepareStep` 訊息格式 `prepareStep` 回呼現在會收到 `MastraDBMessage` 格式的訊息，而非 AI SDK v5+ 模型訊息格式。這項變更讓 `prepareStep` 與新的 `processInputStep` 處理器方法統一，後者會在 Agentic 迴圈的每個步驟執行。 如果需要舊的 AI SDK v5+ 格式，請使用 `messageList.get.all.aiV5.model()`： ```diff agent.generate('Hello', { prepareStep: async ({ messages, messageList }) => { - // messages was AI SDK v5+ ModelMessage format - console.log(messages[0].content); + // messages is now MastraDBMessage format + // Use messageList to get AI SDK v5+ format if needed: + const aiSdkMessages = messageList.get.all.aiV5.model(); return { toolChoice: 'auto' }; }, }); ``` ### `threadId` 與 `resourceId` 改為 `memory` 選項 `agent.stream()` 與 `agent.generate()` 已移除 `threadId` 與 `resourceId` 選項。請改用 `memory` 選項，為 Memory 設定提供更簡潔的 API。 遷移時，請將 `threadId` 與 `resourceId` 移至 `memory` 選項： ```diff await agent.stream('Hello', { - threadId: 'thread-123', - resourceId: 'user-456', + memory: { + thread: 'thread-123', + resource: 'user-456', + }, }); ``` 建立新討論串時，`memory` 選項也支援傳入討論串中繼資料： ```typescript await agent.stream('Hello', { memory: { thread: { id: 'thread-123', title: 'Support conversation', metadata: { category: 'billing' }, }, resource: 'user-456', }, }) ```