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

# AgentController

> **Beta:** La fonctionnalité `AgentController` est en phase bêta et peut subir des changements incompatibles dans les versions mineures jusqu’à sa sortie de la phase bêta.

La classe `AgentController` est un hôte partagé pour une ou plusieurs instances de [`Session`](https://mastra.zisheng.pro/fr/reference/agent-controller/session). Initialisez le contrôleur, créez une session, puis utilisez les API `session.*` pour gérer l’état de la conversation et contrôler l’exécution.

Pour une introduction guidée, consultez la [présentation d’AgentController](https://mastra.zisheng.pro/fr/docs/harness/agent-controller).

## Exemple d’utilisation

L’exemple suivant initialise un contrôleur et crée une session. Il s’abonne aux événements de la session avant d’envoyer un message.

```typescript
import { Agent } from '@mastra/core/agent'
import { AgentController } from '@mastra/core/agent-controller'
import { Workspace } from '@mastra/core/workspace'

const agent = new Agent({
  id: 'coding-agent',
  name: 'Coding agent',
  instructions: 'Help with software engineering tasks.',
  model: 'anthropic/claude-sonnet-4-6',
})

const controller = new AgentController({
  id: 'coding-controller',
  agent,
  workspace: new Workspace({ id: 'coding-workspace' }),
  modes: [{ id: 'build', name: 'Build', metadata: { default: true } }],
})

await controller.init()

const session = await controller.createSession({ resourceId: 'project-42' })
const unsubscribe = session.subscribe(event => {
  if (event.type === 'message_update') {
    console.log(event.message)
  }
})

await session.sendMessage({ content: 'Review the project structure.' })
unsubscribe()
```

## Paramètres du constructeur

**id** (`string`): Identifiant unique du contrôleur. Il sert également d’identifiant par défaut pour la session et la ressource.

**modes** (`AgentControllerMode[]`): Définitions des modes disponibles pour chaque session. Au moins un mode est requis.

**modes.id** (`string`): Identifiant unique du mode.

**modes.name** (`string`): Nom affiché.

**modes.defaultModelId** (`string`): Modèle sélectionné lorsqu’une session entre dans ce mode sans sélection enregistrée.

**modes.description** (`string`): Texte affiché dans les sélecteurs de mode.

**modes.instructions** (`string`): Instructions ajoutées au-dessus de celles de l’Agent sous-jacent pour ce mode.

**modes.transitionsTo** (`string`): Mode activé après une suspension submit\_plan approuvée.

**modes.availableTools** (`string[]`): Liste d’autorisation des noms d’outils exposés. Un tableau vide masque tous les outils dans ce mode.

**modes.metadata** (`Record<string, unknown>`): Métadonnées du mode transmises telles quelles. metadata.default: true désigne le mode par défaut.

**modes.tools** (`ToolsInput`): Outils du mode. Mutuellement exclusif avec additionalTools.

**modes.additionalTools** (`ToolsInput`): Outils ajoutés à ceux de l’Agent sous-jacent. Mutuellement exclusif avec tools.

**modes.agent** (`Agent`): Agent propre au mode, désormais obsolète. Utilisez le paramètre agent de premier niveau.

**modes.default** (`boolean`): Marqueur par défaut obsolète. Utilisez metadata.default ou defaultModeId.

**agent** (`Agent`): Agent sous-jacent partagé utilisé par les modes configurés.

**resourceId** (`string`): Identifiant de ressource par défaut pour les sessions et les threads. Sa valeur par défaut est id.

**storage** (`MastraCompositeStore`): Stockage utilisé pour les threads persistants, les messages, les paramètres et les données d’exécution reprenables.

**stateSchema** (`PublicSchema<TState, any>`): Schéma utilisé pour valider les mises à jour de session.state.

**initialState** (`Partial<TState>`): État initial fusionné avec les valeurs par défaut du schéma pour chaque nouvelle session.

**memory** (`DynamicArgument<MastraMemory>`): Instance de mémoire partagée avec les Agents sous-jacents qui ne définissent pas leur propre mémoire.

**defaultModeId** (`string`): Identifiant du mode par défaut. Il prévaut sur les métadonnées du mode.

**instructions** (`string`): Instructions du contrôleur combinées avec celles du mode actuel.

**tools** (`DynamicArgument<ToolsInput | undefined>`): Outils partagés par les exécutions du contrôleur et accessibles aux sous-agents configurés.

**workspace** (`DynamicArgument<Workspace | undefined>`): Workspace statique ou fabrique de Workspace par session. Une session doit résoudre un Workspace valide.

**browser** (`DynamicArgument<MastraBrowser | undefined>`): Navigateur statique ou fabrique de navigateurs par session.

**channels** (`AgentControllerChannelsConfig`): Configuration des canaux de chat utilisée pour acheminer les threads des canaux vers les sessions du contrôleur.

**intervalHandlers** (`IntervalHandler[]`): Gestionnaires périodiques démarrés par init() et arrêtés par stopIntervals() ou destroy().

**idGenerator** (`() => string`): Générateur d’identifiants personnalisé pour les threads, les messages et les signaux.

**modelUseCountProvider** (`ModelUseCountProvider`): Renvoie les nombres d’utilisations des modèles servant à trier les modèles disponibles.

**modelUseCountTracker** (`ModelUseCountTracker`): Enregistre une sélection de modèle après session.model.switch().

**subagents** (`AgentControllerSubagent[]`): Types de sous-agents exposés par l’outil subagent intégré.

**subagents.id** (`string`): Identifiant unique du type de sous-agent.

**subagents.name** (`string`): Nom affiché.

**subagents.description** (`string`): Description utilisée par l’outil généré.

**subagents.instructions** (`DynamicArgument<AgentInstructions>`): Instructions du sous-agent.

**subagents.tools** (`ToolsInput`): Outils appartenant au sous-agent.

**subagents.allowedControllerTools** (`string[]`): ID des outils du contrôleur ajoutés aux outils du sous-agent.

**subagents.allowedWorkspaceTools** (`string[]`): Noms des outils du Workspace visibles par le sous-agent.

**subagents.defaultModelId** (`string`): Modèle par défaut du sous-agent.

**subagents.maxSteps** (`number`): Nombre maximal d’étapes d’exécution.

**subagents.stopWhen** (`LoopOptions["stopWhen"]`): Condition d’arrêt de la boucle.

**subagents.forked** (`boolean`): Indique si le sous-agent hérite par défaut d’un clone du thread parent.

**gateways** (`MastraModelGatewayInterface[]`): Passerelles de modèles personnalisées fusionnées avec les passerelles intégrées.

**omConfig** (`AgentControllerOMConfig`): Modèles et seuils par défaut de la mémoire observationnelle.

**disableBuiltinTools** (`BuiltinToolId[]`): Outils intégrés du contrôleur à exclure des exécutions.

**toolCategoryResolver** (`(toolName: string) => ToolCategory | null`): Associe les noms d’outils à des catégories d’autorisation.

**pubsub** (`PubSub`): Implémentation PubSub propagée aux Agents sous-jacents.

**threadLock** (`{ acquire: (threadId: string) => void | Promise<void>; release: (threadId: string) => void | Promise<void> }`): Implémentation du verrou utilisée pour coordonner la propriété des threads.

**observability** (`ObservabilityEntrypoint`): Configuration de l’observabilité pour une instance Mastra autonome du contrôleur.

## Propriétés

**id** (`string`): Identifiant du contrôleur transmis au constructeur.

## Méthodes

### Sessions

#### `createSession(options)`

Obtient ou crée la session active enregistrée pour la paire `(resourceId, scope)`. Appelez `init()` avant cette méthode.

```typescript
const session = await controller.createSession({
  resourceId: 'project-42',
  scope: 'editor-window-1',
  threadId: 'thread-7',
})
```

Les mêmes `resourceId` et `scope` renvoient la même instance de `Session`. Un scope différent crée une session isolée pour la même ressource. Lorsque `threadId` est fourni, la méthode bascule une session mise en cache vers ce thread ou crée le thread s’il n’existe pas.

**resourceId** (`string`): Ressource mémoire et clé du registre des sessions actives. Sa valeur par défaut est le resourceId configuré ou l’id du contrôleur.

**scope** (`string`): Espace de noms facultatif du registre qui autorise plusieurs sessions actives pour une même ressource.

**threadId** (`string`): Thread précis à associer. Les threads manquants sont créés avec cet identifiant.

**id** (`string`): Identifiant stable de la session. Sa valeur par défaut est l’id du contrôleur.

**ownerId** (`string`): Identifiant stable du propriétaire de la session. Sa valeur par défaut est id.

**tags** (`Record<string, string>`): Tags copiés dans les threads créés par la session.

**workspace** (`Workspace`): Remplacement du Workspace pour cette session.

**browser** (`MastraBrowser`): Remplacement du navigateur pour cette session.

**requestContext** (`RequestContext`): Contexte utilisé pour résoudre les fabriques dynamiques de Workspace et de navigateurs.

Renvoie : `Promise<Session<TState>>`

#### `getSessionByResource(resourceId, scope?)`

Renvoie la session active enregistrée pour une ressource et, facultativement, un scope.

```typescript
const session = await controller.getSessionByResource('project-42', 'editor-window-1')
```

Renvoie : `Promise<Session<TState> | undefined>`

#### `setResourceId(session, { resourceId })`

Déplace une session active vers une autre ressource et supprime son association au thread actif.

```typescript
await controller.setResourceId(session, { resourceId: 'project-43' })
```

#### `getKnownResourceIds(session)`

Répertorie les identifiants de ressources présents dans les threads stockés.

```typescript
const resourceIds = await controller.getKnownResourceIds(session)
```

Renvoie : `Promise<string[]>`

### Cycle de vie

#### `init()`

Initialise le stockage partagé, les services du Workspace et les gestionnaires périodiques configurés. Les appels répétés réutilisent la même promesse d’initialisation.

```typescript
await controller.init()
```

#### `destroy()`

Arrête les gestionnaires périodiques appartenant au contrôleur. Cette opération ne détruit pas les Sessions créées par le contrôleur.

```typescript
await controller.destroy()
```

### Modes et Agents

#### `listModes()`

Renvoie les définitions des modes configurés.

```typescript
const modes = controller.listModes()
```

Renvoie : `AgentControllerMode[]`

#### `getCurrentAgent(session)`

Renvoie l’Agent sous-jacent du mode actif de la session.

```typescript
const agent = controller.getCurrentAgent(session)
```

Renvoie : `Agent`

### Workspace et navigateur

#### `hasWorkspace()`

Indique si le contrôleur possède une configuration de Workspace statique, dynamique ou fondée sur un objet.

```typescript
if (controller.hasWorkspace()) {
  console.log('Workspace configured')
}
```

Renvoie : `boolean`

#### `isWorkspaceReady()`

Indique si le Workspace au niveau du contrôleur est prêt.

```typescript
const ready = controller.isWorkspaceReady()
```

Renvoie : `boolean`

#### `getWorkspace()`

Renvoie un Workspace statique du contrôleur. Les fabriques dynamiques de Workspace renvoient `undefined` jusqu’à leur résolution.

```typescript
const workspace = controller.getWorkspace()
```

Renvoie : `Workspace | undefined`

#### `resolveWorkspace({ session, requestContext? })`

Résout un Workspace dynamique pour une session et met le résultat en cache dans le contrôleur.

```typescript
const workspace = await controller.resolveWorkspace({ session, requestContext })
```

Renvoie : `Promise<Workspace | undefined>`

#### `setBrowser(browser)`

Remplace le navigateur du contrôleur et le propage aux Agents sous-jacents.

```typescript
controller.setBrowser(browser)
```

### Mastra et canaux

#### `getMastra()`

Renvoie l’instance Mastra parente ou l’instance interne créée par `init()`.

```typescript
const mastra = controller.getMastra()
```

Renvoie : `Mastra | undefined`

#### `getChannels()`

Renvoie l’intégration configurée des canaux de chat.

```typescript
const channels = controller.getChannels()
```

Renvoie : `AgentControllerChannels | null`

### Modèles

#### `getCurrentModelAuthStatus(session)`

Renvoie l’état d’authentification du modèle sélectionné pour la session.

```typescript
const status = await controller.getCurrentModelAuthStatus(session)
```

Renvoie : `Promise<ModelAuthStatus>`

#### `listAvailableModels()`

Répertorie les modèles issus des passerelles configurées et intégrées. Les résultats sont brièvement mis en cache et triés selon les données d’utilisation lorsque `modelUseCountProvider` est configuré.

```typescript
const models = await controller.listAvailableModels()
```

Renvoie : `Promise<AvailableModel[]>`

#### `invalidateAvailableModelsCache()`

Vide le cache des modèles disponibles.

```typescript
controller.invalidateAvailableModelsCache()
```

### Mémoire observationnelle et autorisations

#### `loadOMProgress(session)`

Charge la progression stockée de la mémoire observationnelle pour le thread actif et émet un événement `om_status`.

```typescript
await controller.loadOMProgress(session)
```

#### `getObservationalMemoryRecord(session)`

Renvoie l’enregistrement de mémoire observationnelle du thread actif.

```typescript
const record = await controller.getObservationalMemoryRecord(session)
```

Renvoie : `Promise<ObservationalMemoryRecord | null>`

#### `getToolCategory({ toolName })`

Résout la catégorie d’autorisation d’un outil.

```typescript
const category = controller.getToolCategory({ toolName: 'execute_command' })
```

Renvoie : `ToolCategory | null`

### Intervalles

#### `registerInterval(handler)`

Démarre ou remplace un gestionnaire périodique.

```typescript
controller.registerInterval({
  id: 'refresh',
  intervalMs: 60_000,
  handler: async () => refreshData(),
})
```

#### `removeInterval({ id })`

Arrête un intervalle et exécute sa fonction de rappel d’arrêt facultative.

```typescript
await controller.removeInterval({ id: 'refresh' })
```

#### `stopIntervals()`

Arrête tous les intervalles et exécute leurs fonctions de rappel d’arrêt facultatives.

```typescript
await controller.stopIntervals()
```

## Voir aussi

- [Guide d’AgentController](https://mastra.zisheng.pro/fr/docs/harness/agent-controller)
- [Référence de Session](https://mastra.zisheng.pro/fr/reference/agent-controller/session)
- [Agents](https://mastra.zisheng.pro/fr/docs/agents/overview)
- [Workspace](https://mastra.zisheng.pro/fr/docs/workspace/overview)
- [Canaux](https://mastra.zisheng.pro/fr/docs/capabilities/channels/overview)