submitPlanTool

사용자 검토를 위해 구현 계획을 제출하는 기본 제공 Agent 독립적 Tool입니다. Agent는 마크다운 파일에 계획을 작성하고 파일 경로를 이 Tool에 전달합니다. Tool은 사용자가 계획을 승인하거나 거부할 때까지 실행을 일시 중단합니다.

Tool은 기본 Tool 일시 중단 프리미티브를 통해 일시 중단됩니다. 즉, suspend({ path })를 호출하면 Agent가 tool-call-suspended 이벤트를 내보냅니다. 호스트는 계획 파일을 읽어 사용자에게 표시한 다음 승인 또는 거부 결과로 실행을 재개합니다. Agent 실행 외부에서 실행되어 suspend를 사용할 수 없는 경우 Tool은 파일 경로가 포함된 읽기 쉬운 대체 문자열을 반환합니다.

사용예

Agent의 Tool 집합에 submitPlanTool을 추가하세요.

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

입력 스키마

Model은 다음 매개변수를 사용하여 이 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

계획이 거부되었을 때의 수정 지침입니다. Model이 계획을 수정하고 다시 제출할 수 있도록 전달됩니다.

path?:

string

기록 재생을 위해 그대로 반환되는 계획 파일 경로입니다.

title?:

string

기록 재생을 위해 그대로 반환되는 계획 제목입니다.

plan?:

string

기록 재생을 위해 그대로 반환되는 계획 본문입니다.

승인 행동

• 승인됨: Tool이 Model에 "Plan approved. Proceed with implementation following the approved plan."을 반환합니다.
• 피드백과 함께 거부됨: Tool이 피드백을 반환하고 Model에 계획을 수정하여 다시 제출하도록 요청합니다.
• 피드백 없이 거부됨: Tool이 Model에 수정하기 전에 사용자의 다음 메시지를 기다리도록 지시합니다. AgentController 내에서 사용하면 계획 승인 시 현재 모드에서 transitionsTo로 구성된 모드로 전환됩니다. transitionsTo가 구성되지 않은 경우 컨트롤러는 확인된 기본 모드로 전환됩니다. 자세한 내용은 모드를 참조하세요.