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 },
)

輸入結構

模型會使用以下參數呼叫此 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，控制器會切換至其解析後的預設模式。詳情請參閱模式。