submitPlanTool

Tool intégré indépendant de l’Agent, qui soumet un plan d’implémentation à l’examen de l’utilisateur. L’Agent écrit un plan dans un fichier Markdown et transmet son chemin à ce Tool. Le Tool suspend l’exécution jusqu’à ce que l’utilisateur approuve ou rejette le plan.

Le Tool se met en pause au moyen de la primitive native de suspension des Tools : il appelle suspend({ path }), ce qui amène l’Agent à émettre un événement tool-call-suspended. L’hôte lit le fichier de plan et le présente à l’utilisateur. Il reprend ensuite l’exécution avec une approbation ou un rejet.

Lorsqu’il est exécuté en dehors de l’exécution d’un Agent, sans suspend disponible, le Tool renvoie une chaîne de repli lisible contenant le chemin du fichier.

Exemple d’utilisation

Ajoutez submitPlanTool à l’ensemble de Tools d’un Agent :

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

Gérez la suspension et la reprise :

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

Pour rejeter le plan en fournissant un commentaire :

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

Schéma d’entrée

Le modèle appelle ce Tool avec les paramètres suivants :

path:

string

Chemin du fichier Markdown du plan sur le disque, par exemple '.mastracode/plans/add-dark-mode.md'.

Payload de suspension

L’événement tool-call-suspended transporte un suspendPayload :

path:

string

Chemin du fichier de plan écrit par l’Agent.

title?:

string

Titre du plan, renseigné par l’hôte après la lecture du fichier.

plan?:

string

Corps du plan, renseigné par l’hôte après la lecture du fichier.

Données de reprise

Transmettez un objet à agent.resumeStream() :

action:

'approved' | 'rejected'

Indique si l’utilisateur a approuvé ou rejeté le plan.

feedback?:

string

Instructions de révision lorsque le plan est rejeté. Transmises au modèle pour qu’il puisse réviser et soumettre à nouveau le plan.

path?:

string

Chemin du fichier de plan, renvoyé pour la relecture de l’historique.

title?:

string

Titre du plan, renvoyé pour la relecture de l’historique.

plan?:

string

Corps du plan, renvoyé pour la relecture de l’historique.

Comportement de l’approbation

• Approuvé : le Tool renvoie "Plan approved. Proceed with implementation following the approved plan." au modèle.
• Rejeté avec un commentaire : le Tool renvoie le commentaire et demande au modèle de réviser le plan, puis de le soumettre à nouveau.
• Rejeté sans commentaire : le Tool indique au modèle d’attendre le prochain message de l’utilisateur avant de réviser le plan.

Lorsqu’il est utilisé dans un AgentController, l’approbation du plan remplace le mode actuel par celui configuré avec transitionsTo. Lorsqu’aucun transitionsTo n’est configuré, le contrôleur passe à son mode par défaut résolu. Consultez les modes pour plus de détails.