Tools

Agents 使用工具调用 API 或查询数据库，也可以运行代码库中的自定义函数。工具通过提供结构化的数据访问和执行明确定义的操作，赋予 agents 超越语言生成的能力。你还可以从远程 MCP 服务器加载工具，扩展 Agent 的能力。对于 Linear、Slack、GitHub 等服务，Mastra 平台上的 Connect 提供带托管凭据的现成工具，可与自有工具组合使用。

致 AI agents： execute 只有一种签名：execute(inputData, context)。第一个参数会根据 inputSchema 校验。运行时始终提供第二个参数，包含 requestContext、tracingContext、abortSignal 及其他执行元数据；不使用时可以省略。其他形式均已过时。运行 npx mastra api tool execute weather-tool '{"location":"San Francisco"}' 可直接测试此工具，无需编写临时脚本。该命令需要运行中的 Mastra 服务端；可用 npx mastra dev 启动本地服务端，或通过 --url 传入可访问的服务端基础 URL。构造不同输入前，先运行 npx mastra api tool execute --schema。安装 Mastra skill（npx skills add mastra-ai/skills --skill mastra）可获取完整的 API CLI 发现、目标定位、schema、身份验证和错误处理指南。

何时使用工具

当 Agent 需要从远程资源获取额外上下文或信息，或需要运行执行特定操作的代码时，使用工具。这包括模型无法可靠独立处理的任务，例如获取实时数据，或返回一致、明确定义的输出。

快速开始

从 @mastra/core/tools 导入 createTool，并定义包含 id、description、inputSchema、outputSchema 和 execute 函数的工具。

以下示例创建一个从 API 获取天气数据的工具。execute 只有一种签名：execute(inputData, context)。第一个参数包含根据 inputSchema 校验过的输入。运行时始终将第二个参数作为执行上下文提供，不使用时可以在函数签名中省略。你也可以在函数签名中直接解构输入字段。

src/mastra/tools/weather-tool.ts

import { createTool } from '@mastra/core/tools'
import { z } from 'zod'

export const weatherTool = createTool({
  id: 'weather-tool',
  description: 'Fetches weather for a location',
  inputSchema: z.object({
    location: z.string(),
  }),
  outputSchema: z.object({
    location: z.string(),
    temperatureCelsius: z.number(),
    conditions: z.string(),
  }),
  execute: async ({ location }, { abortSignal }) => {
    const response = await fetch(`https://wttr.in/${location}?format=j1`, {
      signal: abortSignal,
    })
    const data = await response.json()

    return {
      location,
      temperatureCelsius: Number(data.current_condition[0].temp_C),
      conditions: data.current_condition[0].weatherDesc[0].value,
    }
  },
})

创建工具时，请保持描述简洁并聚焦于工具的用途，突出其主要用例。描述性的 schema 名称也有助于引导 Agent 使用该工具。可用属性、配置和示例的更多信息参见 createTool 参考。

要让 Agent 使用工具，请将其添加到 Agent 类的 tools 属性。在 Agent 的 system prompt 中提及可用工具及其大致用途，有助于 Agent 判断何时调用工具、何时不调用。

src/mastra/agents/weather-agent.ts

import { Agent } from '@mastra/core/agent'
import { weatherTool } from '../tools/weather-tool'

export const weatherAgent = new Agent({
  id: 'weather-agent',
  name: 'Weather Agent',
  instructions: `
    You are a helpful weather assistant.
    Use the weatherTool to fetch current weather data.`,
  model: 'openai/gpt-5.6-sol',
  tools: { weatherTool },
})

定义 schemas

你可以使用任何支持 Standard JSON Schema 的库定义工具的 inputSchema 和 outputSchema，包括 Zod、Valibot 和 ArkType 等。

Zod

src/mastra/tools/weather-tool.ts

import { createTool } from '@mastra/core/tools'
import { z } from 'zod'

