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

# API Agents

L’API Agents fournit des méthodes permettant d’interagir avec les Agents IA Mastra, notamment pour générer des réponses et diffuser des interactions en continu. Elle fournit également des méthodes pour gérer les Tools des Agents.

## Récupération de tous les Agents

Récupérez la liste de tous les Agents disponibles :

```typescript
const agents = await mastraClient.listAgents()
```

Renvoie un objet qui associe les ID des Agents à leurs configurations sérialisées.

## Utilisation d’un Agent précis

Récupérez une instance d’un Agent précis à partir de son ID :

```typescript
export const myAgent = new Agent({
  id: 'my-agent',
})
```

```typescript
const agent = mastraClient.getAgent('my-agent')
```

## Méthodes des Agents

### `details()`

Récupère des informations détaillées sur un Agent :

```typescript
const details = await agent.details()
```

### `generate()`

Génère une réponse de l’Agent :

```typescript
const response = await agent.generate(
  [
    {
      role: 'user',
      content: 'Hello, how are you?',
    },
  ],
  {
    memory: {
      thread: 'thread-abc', // Optional: Thread ID for conversation context
      resource: 'user-123', // Optional: Resource ID
    },
    structuredOutput: {}, // Optional: Structured Output configuration
  },
)
```

Vous pouvez également utiliser le format simplifié sous forme de chaîne avec les options de mémoire :

```typescript
const response = await agent.generate('Hello, how are you?', {
  memory: {
    thread: 'thread-1',
    resource: 'resource-1',
  },
})
```

### `stream()`

Diffuse les réponses de l’Agent en continu pour les interactions en temps réel :

```typescript
const response = await agent.stream('Tell me a story')

// Process data stream with the processDataStream util
response.processDataStream({
  onChunk: async chunk => {
    console.log(chunk)
  },
})
```

Vous pouvez également utiliser le format simplifié sous forme de chaîne avec les options de mémoire :

```typescript
const response = await agent.stream('Tell me a story', {
  memory: {
    thread: 'thread-1',
    resource: 'resource-1',
  },
  clientTools: { colorChangeTool },
})

response.processDataStream({
  onChunk: async chunk => {
    if (chunk.type === 'text-delta') {
      console.log(chunk.payload.text)
    }
  },
})
```

Vous pouvez également lire directement le corps de la réponse :

```typescript
const reader = response.body.getReader()
while (true) {
  const { done, value } = await reader.read()
  if (done) break
  console.log(new TextDecoder().decode(value))
}
```

#### Format compatible avec l’AI SDK

Pour diffuser côté client des parties au format AI SDK depuis une réponse `agent.stream(...)`, encapsulez `response.processDataStream` dans un `ReadableStream<ChunkType>` et utilisez `toAISdkStream` :

```typescript
import { createUIMessageStream } from 'ai'
import { toAISdkStream } from '@mastra/ai-sdk'
import type { ChunkType, MastraModelOutput } from '@mastra/core/stream'

const response = await agent.stream('Tell me a story')

const chunkStream: ReadableStream<ChunkType> = new ReadableStream<ChunkType>({
  start(controller) {
    response
      .processDataStream({
        onChunk: async chunk => controller.enqueue(chunk as ChunkType),
      })
      .finally(() => controller.close())
  },
})

const uiMessageStream = createUIMessageStream({
  execute: async ({ writer }) => {
    for await (const part of toAISdkStream(chunkStream as unknown as MastraModelOutput, {
      from: 'agent',
    })) {
      writer.write(part)
    }
  },
})

for await (const part of uiMessageStream) {
  console.log(part)
}
```

### `sendMessage()`

Envoie une entrée rédigée par l’utilisateur à une exécution active de l’Agent ou à un thread de mémoire inactif. Utilisez cette méthode avec `subscribeToThread()` afin que le client puisse effectuer le rendu du flux réveillé par le message ou recevant celui-ci.

