Tool

Tool 執行簽章已更新為使用分開的輸入與內容參數，內容屬性也已重新組織。

已變更

createTool execute 簽章改為 (inputData, context) 格式

所有 createTool execute 函式現在都使用分開的 inputData 與 context 參數，而非單一的解構物件。Tool 輸入與執行內容現在會分別傳入。

此簽章變更僅適用於 createTool。Workflow 的 createStep 呼叫請保留 async (inputData, context) 簽章。

遷移時，請更新 createTool 簽章，將 inputData 作為第一個參數（型別由 inputSchema 決定），並將 context 作為第二個參數。

  createTool({
    id: 'weather-tool',
-   execute: async ({ context, requestContext, mastra }) => {
-     const location = context.location;
-     const userTier = requestContext.get('userTier');
-     return getWeather(location, userTier);
-   },
+   execute: async (inputData, context) => {
+     const location = inputData.location;
+     const userTier = context?.requestContext?.get('userTier');
+     return getWeather(location, userTier);
+   },
  });

createTool 內容屬性的組織方式

createTool 中的內容屬性現在整理到不同命名空間。Agent 專屬屬性位於 context.agent、Workflow 專屬屬性位於 context.workflow，MCP 專屬屬性則位於 context.mcp。這項變更改善組織方式，並讓 API 介面更清楚。

對於在 Agent 內執行的 Tool，請透過 context.agent 存取 Agent 專屬屬性。

  createTool({
    id: 'suspendable-tool',
    suspendSchema: z.object({ message: z.string() }),
    resumeSchema: z.object({ approval: z.boolean() }),
-   execute: async ({ context, suspend, resumeData }) => {
-     if (!resumeData) {
-       return await suspend({ message: 'Waiting for approval' });
-     }
-     if (resumeData.approval) {
-       return { success: true };
-     }
-   },
+   execute: async (inputData, context) => {
+     if (!context?.agent?.resumeData) {
+       return await context?.agent?.suspend({
+         message: 'Waiting for approval',
+       });
+     }
+     if (context.agent.resumeData.approval) {
+       return { success: true };
+     }
+   },
  });

對於在 Workflow 內執行的 Tool，請透過 context.workflow 存取 Workflow 專屬屬性。

  createTool({
    id: 'workflow-tool',
-   execute: async ({ workflowId, runId, state, setState }) => {
-     const currentState = state;
-     setState({ step: 'completed' });
-     return { result: 'done' };
-   },
+   execute: async (inputData, context) => {
+     const currentState = context?.workflow?.state;
+     context?.workflow?.setState({ step: 'completed' });
+     return { result: 'done' };
+   },
  });

Tool 執行時，會根據 suspendSchema 驗證 suspendPayload。如果 suspendPayload 與 suspendSchema 不符，系統會記錄警告並將錯誤作為 Tool 輸出傳回，但仍會繼續暫停。 此外，Tool 恢復時，會根據 resumeSchema 驗證 resumeData。如果 resumeData 與 resumeSchema 不符，Tool 會傳回 ValidationError，阻止 Tool 恢復。

若要略過 suspendSchema 或 resumeSchema 驗證，建立 Tool 時不要定義 suspendSchema 或 resumeSchema。

備註

如需 MCP 專屬 Tool 內容的變更，請參閱 MCP 遷移指南。

RuntimeContext 改為 RequestContext

在整個 Tool 執行內容中，RuntimeContext 類別已重新命名為 RequestContext。新名稱表示此類別包含特定請求的資料。

遷移時，請在 Tool 執行函式中將 runtimeContext 參照更新為 requestContext。

  createTool({
    id: 'my-tool',
    execute: async (inputData, context) => {
-     const userTier = context?.runtimeContext?.get('userTier');
+     const userTier = context?.requestContext?.get('userTier');
      return { result: userTier };
    },
  });

Codemod

你可以使用 Mastra 的 codemod CLI 自動更新匯入：

npx @mastra/codemod@latest v1/runtime-context .

此變更適用於所有 Tool 執行方式，無論是直接呼叫，或透過 Agent 與 Workflow 呼叫。型別縮小可確保你適當處理驗證錯誤，並避免存取輸出屬性時發生執行階段錯誤。

使用 outputSchema 驗證 Tool 輸出

具有 outputSchema 的 Tool 現在會在執行階段驗證傳回值。先前 outputSchema 只用於型別推斷，並不會驗證輸出。

如果 Tool 傳回的資料與其 outputSchema 不符，現在會傳回 ValidationError，而非無效資料。

若要修正驗證錯誤，請確保 Tool 輸出符合結構描述定義：

  const getUserTool = createTool({
    id: "get-user",
    outputSchema: z.object({
      id: z.string(),
      name: z.string(),
      email: z.string().email(),
    }),
    execute: async (inputData) => {
-     return { id: "123", name: "John" }; // Missing email
+     return { id: "123", name: "John", email: "john@example.com" };
    },
  });

驗證失敗時，Tool 會傳回 ValidationError：

+ // Before v1 - invalid output would silently pass through
  await getUserTool.execute({});
- // { id: "123", name: "John" } - missing email
+ // {
+ //   error: true,
+ //   message: "Tool output validation failed for get-user. The tool returned invalid output:\n- email: Required\n\nReturned output: {...}",
+ //   validationErrors: { ... }
+ // }

tool.execute 傳回型別包含 ValidationError

tool.execute 的傳回型別現在包含 ValidationError，以處理驗證失敗。為符合 TypeScript 的型別檢查，你必須先縮小結果型別，再存取輸出結構描述的屬性。

呼叫 tool.execute 時，請先檢查結果是否包含錯誤，再存取輸出屬性：

const result = await getUserTool.execute({})

// Type-safe check for validation errors
if ('error' in result && result.error) {
  console.error('Validation failed:', result.message)
  console.error('Details:', result.validationErrors)
  return
}

// TypeScript knows result is valid here
console.log(result.id, result.name, result.email)

你也可以更新 outputSchema 以符合實際輸出；如果不需要驗證，也可以完全移除 outputSchema。

直接執行 Tool

tool.execute 屬性在型別系統中是選填，以支援由其他方式處理執行邏輯的使用者端 Tool 定義。直接在 Tool 執行個體上呼叫 execute（而非透過 Agent 或 Workflow）時，請使用 optional chaining 或非 null 斷言：

// Optional chaining (recommended)
const result = await weatherTool.execute?.({ location: 'New York' }, {})

// Non-null assertion (when you know execute exists)
const result = await weatherTool.execute!({ location: 'New York' }, {})