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'）。

暫停 payload

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，controller 會切換到解析後的預設模式。詳情請參閱模式。