export const weatherTool = createTool({
  id: 'weather-tool',
  description: 'Fetches weather for a location',
  inputSchema: z.object({
    location: z.string(),
  }),
  outputSchema: z.object({
    location: z.string(),
    temperatureCelsius: z.number(),
    conditions: z.string(),
  }),
  execute: async ({ location }) => {
    return { location, temperatureCelsius: 21, conditions: 'sunny' }
  },
})

Valibot

src/mastra/tools/weather-tool.ts

import { createTool } from '@mastra/core/tools'
import * as v from 'valibot'
import { toStandardJsonSchema } from '@valibot/to-json-schema'

export const weatherTool = createTool({
  id: 'weather-tool',
  description: 'Fetches weather for a location',
  inputSchema: toStandardJsonSchema(
    v.object({
      location: v.string(),
    }),
  ),
  outputSchema: toStandardJsonSchema(
    v.object({
      location: v.string(),
      temperatureCelsius: v.number(),
      conditions: v.string(),
    }),
  ),
  execute: async ({ location }) => {
    return { location, temperatureCelsius: 21, conditions: 'sunny' }
  },
})

ArkType

src/mastra/tools/weather-tool.ts

import { createTool } from '@mastra/core/tools'
import { type } from 'arktype'

export const weatherTool = createTool({
  id: 'weather-tool',
  description: 'Fetches weather for a location',
  inputSchema: type({
    location: 'string',
  }),
  outputSchema: type({
    location: 'string',
    temperatureCelsius: 'number',
    conditions: 'string',
  }),
  execute: async ({ location }) => {
    return { location, temperatureCelsius: 21, conditions: 'sunny' }
  },
})

处理输出校验失败

当结果不匹配 outputSchema 时，Mastra 会记录警告并返回校验错误对象，而不是结果本身。模型会将调用视为失败，并可能重试。对于结果产生时副作用已经发生的工具，请设置 outputValidation: 'warn'。Mastra 仍会记录不匹配，但会原样返回真实结果，避免模型重试已经下单的订单。

src/mastra/tools/place-order-tool.ts

export const placeOrderTool = createTool({
  id: 'place-order',
  description: 'Places an order and returns its id and total',
  inputSchema: z.object({ sku: z.string(), quantity: z.number().int().positive() }),
  outputSchema: z.object({ orderId: z.string(), total: z.number() }),
  outputValidation: 'warn',
  execute: async ({ sku, quantity }) => {
    return await orders.create({ sku, quantity })
  },
})

多个工具

Agent 可以使用多个工具，将复杂任务中的特定部分委派给各个工具。Agent 根据用户消息、自身 instructions，以及工具描述和 schemas 决定使用哪些工具。

src/mastra/agents/weather-agent.ts

import { Agent } from '@mastra/core/agent'
import { weatherTool } from '../tools/weather-tool'
import { hazardsTool } from '../tools/hazards-tool'

export const weatherAgent = new Agent({
  id: 'weather-agent',
  name: 'Weather Agent',
  instructions: `
    You are a helpful weather assistant.
    Use the weatherTool to fetch current weather data.
    Use the hazardsTool to provide information about potential weather hazards.`,
  model: 'openai/gpt-5.6-sol',
  tools: { weatherTool, hazardsTool },
})

将 Agents 用作工具

通过 agents 配置添加子 Agents，即可创建监督者。Mastra 会将每个子 Agent 转换为 agent-<key> 工具。请为每个子 Agent 添加 description，让监督者知道何时委派。

src/mastra/agents/supervisor.ts

import { Agent } from '@mastra/core/agent'

const writer = new Agent({
  id: 'writer',
  name: 'Writer',
  description: 'Drafts and edits written content',
  instructions: 'You are a skilled writer.',
  model: 'openai/gpt-5.6-sol',
})

export const supervisor = new Agent({
  id: 'supervisor',
  name: 'Supervisor',
  instructions: 'Coordinate the writer to produce content.',
  model: 'openai/gpt-5.6-sol',
  agents: { writer },
})

将 Workflows 用作工具

