submitPlanTool

这是一个内置且与 Agent 无关的 Tool，用于提交实施计划供用户审查。Agent 将计划写入 Markdown 文件，并把文件路径传给此 Tool。该 Tool 会暂停运行，直至用户批准或拒绝计划。

该 Tool 通过原生的 Tool 暂停机制实现暂停：它会调用 suspend({ path })，使 Agent 发出 tool-call-suspended 事件。宿主读取计划文件并将其呈现给用户，然后根据批准或拒绝结果恢复运行。

在 Agent 运行之外执行时（没有可用的 suspend），该 Tool 会返回一个包含文件路径的易读回退字符串。

使用示例

将 submitPlanTool 添加到 Agent 的 Tool 集：

src/mastra/agents/index.ts

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

const agent = new Agent({
  id: 'planner',
  name: 'Planner',
  instructions: 'Write a plan to a file before starting work, then submit it for approval.',
  model,
  tools: { submitPlanTool },
})

处理暂停并恢复运行：

src/run.ts

import fs from 'node:fs'

const stream = await agent.stream('Refactor the auth module')

for await (const chunk of stream.fullStream) {
  if (chunk.type === 'tool-call-suspended' && chunk.payload.toolName === 'submit_plan') {
    const { path } = chunk.payload.suspendPayload
    const plan = fs.readFileSync(path, 'utf-8')
    console.log(plan)

    // Approve:
    const resumed = await agent.resumeStream({ action: 'approved' }, { runId: stream.runId })
    for await (const c of resumed.textStream) process.stdout.write(c)
  }
}

要拒绝计划并提供反馈：

await agent.resumeStream(
  { action: 'rejected', feedback: 'Add error handling steps' },
  { runId: stream.runId },
)

输入 Schema

模型调用此 Tool 时使用以下参数：

path:

string

磁盘上的计划 Markdown 文件路径（例如 '.mastracode/plans/add-dark-mode.md'）。

暂停载荷

tool-call-suspended 事件携带一个 suspendPayload：

path:

string

Agent 写入的计划文件路径。

title?:

string

计划标题，由宿主读取文件后填充。

plan?:

string

计划正文，由宿主读取文件后填充。

恢复数据

向 agent.resumeStream() 传入一个对象：

action:

'approved' | 'rejected'

用户批准还是拒绝了计划。

feedback?:

string

计划被拒绝时的修改指示。该内容会提供给模型，使其能够修改并重新提交。

path?:

string

计划文件路径，回传该值以便重放历史记录。

title?:

string

计划标题，回传该值以便重放历史记录。

plan?:

string

计划正文，回传该值以便重放历史记录。

审批行为

• 已批准： Tool 向模型返回 "Plan approved. Proceed with implementation following the approved plan."。
• 拒绝并提供反馈： Tool 返回反馈，并要求模型修改计划后再次提交。
• 拒绝但未提供反馈： Tool 会告诉模型等待用户的下一条消息，然后再修改计划。

在 AgentController 中使用时，计划获批会从当前模式切换到 transitionsTo 配置的模式。未配置 transitionsTo 时，控制器会切换到解析出的默认模式。详情请参阅模式。