```typescript
const agent = mastraClient.getAgent('support-agent')

const result = await agent.sendMessage({
  message: {
    contents: 'Also consider the customer note I just added.',
    attributes: { sentFrom: 'web' },
  },
  resourceId: 'user-123',
  threadId: 'thread-abc',
})

console.log(result.runId)
```

`message` accepte une chaîne, un tableau de parties texte/fichier ou un objet contenant `contents`, `attributes`, `metadata` et `providerOptions`.

### `queueMessage()`

Place une entrée rédigée par l’utilisateur dans la file d’attente du prochain tour du thread. Si le thread est actif, Mastra démarre une nouvelle exécution après la fin de l’exécution actuelle. Si le thread est inactif, Mastra démarre immédiatement une exécution.

```typescript
await agent.queueMessage({
  message: 'Also check whether the tests need updates.',
  resourceId: 'user-123',
  threadId: 'thread-abc',
})
```

### `sendSignal()`

Envoie un signal de bas niveau à une exécution active de l’Agent ou à un thread de mémoire. Utilisez cette méthode pour le contexte généré par le système, comme les rappels réactifs ou le contexte en forme de notification qui ne nécessite pas de stockage dans une boîte de réception. Pour des enregistrements de notification durables, utilisez l’API côté serveur [`Agent.sendNotificationSignal()`](https://mastra.zisheng.pro/fr/reference/agents/agent). Pour les entrées rédigées par l’utilisateur, privilégiez `sendMessage()` ou `queueMessage()`.

```typescript
const agent = mastraClient.getAgent('support-agent')

const result = await agent.sendSignal({
  signal: {
    type: 'reactive',
    tagName: 'system-reminder',
    contents: 'Also consider the latest customer note.',
  },
  resourceId: 'user-123',
  threadId: 'thread-abc',
})

console.log(result.runId)
```

Utilisez `ifActive.behavior` et `ifIdle.behavior` pour déterminer si Mastra distribue, persiste ou ignore un signal, ou réveille un thread à partir de celui-ci :

```typescript
await agent.sendSignal({
  signal: { type: 'reactive', tagName: 'system-reminder', contents: 'Store this for later.' },
  resourceId: 'user-123',
  threadId: 'thread-abc',
  ifIdle: {
    behavior: 'persist',
  },
})
```

Transmettez `ifIdle.streamOptions` lorsque le flux de réveil d’un thread inactif nécessite des options telles que les paramètres du modèle, les Tools ou le contexte d’exécution :

```typescript
await agent.sendSignal({
  signal: { type: 'reactive', tagName: 'system-reminder', contents: 'Start from this signal.' },
  resourceId: 'user-123',
  threadId: 'thread-abc',
  ifIdle: {
    behavior: 'wake',
    streamOptions: {
      maxSteps: 3,
    },
  },
})
```

Renvoie `{ accepted: true, runId: string }`.

**signal** (`{ type: 'user' | 'reactive' | 'notification' | string; tagName?: string; contents: string | Array<TextPart | FilePart>; attributes?: Record<string, JSONValue>; metadata?: Record<string, unknown>; providerOptions?: ProviderMetadata }`): Charge utile du signal de bas niveau. Utilisez type pour la catégorie sémantique du signal et tagName pour le tag XML présenté au modèle. providerOptions est associé au tour de prompt obtenu et persisté dans le message de signal stocké.

**runId** (`string`): ID d’exécution à cibler directement.

**resourceId** (`string`): ID de ressource du thread de mémoire. À utiliser avec threadId pour les signaux ciblant un thread.

**threadId** (`string`): ID du thread à cibler. À utiliser avec resourceId pour les signaux ciblant un thread.

**ifActive.behavior** (`'deliver' | 'persist' | 'discard'`): Contrôle le comportement lorsque le thread cible est actif. Utilise par défaut deliver.

**ifActive.attributes** (`Record<string, string | number | boolean>`): Attributs fusionnés dans le signal lorsque Mastra l’accepte pendant que le thread cible est actif.

**ifIdle.behavior** (`'wake' | 'persist' | 'discard'`): Contrôle le comportement lorsque le thread cible est inactif. Utilise par défaut wake.

**ifIdle.streamOptions** (`Omit<AgentExecutionOptions, 'messages'>`): Options du flux qui démarre lorsque ifIdle.behavior vaut wake.

**ifIdle.attributes** (`Record<string, string | number | boolean>`): Attributs fusionnés dans le signal lorsque Mastra l’accepte pendant que le thread cible est inactif.

### `subscribeToThread()`

S’abonne aux chunks bruts du flux d’un thread de mémoire. Utilisez cette méthode pour effectuer le rendu de la sortie d’un thread susceptible d’être démarré ou poursuivi par `sendMessage()`, `queueMessage()`, `sendSignal()` ou par la distribution d’une notification côté serveur.

```typescript
const agent = mastraClient.getAgent('support-agent')

const subscription = await agent.subscribeToThread({
  resourceId: 'user-123',
  threadId: 'thread-abc',
})

await subscription.processDataStream({
  onChunk: chunk => {
    console.log(chunk)
  },
  reconnect: true,
})
```

`subscribeToThread()` renvoie la `Response` sous-jacente ainsi qu’un utilitaire `processDataStream()`. Cet utilitaire lit le flux d’abonnement jusqu’à la fermeture de la connexion ou l’abandon de la requête. Transmettez `reconnect: true` pour vous réabonner lorsque le transport se ferme ou qu’une demande de reconnexion échoue, par exemple après l’expiration du délai d’inactivité d’un proxy.

**resourceId** (`string`): ID de ressource du thread de mémoire.

**threadId** (`string`): ID du thread auquel s’abonner.

**processDataStream().reconnect** (`boolean | { maxRetries?: number; delayMs?: number }`): Reconnecte le flux d’abonnement après sa fermeture ou l’échec d’une demande de reconnexion. true réessaie indéfiniment avec un délai d’une seconde.

### `streamUntilIdle()`

Diffuse une réponse en continu et maintient le flux ouvert jusqu’à la fin de chaque [tâche en arrière-plan](https://mastra.zisheng.pro/fr/docs/long-running-agents/background-tasks) lancée pendant l’exécution. Le serveur revient dans la boucle agentique à la fin de chaque tâche afin que le LLM puisse réagir aux résultats au cours du même appel. Nécessite que les tâches en arrière-plan soient [activées sur l’instance Mastra](https://mastra.zisheng.pro/fr/reference/configuration) ainsi qu’un thread de mémoire ; sinon, l’appel utilise un simple `stream()`.

```typescript
const response = await agent.streamUntilIdle('Research solana for me', {
  memory: {
    thread: 'thread-1',
    resource: 'resource-1',
  },
  maxIdleMs: 5 * 60_000, //optional
})

response.processDataStream({
  onChunk: async chunk => {
    if (chunk.type === 'background-task-completed') {
      console.log('task complete:', chunk.payload.taskId)
    }
  },
})
```

### `resumeStreamUntilIdle()`

Reprend un flux d’Agent suspendu avec des données personnalisées et maintient le flux ouvert jusqu’à la fin de chaque [tâche en arrière-plan](https://mastra.zisheng.pro/fr/docs/long-running-agents/background-tasks) lancée pendant l’exécution. Utilisez cette méthode pour poursuivre l’exécution après un point de suspension, par exemple la suspension d’un Workflow au sein d’un Agent. Nécessite que les tâches en arrière-plan soient [activées sur l’instance Mastra](https://mastra.zisheng.pro/fr/reference/configuration) ainsi qu’un thread de mémoire ; sinon, l’appel utilise un simple `resumeStream()` :

```typescript
const response = await agent.resumeStreamUntilIdle(
  { approved: true, selectedOption: 'plan-b' },
  {
    memory: {
      thread: 'thread-1',
      resource: 'resource-1',
    },
    runId: 'run-123',
    toolCallId: 'tool-call-456', // optional
    maxIdleMs: 5 * 60_000, //optional
  },
)

await response.processDataStream({
  onChunk: chunk => {
    console.log(chunk)
  },
})
```

Le flux émet les mêmes types de chunks que `stream()`, auxquels s’ajoutent des chunks `background-task-*` pour les événements du cycle de vie des tâches. Consultez [`Agent.streamUntilIdle()`](https://mastra.zisheng.pro/fr/reference/streaming/agents/streamUntilIdle) pour l’API côté serveur complète et les [chunks des tâches en arrière-plan](https://mastra.zisheng.pro/fr/reference/streaming/ChunkType) pour connaître la structure des charges utiles.

### `getTool()`

Récupère des informations sur un Tool précis disponible pour l’Agent :

```typescript
const tool = await agent.getTool('tool-id')
```

### `executeTool()`

Exécute un Tool précis pour l’Agent :

```typescript
const result = await agent.executeTool('tool-id', {
  data: { input: 'value' },
})
```

### `network()`

Diffuse les réponses d’un réseau d’Agents pour les interactions multi-Agents :

```typescript
const response = await agent.network('Research this topic and write a summary')

response.processDataStream({
  onChunk: async chunk => {
    console.log(chunk)
  },
})
```

### `listSuspendedRuns()`

Répertorie depuis le stockage les exécutions suspendues de l’Agent : celles qui attendent l’approbation d’un appel de Tool ou la reprise d’un Tool suspendu. La découverte s’appuie sur le stockage ; elle fonctionne donc après le redémarrage du serveur et sur plusieurs instances de serveur. Transmettez le `runId` renvoyé à `approveToolCall()`, `declineToolCall()` ou `resumeStream()`.

```typescript
const { runs, total } = await agent.listSuspendedRuns({
  threadId: 'thread-456',
  resourceId: 'user-123',
})

if (runs[0]) {
  console.log(runs[0].toolCalls) // [{ toolCallId, toolName, args, requiresApproval }]
  await agent.approveToolCall({
    runId: runs[0].runId,
    toolCallId: runs[0].toolCalls[0].toolCallId,
  })
}
```

Accepte des filtres facultatifs (`threadId`, `resourceId`, `fromDate`, `toDate`) et des paramètres de pagination (`perPage`, `page`). Renvoie `{ runs, total }`, où `total` correspond au nombre d’exécutions correspondantes avant pagination. Consultez [`Agent.listSuspendedRuns()`](https://mastra.zisheng.pro/fr/reference/agents/listSuspendedRuns) pour en savoir plus sur la structure des exécutions renvoyées.

### `approveToolCall()`

Approuve un appel de Tool en attente et renvoie un flux de continuation. Utilisez cette méthode lorsque vous effectuez le rendu des chunks repris depuis la réponse d’approbation.

```typescript
const response = await agent.approveToolCall({
  runId: 'run-123',
  toolCallId: 'tool-call-456',
})

response.processDataStream({
  onChunk: async chunk => {
    console.log(chunk)
  },
})
```

### `sendToolApproval()`

Approuve ou refuse un appel de Tool en attente pour un thread auquel le client est abonné. Utilisez cette méthode avec `subscribeToThread()` lorsque les chunks repris doivent parvenir par l’abonnement existant au thread plutôt que par un flux de continuation distinct.

```typescript
const result = await agent.sendToolApproval({
  resourceId: 'user-123',
  threadId: 'thread-456',
  toolCallId: 'tool-call-456',
  approved: true,
})

console.log(result.accepted)
```

Renvoie `{ accepted: true, runId: string, toolCallId?: string }`.

### `declineToolCall()`

Refuse un appel de Tool en attente et renvoie un flux de continuation. Utilisez cette méthode lorsque vous effectuez le rendu des chunks repris depuis la réponse de refus.

```typescript
const response = await agent.declineToolCall({
  runId: 'run-123',
  toolCallId: 'tool-call-456',
})

response.processDataStream({
  onChunk: async chunk => {
    console.log(chunk)
  },
})
```

### `resumeStream()`

Reprend un flux d’Agent suspendu avec des données personnalisées. Utilisez cette méthode pour poursuivre l’exécution après un point de suspension, par exemple la suspension d’un Workflow au sein d’un Agent :

```typescript
const response = await agent.resumeStream(
  { approved: true, selectedOption: 'plan-b' },
  {
    runId: 'run-123',
    toolCallId: 'tool-call-456', // optional
  },
)

await response.processDataStream({
  onChunk: chunk => {
    console.log(chunk)
  },
})
```

### `approveToolCallGenerate()`

Approuve un appel de Tool en attente lors de l’utilisation de `generate()` (sans streaming). Renvoie la réponse complète :

```typescript
const output = await agent.generate('Find user John', {
  requireToolApproval: true,
})

if (output.finishReason === 'suspended') {
  const result = await agent.approveToolCallGenerate({
    runId: output.runId,
    toolCallId: output.suspendPayload.toolCallId,
  })

  console.log(result.text)
}
```

### `declineToolCallGenerate()`

Refuse un appel de Tool en attente lors de l’utilisation de `generate()` (sans streaming). Renvoie la réponse complète :

```typescript
const output = await agent.generate('Find user John', {
  requireToolApproval: true,
})

if (output.finishReason === 'suspended') {
  const result = await agent.declineToolCallGenerate({
    runId: output.runId,
    toolCallId: output.suspendPayload.toolCallId,
  })

  console.log(result.text)
}
```

## Planifications des Agents

Utilisez les méthodes de planification du SDK client pour gérer les planifications persistées des Agents au moyen des routes `/api/schedules`. Pour découvrir les concepts et des exemples côté serveur, consultez [Schedules](https://mastra.zisheng.pro/fr/docs/long-running-agents/schedules) et la [référence de `mastra.schedules`](https://mastra.zisheng.pro/fr/reference/schedules/overview).

### `createSchedule()`

Crée une planification d’Agent en transmettant `agentId`.

```typescript
const schedule = await mastraClient.createSchedule({
  agentId: 'pinger',
  cron: '0 * * * *',
  prompt: 'Give me a status update.',
})
```

### `listSchedules()`

Répertorie les planifications des Agents. Filtrez-les au moyen de champs tels que `agentId`, `threadId`, `resourceId`, `name` ou `status`.

```typescript
const schedules = await mastraClient.listSchedules({
  agentId: 'pinger',
  status: 'active',
})
```

### `getSchedule()`

Récupère une planification d’Agent précise à partir de son ID.

```typescript
const schedule = await mastraClient.getSchedule('agent_pinger')
```

### `updateSchedule()`

Met à jour une planification d’Agent. Les planifications des Agents peuvent modifier des champs tels que `cron`, `timezone`, `prompt`, `name`, les options de distribution des signaux, les métadonnées et `status`.

```typescript
const updated = await mastraClient.updateSchedule('agent_pinger', {
  cron: '*/30 * * * *',
  prompt: 'Give me a status update every 30 minutes.',
})
```

### `deleteSchedule()`

Supprime une planification d’Agent.

```typescript
await mastraClient.deleteSchedule('agent_pinger')
```

### `runSchedule()`

Déclenche immédiatement et une seule fois une planification d’Agent sans modifier sa cadence cron.

```typescript
const run = await mastraClient.runSchedule('agent_pinger')
```

### `pauseSchedule()`

Suspend une planification d’Agent afin que le planificateur cesse de la déclencher. Renvoie la planification mise à jour.

```typescript
await mastraClient.pauseSchedule('agent_pinger')
```

### `resumeSchedule()`

Reprend une planification d’Agent suspendue. La prochaine heure de déclenchement est recalculée à partir de l’heure actuelle ; une planification suspendue pendant une longue période ne déclenche donc pas les occurrences en retard. Renvoie la planification mise à jour.

```typescript
await mastraClient.resumeSchedule('agent_pinger')
```

### `listScheduleTriggers()`

Répertorie l’historique des déclenchements d’une planification d’Agent, y compris le résumé joint de l’exécution pour chaque déclenchement.

```typescript
const { triggers } = await mastraClient.listScheduleTriggers('agent_pinger', {
  limit: 50,
})
```

## Tools clients

Les Tools côté client vous permettent d’exécuter des fonctions personnalisées sur le client lorsque l’Agent les demande.

```typescript
import { createTool } from '@mastra/client-js'
import { z } from 'zod'

const colorChangeTool = createTool({
  id: 'changeColor',
  description: 'Changes the background color',
  inputSchema: z.object({
    color: z.string(),
  }),
  execute: async inputData => {
    document.body.style.backgroundColor = inputData.color
    return { success: true }
  },
})

// Use with generate
const response = await agent.generate('Change the background to blue', {
  clientTools: { colorChangeTool },
})

// Use with stream
const response = await agent.stream('Tell me a story', {
  memory: {
    thread: 'thread-1',
    resource: 'resource-1',
  },
  clientTools: { colorChangeTool },
})

response.processDataStream({
  onChunk: async chunk => {
    if (chunk.type === 'text-delta') {
      console.log(chunk.payload.text)
    } else if (chunk.type === 'tool-call') {
      console.log(
        `calling tool ${chunk.payload.toolName} with args ${JSON.stringify(
          chunk.payload.args,
          null,
          2,
        )}`,
      )
    }
  },
})
```

### Mise en forme de la sortie d’un Tool client pour le modèle

Les Tools clients prennent en charge `toModelOutput` afin de contrôler ce que reçoit le modèle, notamment le contenu multimodal tel que les images. Comme les Tools clients s’exécutent localement, le mappage s’exécute également sur le client après la fin d’`execute`. La sortie transformée est renvoyée au serveur avec le résultat brut ; celui-ci reste ainsi disponible pour le stockage et la logique applicative.

```typescript
const screenshotTool = createTool({
  id: 'takeScreenshot',
  description: 'Takes a screenshot of the current page',
  inputSchema: z.object({}),
  execute: async () => {
    const base64 = await captureScreenshot()
    return { ok: true, data: base64 }
  },
  toModelOutput: output => ({
    type: 'content',
    value: [{ type: 'media', data: output.data, mediaType: 'image/jpeg' }],
  }),
})
```

### Tracing des Tools clients

Lorsque `@mastra/observability` est installé et configuré sur le serveur, un Tool côté client enregistre un Span `CLIENT_TOOL_CALL` comme enfant du Span `AGENT_RUN` actuel. Le serveur crée ce Span lorsque le modèle émet l’appel du Tool client et injecte un transporteur de Trace W3C dans le chunk d’appel de Tool sortant. Il termine le Span dès que les arguments du Tool sont disponibles. Sans observabilité configurée côté serveur, le Tracing des Tools clients n’effectue aucune opération.

Le SDK client mesure également la durée réelle de la fonction `execute` de chaque Tool client et la renvoie au serveur, où elle est émise comme métrique `mastra_tool_duration_ms` avec `toolType: "client"`.

Pour enrichir la télémétrie depuis la fonction `execute` de votre Tool, utilisez l’utilitaire `observe` du contexte d’exécution afin d’ajouter des Spans enfants et des logs structurés :

```typescript
import { createTool } from '@mastra/client-js'
import { z } from 'zod'

const fetchUserTool = createTool({
  id: 'fetchUser',
  description: 'Fetches the current user profile',
  inputSchema: z.object({ userId: z.string() }),
  execute: async ({ userId }, { observe }) => {
    observe.log('info', 'fetching user', { userId })
    const user = await observe.span('http GET /users', async () => {
      const res = await fetch(`/api/users/${userId}`)
      return res.json()
    })
    return user
  },
})
```

`observe` est toujours disponible : lorsqu’aucun contexte de Tracing n’est actif, par exemple lors d’une exécution en dehors d’un Agent tracé, `span` exécute directement la fonction et `log` n’effectue aucune opération. Aucun contrôle de valeur null n’est nécessaire.

Le SDK sérialise au format OTLP/JSON tout ce que le collecteur a mis en mémoire tampon et le renvoie dans le corps de la requête suivante. Le package `@mastra/observability` du serveur vérifie que les Spans appartiennent à la bonne Trace afin d’empêcher toute injection entre Traces, puis transmet chaque Span et log au même bus d’observabilité que celui utilisé par la télémétrie côté serveur. Vos exportateurs existants les récupèrent automatiquement une fois l’observabilité configurée.

## Agents stockés

Les Agents stockés sont des configurations d’Agent conservées dans une base de données, qui peuvent être créées, mises à jour et supprimées à l’exécution. Ils référencent des primitives (Tools, Workflows, autres Agents, Scorers) par clé ; celles-ci sont résolues depuis le registre Mastra lors de l’instanciation de l’Agent. La mémoire est configurée en ligne sous la forme d’un objet `SerializedMemoryConfig` avec des options telles que `lastMessages` et `semanticRecall`.

### `listStoredAgents()`

Récupère une liste paginée de tous les Agents stockés :

```typescript
const result = await mastraClient.listStoredAgents()
console.log(result.agents) // Array of stored agents
console.log(result.total) // Total count
```

Avec pagination et tri :

```typescript
const result = await mastraClient.listStoredAgents({
  page: 0,
  perPage: 20,
  orderBy: {
    field: 'createdAt',
    direction: 'DESC',
  },
})
```

### `createStoredAgent()`

Crée un nouvel Agent stocké :

```typescript
const agent = await mastraClient.createStoredAgent({
  id: 'my-agent',
  name: 'My Assistant',
  instructions: 'You are a helpful assistant.',
  model: {
    provider: 'openai',
    name: 'gpt-5.4',
  },
})
```

Par défaut, `createStoredAgent()` publie immédiatement la version initiale. Définissez `autoPublish` sur `false` pour créer un brouillon non publié que vous pourrez examiner avant d’appeler [`activateVersion()`](#activateversion) :

```typescript
const draft = await mastraClient.createStoredAgent({
  id: 'draft-agent',
  name: 'Draft Assistant',
  instructions: 'You are a helpful assistant.',
  model: {
    provider: 'openai',
    name: 'gpt-5',
  },
  autoPublish: false,
})
```

Les Editors configurés avec la source `code` publient toujours la version initiale, car l’enregistrement écrit la configuration de l’Agent dans le système de fichiers.

Avec toutes les options :

```typescript
const agent = await mastraClient.createStoredAgent({
  id: 'full-agent',
  name: 'Full Agent',
  description: 'A fully configured agent',
  instructions: 'You are a helpful assistant.',
  model: {
    provider: 'openai',
    name: 'gpt-5.4',
  },
  tools: { calculator: {}, weather: {} },
  workflows: { 'data-processing': {} },
  agents: { 'subagent-1': {} },
  memory: {
    options: {
      lastMessages: 20,
      semanticRecall: false,
    },
  },
  scorers: {
    'quality-scorer': {
      sampling: { type: 'ratio', rate: 0.1 },
    },
  },
  defaultOptions: {
    maxSteps: 10,
  },
  metadata: {
    version: '1.0',
    team: 'engineering',
  },
})
```

### `getStoredAgent()`

Récupère une instance d’un Agent stocké précis :

```typescript
const storedAgent = mastraClient.getStoredAgent('my-agent')
```

## Méthodes des Agents stockés

### `details()`

Récupère la configuration de l’Agent stocké :

```typescript
const details = await storedAgent.details()
console.log(details.name)
console.log(details.instructions)
console.log(details.model)
```

### `update()`

Met à jour certains champs d’un Agent stocké. Tous les champs sont facultatifs :

```typescript
const updated = await storedAgent.update({
  name: 'Updated Agent Name',
  instructions: 'New instructions for the agent.',
})
```

```typescript
// Update just the tools
await storedAgent.update({
  tools: { 'new-tool-1': {}, 'new-tool-2': {} },
})

// Update metadata
await storedAgent.update({
  metadata: {
    version: '2.0',
    lastModifiedBy: 'admin',
  },
})
```

### `delete()`

Supprime un Agent stocké :

```typescript
const result = await storedAgent.delete()
console.log(result.success) // true
```

## Gestion des versions

Les instances `Agent` (définies dans le code) et `StoredAgent` disposent toutes deux de méthodes de gestion des versions de configuration. Consultez la section [Gestion des versions dans Editor](https://mastra.zisheng.pro/fr/docs/editor/overview) pour découvrir le cycle de vie et le comportement de sélection.

### Récupération d’un Agent dans une version précise

Transmettez un identifiant de version lors de la récupération d’un Agent :

```typescript
// Load the published version (default)
const agent = mastraClient.getAgent('support-agent')

// Load the latest draft
const draftAgent = mastraClient.getAgent('support-agent', { status: 'draft' })

// Load a specific version
const versionedAgent = mastraClient.getAgent('support-agent', { versionId: 'abc-123' })
```

Pour les Agents stockés, transmettez une option de statut à `details()` :

```typescript
const storedAgent = mastraClient.getStoredAgent('my-agent')
const draft = await storedAgent.details(undefined, { status: 'draft' })
```

### `listVersions()`

Répertorie toutes les versions d’un Agent :

```typescript
const versions = await agent.listVersions()
console.log(versions.items) // Array of version snapshots
console.log(versions.total)
```

Avec pagination et tri :

```typescript
const versions = await agent.listVersions({
  page: 0,
  perPage: 10,
  orderBy: {
    field: 'createdAt',
    direction: 'DESC',
  },
})
```

### `createVersion()`

Crée un nouvel instantané de version :

```typescript
const version = await agent.createVersion({
  changeMessage: 'Updated tone to be more friendly',
})
```

### `getVersion()`

Récupère une version précise à partir de son ID :

```typescript
const version = await agent.getVersion('version-123')
console.log(version.versionNumber)
console.log(version.changedFields)
console.log(version.createdAt)
```

### `activateVersion()`

Définit une version comme version publiée active :

```typescript
await agent.activateVersion('version-123')
```

### `restoreVersion()`

Restaure une version antérieure en créant une nouvelle version avec la même configuration :

```typescript
await agent.restoreVersion('version-456')
```

### `deleteVersion()`

Supprime une version :

```typescript
await agent.deleteVersion('version-789')
```

### `compareVersions()`

Compare deux versions et renvoie leurs différences :

```typescript
const diff = await agent.compareVersions('version-123', 'version-456')
console.log(diff.changes) // Fields that changed between versions
```

### SDK React

Dans le SDK React, transmettez un `agentVersionId` au moyen de `requestContext` lorsque vous utilisez le hook `useChat` :

```typescript
import { useChat } from '@mastra/react'

function Chat() {
  const { messages, input, handleInputChange, handleSubmit } = useChat({
    agentId: 'support-agent',
    requestContext: {
      agentVersionId: 'abc-123',
    },
  })

  // ... render chat UI
}
```