通过 workflows 配置添加 workflows。Mastra 会将每个 workflow 转换为 workflow-<key> 工具，使用 workflow 的 inputSchema 和 outputSchema。请为 workflow 添加 description，让 Agent 知道何时触发它。

src/mastra/agents/research-agent.ts

import { Agent } from '@mastra/core/agent'
import { researchWorkflow } from '../workflows/research-workflow'

export const researchAgent = new Agent({
  id: 'research-agent',
  name: 'Research Agent',
  instructions: 'You are a research assistant.',
  model: 'openai/gpt-5.6-sol',
  workflows: { researchWorkflow },
})

在 agents 之间共享工具

当多个 agents 使用同一个工具时，直接导入是最佳选择。每个 Agent 导入该工具并将其添加到自己的 tools 记录中。依赖关系保持明确，每个 Agent 都可独立使用。

src/mastra/tools/weather-tool.ts

import { createTool } from '@mastra/core/tools'

export const weatherTool = createTool({
  id: 'weather-tool',
  // Rest of the tool definition...
})

src/mastra/agents/weather-agents.ts

import { Agent } from '@mastra/core/agent'
import { weatherTool } from '../tools/weather-tool'

export const weatherAgent = new Agent({
  id: 'weather-agent',
  name: 'Weather Agent',
  instructions: 'Answer questions about current weather.',
  model: 'openai/gpt-5.6-sol',
  tools: { weatherTool },
})

src/mastra/agents/travel-agents.ts

import { Agent } from '@mastra/core/agent'
import { weatherTool } from '../tools/weather-tool'

export const travelAgent = new Agent({
  id: 'travel-agent',
  name: 'Travel Agent',
  instructions: 'Help users plan trips.',
  model: 'openai/gpt-5.6-sol',
  tools: { weatherTool },
})

如果需要从 Mastra 实例访问工具，参见 Mastra.getTool()、Mastra.getToolById()、Mastra.listTools() 和 Agent 参考。

为模型塑造输出

当工具为应用返回丰富的结构化数据，但你希望模型收到更小或多模态的表示时，使用 toModelOutput。这样既能保持模型上下文聚焦，又能在应用中保留完整的工具结果。

src/mastra/tools/weather-tool.ts

export const weatherTool = createTool({
  execute: async ({ location }) => {
    const response = await fetch(`https://wttr.in/${location}?format=j1`)
    const data = await response.json()

    return {
      location,
      temperatureCelsius: Number(data.current_condition[0].temp_C),
      conditions: data.current_condition[0].weatherDesc[0].value,
      weatherIconUrl: data.current_condition[0].weatherIconUrl[0].value,
      source: data,
    }
  },
  toModelOutput: output => {
    return {
      type: 'content',
      value: [
        {
          type: 'text',
          text: `${output.location}: ${output.temperatureCelsius}°C and ${output.conditions}`,
        },
        { type: 'image-url', url: output.weatherIconUrl },
      ],
    }
  },
})

toModelOutput 也适用于客户端工具。对于通过 clientTools 传入的工具，映射会在工具执行后于客户端运行，转换后的输出会与原始结果一起发送回服务器。对于在服务器上定义但没有 execute 函数的工具（浏览器运行该工具并在下一次请求时返回结果），服务器定义中的 toModelOutput 会应用于传入的结果。模型收到的是转换后的内容，而不是原始工具结果。

在客户端运行的工具

没有 execute 函数的工具是客户端工具：服务器无法运行它。Agent 会在模型调用它的那一步停止。运行以 finishReason: 'tool-calls' 结束，在工具获得结果之前，模型不会产生更多文本。请选择符合模型所需返回内容的模式：

• 客户端运行工具，且模型需要其结果：省略 execute。客户端运行工具，将结果加入对话，并发送新请求让 Agent 继续。使用 AI SDK useChat() 时，参见使用 useChat() 的客户端工具。
• 客户端只渲染调用（例如产品卡片）：为该工具提供返回简短确认的 execute。Agent 会在同一次运行中继续，客户端从其输入渲染工具部分。请返回较小的值，而不是回显输入，以保持模型上下文和已存储消息精简。
• 工具需要用户提供结构化答案（例如确认购物车写入）：在 execute 中调用 suspend()，并使用用户的答案恢复。参见使用 suspend() 的运行时挂起。

