Tool

Tool 的執行簽名已更新，改為使用獨立的輸入及 context 參數，而 context 屬性亦已重新整理。

變更

將 createTool 的 execute 簽名改為 (inputData, context) 格式

所有 createTool execute 函式現在都使用獨立的 inputData 及 context 參數，不再使用單一的解構物件。Tool 輸入及執行 context 現在會分開傳遞。

這項簽名變更只適用於 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 context 屬性的組織方式

createTool 中的 context 屬性現在會按命名空間分類。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 context 的變更，請參閱 MCP 遷移指南。

RuntimeContext 改名為 RequestContext

在整個 Tool 執行 context 中，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 自動更新 imports：

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

這項變更適用於所有 Tool 執行方式，不論是直接呼叫，還是透過 Agent 及 Workflow 呼叫。類型收窄可確保你妥善處理驗證錯誤，並避免在存取輸出屬性時發生執行階段錯誤。

使用 outputSchema 驗證 Tool 輸出

設有 outputSchema 的 Tool 現在會在執行階段驗證其傳回值。以往，outputSchema 只用於類型推斷，並不會驗證輸出。

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

如要修正驗證錯誤，請確保 Tool 的輸出符合 schema 定義：

  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 的類型檢查要求，你必須先收窄結果類型，才可存取輸出 schema 的屬性。

呼叫 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 或 non-null assertion：

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