> Discover all available pages from the documentation index: https://mastra.zisheng.pro/fr/llms.txt

# 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`](https://mastra.zisheng.pro/fr/docs/capabilities/subagents) : 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`](https://mastra.zisheng.pro/fr/docs/capabilities/subagents).

## Démarrage rapide

Goals nécessite un backend de [stockage](https://mastra.zisheng.pro/fr/docs/storage/overview) 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 :

```typescript
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.

```typescript
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` :

```typescript
// 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](https://mastra.zisheng.pro/fr/reference/streaming/ChunkType) pour la forme complète du chunk de goal.

## Pages connexes

- [Agents superviseurs](https://mastra.zisheng.pro/fr/docs/capabilities/subagents) : `isTaskComplete` et le rubric scorer
- [Providers de signal](https://mastra.zisheng.pro/fr/docs/long-running-agents/signal-providers) : comment l’objectif est projeté dans le contexte
- [Stockage de mémoire](https://mastra.zisheng.pro/fr/docs/storage/overview) : le backend de stockage requis par Goals