src/mastra/tools/show-product-tool.ts

import { createTool } from '@mastra/core/tools'
import { z } from 'zod'

export const showProductTool = createTool({
  id: 'show-product',
  description: 'Shows a product card to the user',
  inputSchema: z.object({
    productId: z.string(),
  }),
  execute: async () => ({ rendered: true }),
})

子 Agents 无法运行客户端工具。当子 Agent 调用没有 execute 的工具时，其运行会停止，监督者会在委派结果的 subAgentPendingToolCalls 中收到未解决的调用。请将客户端工具交给监督者，或在子 Agent 的工具中使用 suspend()。挂起会通过监督者传递，参见在监督者 agents 中使用 suspend()。

为 UI 和对话记录转换工具 payload

当工具返回应用需要的原始数据，但面向浏览器的流或用户可见的对话记录消息应收到更小或更安全的形态时，使用 transform。transform 与 toModelOutput 相互独立：toModelOutput 塑造发送回模型的 payload，而 transform 为 display 和 transcript 目标塑造工具输入、输出、错误、审批 payload 和挂起 payload。

工具级 transform 只会更改其定义的阶段。在下面的示例中，只有 output 被转换，因此存储的工具输入保持不变。如果配置了 transform 但它执行失败，Mastra 不会回退到原始 payload 用于 display 或 transcript 目标。当没有可用的安全 inputDelta 转换时，输入增量会被抑制。

以下示例从两个目标中移除机密信息：

src/mastra/tools/customer-tool.ts

import { createTool } from '@mastra/core/tools'
import { z } from 'zod'

export const customerTool = createTool({
  id: 'lookup-customer',
  description: 'Looks up a customer by id',
  inputSchema: z.object({
    customerId: z.string(),
  }),
  outputSchema: z.object({
    ssn: z.string(),
  }),
  execute: async ({ customerId }) => {
    // const response = await fetch(`https://your-crm.example.com/customers/${customerId}`)
    // const { ssn } = await response.json()
    return {
      ssn: '123-45-6789',
    }
  },
  transform: {
    display: {
      output: () => ({ ssn: '***-**-****' }),
    },
    transcript: {
      output: () => ({ ssn: '***-**-****' }),
    },
  },
})

你的应用代码仍会收到工具返回的原始 ssn。面向浏览器的流会获得 display 输出，用户可见的对话记录消息会获得 transcript 输出。

当 DurableAgent 能在进程重启后完成工具调用时，请在工具的 transform.transcript 配置中声明所需的对话记录脱敏。传给 DurableAgent 的单次调用 transform 位于进程内运行注册表中，无法在新进程中恢复。持久化 worker 会从已注册的工具重新解析工具级 transform。

关于更多阶段（包括 input、inputDelta、error、approval、suspend 和 resume），参见 createTool() 参考。若要在多个工具间共享规则，请在 Agent 构造函数中配置 Agent 级 transform 策略。

在工具调用前后运行逻辑

使用 hooks 在 Agent 每次工具调用前后运行自定义逻辑。Hooks 适用于所有工具来源：已分配工具、memory 工具、toolsets、客户端工具、Agent 和 workflow 工具，以及 workspace 工具。常见用途包括日志、审计、输入校验和阻止特定调用。

src/mastra/agents/support-agent.ts

import { Agent } from '@mastra/core/agent'

export const supportAgent = new Agent({
  id: 'support-agent',
  name: 'support-agent',
  instructions: 'Help users with their questions.',
  model: 'openai/gpt-5.6-sol',
  hooks: {
    beforeToolCall: ({ toolName, input }) => {
      console.log(`Running ${toolName}`, input)
    },
    afterToolCall: ({ toolName, output, error }) => {
      console.log(`Finished ${toolName}`, { output, error })
    },
  },
})

