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

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.

src/mastra/agent-controller.ts

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.

AgentControllerMode

id:

string

Identifiant unique du mode.

name?:

string

Nom affiché.

defaultModelId?:

string

Modèle sélectionné lorsqu’une session entre dans ce mode sans sélection enregistrée.

description?:

string

Texte affiché dans les sélecteurs de mode.

instructions?:

string

Instructions ajoutées au-dessus de celles de l’Agent sous-jacent pour ce mode.

transitionsTo?:

string

Mode activé après une suspension submit_plan approuvée.

availableTools?:

string[]

Liste d’autorisation des noms d’outils exposés. Un tableau vide masque tous les outils dans ce mode.

metadata?:

Record<string, unknown>

Métadonnées du mode transmises telles quelles. metadata.default: true désigne le mode par défaut.

tools?:

ToolsInput

Outils du mode. Mutuellement exclusif avec additionalTools.

additionalTools?:

ToolsInput

Outils ajoutés à ceux de l’Agent sous-jacent. Mutuellement exclusif avec tools.

agent?:

Agent

Agent propre au mode, désormais obsolète. Utilisez le paramètre agent de premier niveau.

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é.

AgentControllerSubagent

id:

string

Identifiant unique du type de sous-agent.

name:

string

Nom affiché.

description:

string

Description utilisée par l’outil généré.

instructions:

DynamicArgument<AgentInstructions>

Instructions du sous-agent.

tools?:

ToolsInput

Outils appartenant au sous-agent.

allowedControllerTools?:

string[]

ID des outils du contrôleur ajoutés aux outils du sous-agent.

allowedWorkspaceTools?:

string[]

Noms des outils du Workspace visibles par le sous-agent.

defaultModelId?:

string

Modèle par défaut du sous-agent.

maxSteps?:

number

Nombre maximal d’étapes d’exécution.

stopWhen?:

LoopOptions["stopWhen"]

Condition d’arrêt de la boucle.

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.

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.

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.

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

getKnownResourceIds(session)

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

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.

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.

await controller.destroy()

Modes et Agents

listModes()

Renvoie les définitions des modes configurés.

const modes = controller.listModes()

Renvoie : AgentControllerMode[]

getCurrentAgent(session)

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

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.

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

Renvoie : boolean

isWorkspaceReady()

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

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.

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.

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.

controller.setBrowser(browser)

Mastra et canaux

getMastra()

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

const mastra = controller.getMastra()

Renvoie : Mastra | undefined

getChannels()

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

const channels = controller.getChannels()

Renvoie : AgentControllerChannels | null

Modèles

getCurrentModelAuthStatus(session)

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

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é.

const models = await controller.listAvailableModels()

Renvoie : Promise<AvailableModel[]>

invalidateAvailableModelsCache()

Vide le cache des modèles disponibles.

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.

await controller.loadOMProgress(session)

getObservationalMemoryRecord(session)

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

const record = await controller.getObservationalMemoryRecord(session)

Renvoie : Promise<ObservationalMemoryRecord | null>

getToolCategory({ toolName })

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

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

Renvoie : ToolCategory | null

Intervalles

registerInterval(handler)

Démarre ou remplace un gestionnaire périodique.

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.

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

stopIntervals()

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

await controller.stopIntervals()

Voir aussi

• Guide d’AgentController
• Référence de Session
• Agents
• Workspace
• Canaux