Goals

Added in: @mastra/core@1.42.0

beta

La fonctionnalité Goals est au stade bêta et peut subir des changements cassants dans les versions mineures jusqu’à la fin de ce statut bêta.

Un goal est un objectif durable, limité à un thread : une instruction permanente vers laquelle l’agent continue de travailler au fil des itérations de boucle, jusqu’à ce qu’un modèle juge décide qu’il est atteint ou que le budget d’exécution soit épuisé.

L’objectif est conservé dans l’état du thread ; il survit donc aux rechargements et est évalué dans la boucle, même lorsqu’un nouveau message arrive au milieu d’un tour déjà en cours.

Goals s’appuie sur les mêmes mécanismes que isTaskComplete : un LLM utilisé comme juge évalue la sortie de l’agent à chaque itération et contrôle la boucle. La différence est qu’un goal est durable, car stocké dans l’état du thread plutôt que transmis à chaque appel, et qu’il est défini et mis à jour par les méthodes d’Agent plutôt que par des options propres à stream().

Quand utiliser Goals

Utilisez un goal lorsque vous souhaitez qu’un agent continue de travailler sur un objectif unique à travers de nombreuses itérations et de nombreux messages, sans redonner les critères de réussite à chaque appel :

• Un objectif permanent que l’agent doit poursuivre jusqu’à ce qu’un juge le déclare terminé.
• Un travail qui doit se poursuivre malgré des messages reçus en cours d’exécution, car un message transmis à une exécution active reste évalué par rapport au goal.
• Un objectif qui doit persister malgré les rechargements de thread ou les redémarrages de processus.

Pour un contrôle ponctuel d’achèvement dans un seul appel à stream(), utilisez plutôt isTaskComplete.

Démarrage rapide

Goals nécessite un backend de stockage configuré et un thread soutenu par la mémoire. Ajoutez une configuration goal à l’agent ; un modèle juge est requis pour que le goal puisse agir, puis définissez un objectif pour un thread :

src/mastra/agents/worker.ts

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

const worker = new Agent({
  id: 'worker',
  name: 'worker',
  instructions: 'You complete software tasks end to end.',
  model: 'openai/gpt-5.6-sol',
  memory,
  goal: {
    judge: 'openai/gpt-5-mini',
    maxRuns: 50,
  },
})

// Set the durable objective for a thread.
await worker.setObjective('Add and test a /health endpoint', {
  threadId,
  resourceId,
})

// The objective is judged each iteration until it's complete or maxRuns is hit.
const stream = await worker.stream('Start working on the goal', {
  memory: { thread: threadId, resource: resourceId },
})

La configuration goal enregistre automatiquement la projection de signal d’état ; le modèle voit donc toujours l’objectif actuel sous la forme <current-objective> dans son contexte, sans configuration supplémentaire.

Fonctionnement de l’étape de goal

Une étape de goal s’exécute dans la boucle d’exécution agentique, juste après isTaskComplete. Sur une véritable réponse candidate, elle évalue la conversation par rapport à l’objectif et contrôle la boucle :

• Non atteint, budget restant → la boucle continue. Un retour par évaluation est injecté afin que l’agent itère.
• Atteint → la boucle s’arrête et l’objectif est marqué done.
• Budget épuisé (runsUsed >= maxRuns) → la boucle s’arrête et l’objectif est marqué paused. Augmentez maxRuns, puis reprenez l’objectif pour continuer.

Cette étape est sans effet pour les itérations de tâche d’arrière-plan, au milieu d’une boucle de tool et limitées à la mémoire de travail, avec le même contrôle que isTaskComplete.

Le modèle juge est le commutateur d’activation. Si aucun juge n’est résolu, ni par remplacement propre à l’objectif ni par goal.judge de l’agent, l’étape de goal n’effectue aucune évaluation, ne consomme aucun budget et n’émet aucun chunk goal.

Les paramètres effectifs sont résolus selon cet ordre : valeur de l’enregistrement propre à l’objectif → configuration goal de l’agent → valeur intégrée par défaut, soit maxRuns 50 et un prompt de juge par défaut.

Par défaut, l’étape utilise un scorer intégré de type LLM-as-judge, qui renvoie 1 lorsque l’objectif est atteint et 0 dans le cas contraire. Fournissez votre propre scorer avec goal.scorer pour personnaliser le jugement.

src/mastra/agents/worker.ts

const worker = new Agent({
  id: 'worker',
  name: 'worker',
  instructions: 'You complete software tasks end to end.',
  model: 'openai/gpt-5.6-sol',
  memory,
  goal: {
    // A resolver function lets you inject provider credentials and read the
    // current judge selection at runtime; returning `undefined` keeps the
    // goal step a no-op.
    judge: ({ requestContext }) => resolveJudgeModel(requestContext),
    maxRuns: 30,
    prompt: 'Only mark the goal complete when tests pass.',
  },
})

Chaque évaluation émet un chunk de stream goal typé (GoalEvaluationPayload : objective, iteration, maxRuns, passed, status, results, reason, duration, timedOut, maxRunsReached, suppressFeedback) afin qu’une interface puisse afficher la progression du goal en cours d’exécution.

Gérer l’objectif

Contrôlez l’objectif d’un thread avec les méthodes d’Agent. Elles sont toutes sans effet lorsque l’exécution n’est pas soutenue par la mémoire, car elles exigent un stockage et un threadId :

src/mastra/objective.ts

// Read the current objective record.
const record = await worker.getObjective({ threadId })

// Update options on the active objective (only provided fields are written;
// unset fields fall back to the agent's `goal` config).
await worker.updateObjectiveOptions({ threadId, maxRuns: 100 })

// Drop the objective.
await worker.clearObjective({ threadId })

Les enregistrements d’objectif incluent une valeur facultative activeDurationMs destinée aux interfaces qui affichent le temps de poursuite active. Mastra fait progresser cette valeur pendant qu’un agent s’exécute vers un objectif actif et la sauvegarde lorsque l’exécution se termine ou attend l’approbation d’un tool. Les valeurs manquantes représentent zéro, et la durée mesure l’exécution de l’agent plutôt que l’âge réel du goal.

Les valeurs propres à l’objectif écrites par setObjective / updateObjectiveOptions ont priorité sur la configuration goal de l’agent, et cette priorité est mémorisée dans l’état du thread. Consultez GoalEvaluationPayload dans la référence ChunkType pour la forme complète du chunk de goal.

Pages connexes

• Agents superviseurs : isTaskComplete et le rubric scorer
• Providers de signal : comment l’objectif est projeté dans le contexte
• Stockage de mémoire : le backend de stockage requis par Goals