beforeToolCall 在工具执行前运行，并收到工具名称、输入和执行上下文。返回 { proceed: false, output } 可完全跳过工具调用，Agent 会将 output 作为工具结果：

const guardedAgent = new Agent({
  id: 'guarded-agent',
  name: 'guarded-agent',
  instructions: 'Run shell commands for the user.',
  model: 'openai/gpt-5.6-sol',
  hooks: {
    beforeToolCall: ({ toolName, input }) => {
      const command = (input as { command?: string }).command ?? ''
      if (toolName === 'execute_command' && command.includes('rm -rf')) {
        return { proceed: false, output: 'Command blocked by policy.' }
      }
    },
  },
})

afterToolCall 在工具完成后运行，无论成功还是失败。成功时会收到 output；如果工具抛出异常，则会收到 error，并在 hook 运行后重新抛出该错误。

单次执行的 hooks

向 .generate() 或 .stream() 传入 hooks，可为单次执行设置 hooks。单次执行的 hooks 会覆盖匹配的 Agent 级 hooks：

await supportAgent.generate('Look up the order status', {
  hooks: {
    beforeToolCall: ({ toolName }) => {
      console.log(`This run only: ${toolName}`)
    },
  },
})

Agent 级和单次执行的 hooks 按键合并：执行时只传 beforeToolCall，仍会保留 Agent 级的 afterToolCall。

流式传输

工具支持生命周期 hooks，让你在流式传输期间监控工具执行的不同阶段。这些 hooks 对日志或分析尤其有用。

通用 writer API 用法参见流式传输。

可用 Hooks

• onInputStart：工具调用输入开始流式传输时调用
• onInputDelta：输入流式传入时，每个 chunk 调用一次
• onInputAvailable：完整输入被解析并校验后调用
• onOutput：工具成功执行后带着输出调用

所有生命周期 hooks 的详细文档参见 createTool() 参考。

示例：使用 onInputAvailable 和 onOutput

import { createTool } from '@mastra/core/tools'
import { z } from 'zod'

export const weatherTool = createTool({
  id: 'weather-tool',
  description: 'Get weather information',
  inputSchema: z.object({
    location: z.string(),
  }),
  outputSchema: z.object({
    location: z.string(),
    temperatureCelsius: z.number(),
    conditions: z.string(),
  }),
  // Called when the complete input is available
  onInputAvailable: ({ input, toolCallId }) => {
    console.log(`Weather requested for: ${input.location}`)
  },
  execute: async ({ location }) => {
    const weather = await fetchWeather(location)
    return weather
  },
  // Called after successful execution
  onOutput: ({ output, toolName }) => {
    console.log(`${toolName} result: ${output.temperatureCelsius}°C, ${output.conditions}`)
  },
})

在 UI 中流式显示工具输入

当模型生成工具调用时，参数会在最终的 tool-call chunk 之前，以 tool-call-delta 流 chunks 的形式增量到达。UI 可以监听对应的 tool_input_start、tool_input_delta 和 tool_input_end 事件，在工具参数流式传入时进行渲染，例如立即显示文件路径或命令，而无需等待完整工具调用。

对累积的 argsTextDelta 片段使用部分 JSON 解析器，可以在 JSON 完整之前提取可用的参数值。这支持编辑工具的实时 diff 预览、写入工具的文件内容流式显示，以及即时显示搜索模式或文件路径等功能。

控制工具选择

向 .generate() 或 .stream() 传入 toolChoice 或 activeTools，控制 Agent 在运行时使用哪些工具。

await agent.generate('Check the forecast', {
  toolChoice: 'required',
  activeTools: ['weatherTool'],
})

包括 toolsets、clientTools 和 prepareStep 在内的所有运行时选项，参见 Agent.generate() 参考。

控制流响应中的 toolName

流响应中的 toolName 由你使用的对象键决定，而不是工具、Agent 或 workflow 的 id 属性。

export const weatherTool = createTool({
  id: 'weather-tool',
})

// Using the variable name as the key
tools: { weatherTool }
// Stream returns: toolName: "weatherTool"

// Using the tool's id as the key
tools: { [weatherTool.id]: weatherTool }
// Stream returns: toolName: "weather-tool"

// Using a custom key
tools: { "my-custom-name": weatherTool }
// Stream returns: toolName: "my-custom-name"

这让你可以指定工具在流中的标识方式。若希望 toolName 与工具的 id 一致，请使用工具的 id 作为对象键。

将子 Agents 和 workflows 用作工具

子 Agents 和 workflows 遵循相同模式。它们会被转换为工具，名称由前缀加上你的对象键组成：

属性	前缀	示例键	toolName
agents	agent-	weather	agent-weather
workflows	workflow-	research	workflow-research

const orchestrator = new Agent({
  id: 'orchestrator',
  agents: {
    weather: weatherAgent, // toolName: "agent-weather"
  },
  workflows: {
    research: researchWorkflow, // toolName: "workflow-research"
  },
})

请注意，对于子 Agents，你会在流响应中看到两个不同的标识符：

• 工具调用事件中的 toolName: "agent-weather"：生成的工具包装器名称
• data-tool-agent chunks 中的 id: "weather-agent"：子 Agent 实际的 id 属性

内置工具

Mastra 在 @mastra/core/tools 中包含与 Agent 无关的内置工具，为任何 Agent 增加交互和组织能力。

每个工具有两个名称：你导入的导出名，以及模型在工具调用、traces 和 toolName 字段中看到的工具 ID。

导出	工具 ID	用途
askUserTool	ask_user	向用户提问并等待回答
submitPlanTool	submit_plan	提交计划文件供用户审批
taskWriteTool	task_write	创建或替换结构化任务列表
taskUpdateTool	task_update	按 ID 更新一个已跟踪任务
taskCompleteTool	task_complete	将一个已跟踪任务标记为完成
taskCheckTool	task_check	检查任务列表的完成状态
webSearchTool	<provider.defined>	运行当前提供商的原生 web 搜索
webFetchTool	web_fetch	通过 URL 获取网页并返回其文本内容

使用提供商 web 搜索

若希望由模型提供商运行其原生 web 搜索工具，请从 @mastra/core/tools 导入 webSearchTool。Mastra 会在运行时从当前模型解析它，然后将提供商管理的工具传给模型。

src/mastra/agents/research-agent.ts

import { Agent } from '@mastra/core/agent'
import { webSearchTool } from '@mastra/core/tools'

export const researchAgent = new Agent({
  id: 'research-agent',
  name: 'Research Agent',
  instructions: 'Use web search when you need current information.',
  model: 'openai/gpt-5.6-sol',
  tools: {
    search: webSearchTool,
  },
})

webSearchTool 支持 OpenAI、Anthropic、Google Gemini 和 xAI 模型。如果 Mastra 无法从当前模型推断出这些提供商之一，Agent 运行会以 MastraError 失败。

解析后的工具 ID 来自提供商：openai.web_search、anthropic.web_search_20250305、google.google_search 或 xai.web_search。

search 键只是 Agent 本地的工具名称，可使用任意键。webSearchTool 值告诉 Mastra 使用提供商 web 搜索。

获取网页

当 Agent 需要读取特定 URL 时，从 @mastra/core/tools 导入 webFetchTool。该工具通过 HTTP 或 HTTPS 请求页面，并返回其文本内容及响应元数据。

src/mastra/agents/reader-agent.ts

import { Agent } from '@mastra/core/agent'
import { webFetchTool } from '@mastra/core/tools'

export const readerAgent = new Agent({
  id: 'reader-agent',
  name: 'Reader Agent',
  instructions: 'Fetch the page the user links to before answering.',
  model: 'openai/gpt-5.6-sol',
  tools: {
    fetch: webFetchTool,
  },
})

该工具接收单个 url 输入，并返回 content、truncated、status、statusText、contentType、url 和 ok。它应用以下限制：

• 只允许 http: 和 https: URL。
• 阻止对 localhost 以及私有或保留 IP 地址的请求，包括 DNS 解析返回的地址。
• 响应会在 100,000 个字符处截断，结果中 truncated: true。
• 请求最多跟随 5 次重定向，超时时间为 15 秒。

失败不会抛出异常。工具会返回 isError: true，原因放在 content 中，以便 Agent 重试或解释问题。

向用户提问

导入 askUserTool 并将其添加到 Agent 的工具集中。

该工具会挂起运行，并发出带有问题的 tool-call-suspended 事件。当你使用用户的答案调用 resumeStream() 时，它会恢复。

src/mastra/agents/index.ts

import { Agent } from '@mastra/core/agent'
import { askUserTool } from '@mastra/core/tools'

const agent = new Agent({
  id: 'assistant',
  name: 'Assistant',
  instructions: 'Ask the user for clarification when the request is ambiguous.',
  model,
  tools: { askUserTool },
})

对 Agent 进行流式调用，并监听 tool-call-suspended chunks。suspendPayload 包含问题和可选的结构化选项：

src/run.ts

const stream = await agent.stream('Summarize my project')

for await (const chunk of stream.fullStream) {
  if (chunk.type === 'tool-call-suspended') {
    const { question, options } = chunk.payload.suspendPayload
    console.log(question)
    const answer = await getUserAnswer() // your UI logic
    const resumed = await agent.resumeStream(answer, { runId: stream.runId })
    for await (const c of resumed.textStream) process.stdout.write(c)
  }
}

askUserTool 支持自由文本、单选（options 数组）和多选（selectionMode: 'multi_select'）提示。可与 autoResumeSuspendedTools 搭配使用，让 Agent 从用户的下一条聊天消息自动恢复。详情参见自动恢复工具。

提交计划以供审核

导入 submitPlanTool，让 Agent 将计划写入文件并提交给用户审核。该工具会挂起运行，直到用户批准或拒绝：

src/run.ts

for await (const chunk of stream.fullStream) {
  if (chunk.type === 'tool-call-suspended' && chunk.payload.toolName === 'submit_plan') {
    const { path } = chunk.payload.suspendPayload
    // Read and display the plan file, then resume:
    const resumed = await agent.resumeStream({ action: 'approved' }, { runId: stream.runId })
    for await (const c of resumed.textStream) process.stdout.write(c)
  }
}

任务跟踪

任务工具为 Agent 运行管理结构化的持久化任务列表。它们需要 Memory，以便列表持久化在线程作用域存储中。

通过 TaskSignalProvider添加任务跟踪，它会在单次注册中打包全部四个工具和 TaskStateProcessor：

src/mastra/agents/index.ts

import { Agent } from '@mastra/core/agent'
import { Memory } from '@mastra/memory'
import { TaskSignalProvider } from '@mastra/core/signals'

const agent = new Agent({
  id: 'coder',
  name: 'Coder',
  instructions: 'Track your progress with the task tools.',
  model,
  memory: new Memory(),
  signals: [new TaskSignalProvider()],
})

同一时间只能有一个任务处于 in_progress。该列表存储在 thread 作用域的 threadState 存储 domain 中，并投影到 Agent 的 state-signal 通道，因此能在观察式记忆截断后保留。完整 schemas 参见任务工具参考。

AgentController会在每种模式下自动包含所有内置工具，无需手动添加。AgentController 特有的行为参见工具审批。

相关内容

• createTool 参考
• Agent.generate() 参考：工具选择、步骤和回调的运行时选项
• 后台任务：运行长时工具而不阻塞 Agent 循环
• MCP 概览
• Connect 工具：为连接到 Mastra 平台项目的提供商提供现成工具
• 动态工具搜索：为拥有大量工具的 agents 按需加载工具
• 带结构化输出的工具：组合工具与结构化输出时的模型兼容性
• Agent 审批
• askUserTool 参考
• submitPlanTool 参考
• 任务工具参考
• TaskSignalProvider 参考
• 请求上下文