Session

beta

La fonctionnalité AgentController est en phase bêta et peut subir des modifications incompatibles dans les versions mineures jusqu’à sa sortie de bêta.

Une Session est l’environnement d’exécution isolé d’une ressource et d’une portée facultative. Elle possède son bus d’événements, sa liaison au thread, son état, ses sélections de mode et de modèle, son contrôle d’exécution, ses approbations, ses suspensions, ses suivis et son état d’affichage. L’AgentController fournit les Agents, la configuration, le stockage, les Workspaces et les services partagés.

Créez les Sessions au moyen de controller.createSession(). La construction directe et les méthodes de raccordement au contrôleur ne font pas partie des API applicatives.

Pour une introduction conceptuelle, consultez la présentation d’AgentController.

Exemple d’utilisation

L’exemple suivant utilise le flux pris en charge du contrôleur vers la Session.

await controller.init()

const session = await controller.createSession({ resourceId: 'project-42' })
const unsubscribe = session.subscribe(event => {
  if (event.type === 'display_state_changed') {
    render(event.displayState)
  }
})

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

Propriétés

La Session est organisée en sous-objets, chacun possédant un domaine de l’état propre à la conversation.

identity:

SessionIdentity

Identité stable de la Session, de son propriétaire et de sa ressource pour la conversation. Consultez les méthodes d’identité ci-dessous.

thread:

SessionThread

Liaison au thread actif et lecture des threads et messages. Consultez les méthodes de thread ci-dessous.

mode:

SessionMode

Sélection du mode actif. Consultez les méthodes de mode ci-dessous.

model:

SessionModel

Sélection du modèle actif, y compris la persistance propre à chaque mode. Consultez les méthodes de modèle ci-dessous.

om:

SessionOM

Paramètres des modèles observateur et réflecteur de la mémoire observationnelle.

permissions:

SessionPermissions

Politiques d’autorisation des Tools et des catégories représentées dans l’état de la Session.

subagents:

SessionSubagents

Sélection du modèle de sous-Agent globale et propre à chaque type d’Agent.

run:

SessionRun

Identité de l’exécution et de la Trace, ainsi qu’état d’abandon de l’exécution en cours. Consultez les méthodes d’exécution ci-dessous.

stream:

SessionStream

Abonnement en direct au flux du thread de l’Agent. Consultez les méthodes de flux ci-dessous.

suspensions:

SessionSuspensions

Appels de Tool interactifs mis en attente jusqu’à leur reprise. Consultez les méthodes de suspension ci-dessous.

followUps:

SessionFollowUps

File d’attente des messages envoyés pendant une exécution. Consultez les méthodes de suivi ci-dessous.

approval:

SessionApproval

Point de contrôle de l’approbation de Tool en attente. Consultez les méthodes d’approbation ci-dessous.

displayState:

SessionDisplayState

Instantané AgentControllerDisplayState canonique à partir duquel une interface utilisateur effectue son rendu. Consultez les méthodes d’état d’affichage ci-dessous.

state:

AgentControllerRequestState<TState>

État AgentController appartenant à la Session et validé par le schéma. Consultez les méthodes d’état ci-dessous.

browser:

MastraBrowser | undefined

Instance d’automatisation du Browser pour cette Session. Définie lors de la création par createSession, ou issue de la valeur par défaut de la configuration AgentController. Vaut undefined lorsqu’aucun Browser n’est configuré.

Méthodes

Identité et événements

getTags()

Renvoie une copie des tags fournis lors de la création de la Session.

const tags = session.getTags()

Renvoie : Record<string, string>

subscribe(listener)

S’abonne au bus d’événements isolé de cette Session. La méthode renvoie une fonction de désabonnement.

const unsubscribe = session.subscribe(event => {
  console.log(event.type)
})

unsubscribe()

Renvoie : () => void

Messages et contrôle de l’exécution

sendMessage({ content, files?, requestContext? })

Envoie un message utilisateur. La Session crée d’abord un thread lorsqu’aucun thread n’est actif.

await session.sendMessage({
  content: 'Summarize this file.',
  files: [{ data: fileContents, mediaType: 'text/plain', filename: 'notes.txt' }],
})

steer({ content, requestContext? })

Place un contenu d’orientation dans la file d’attente d’une exécution active.

await session.steer({ content: 'Focus on the failing tests.' })

followUp({ content, requestContext? })

Place un suivi dans la file d’attente pendant une exécution active, ou l’envoie immédiatement lorsque la Session est inactive.

await session.followUp({ content: 'Then propose a fix.' })

getCurrentRunId()

Renvoie l’identifiant d’exécution du flux actif, l’identifiant d’exécution suivi ou null lorsque la Session est inactive.

const runId = session.getCurrentRunId()

Renvoie : string | null

abort()

Abandonne l’exécution active et efface l’état d’affichage des suspensions en attente.

session.abort()

Workspace

getWorkspace()

Renvoie le Workspace résolu pour cette Session. Les remplacements propres à la Session et les Workspaces sélectionnés depuis sa portée sont ainsi conservés.

const workspace = session.getWorkspace()
const skill = await workspace.skills?.get('code-review')

Renvoie : Workspace

Autorisations de la Session

Les autorisations limitées à la Session approuvent automatiquement les Tools sans demander de confirmation. Elles sont éphémères : elles sont réinitialisées au redémarrage de la Session et ne sont jamais persistées.

grantCategory(category)

Autorise une catégorie de Tools pour la Session actuelle. Les Tools de cette catégorie sont automatiquement approuvés.

session.grantCategory('edit')

grantTool(toolName)

Autorise un Tool précis pour la Session actuelle.

session.grantTool('mastra_workspace_execute_command')

getGrants()

Renvoie les catégories et les Tools actuellement autorisés.

const grants = session.getGrants()
// { categories: string[], tools: string[] }

hasCategoryGrant(category)

Indique si une catégorie dispose d’une autorisation de Session en mémoire.

const allowed = session.hasCategoryGrant('edit')

Renvoie : boolean

hasToolGrant(toolName)

Indique si un Tool dispose d’une autorisation de Session en mémoire.

const allowed = session.hasToolGrant('write_file')

Renvoie : boolean

Approbations des Tools

resolveToolApproval(toolName)

Renvoie la politique effective après l’application des règles explicites des Tools, des autorisations de Session et des règles de catégorie.

const policy = session.resolveToolApproval('execute_command')

Renvoie : PermissionPolicy

respondToToolApproval({ decision, toolCallId?, requestContext?, declineContext? })

Répond à une demande d’approbation de Tool en attente, déclenchée par un événement tool_approval_required. Transmettez always_allow_category pour autoriser également toute la catégorie du Tool pendant le reste de la Session.

session.respondToToolApproval({ decision: 'approve' })
session.respondToToolApproval({ decision: 'decline' })
session.respondToToolApproval({ decision: 'always_allow_category' })

respondToToolSuspension({ resumeData, toolCallId?, requestContext? })

Reprend un Tool suspendu avec les données fournies par l’application. Fournissez toolCallId lorsque plusieurs appels de Tool sont suspendus.

await session.respondToToolSuspension({
  toolCallId: event.toolCallId,
  resumeData: ['src'],
})

Pour submit_plan, transmettez { action: 'approved' } ou { action: 'rejected', feedback }. L’approbation peut basculer vers le mode configuré par transitionsTo avant la reprise du Tool.

Utilisation des tokens

getTokenUsage()

Renvoie une copie du décompte cumulé des tokens utilisés pour le thread actif.

const usage = session.getTokenUsage()
// { promptTokens, completionTokens, totalTokens, ... }

Identité

session.identity possède les identifiants stables de la conversation : l’ID de ressource, un id de Session et un ownerId. Les valeurs id et ownerId restent stables pendant toute la durée de vie de la Session et ne changent pas lors du remplacement de l’ID de ressource. Elles reflètent les champs id et ownerId de SessionRecord dans le stockage.

session.identity.getId()

Renvoie l’identifiant stable de la Session.

const sessionId = session.identity.getId()

session.identity.getOwnerId()

Renvoie l’identifiant stable du propriétaire de la Session.

const ownerId = session.identity.getOwnerId()

session.identity.getResourceId()

Renvoie l’ID de ressource actuel.

const resourceId = session.identity.getResourceId()

session.identity.getDefaultResourceId()

Renvoie l’ID de ressource avec lequel la Session a été créée.

const defaultResourceId = session.identity.getDefaultResourceId()

Pour modifier l’ID de ressource, utilisez controller.setResourceId(), qui efface également le thread actif. Les valeurs id et ownerId de la Session ne sont pas affectées par les changements de ressource.

Thread

session.thread possède la liaison au thread actif et les opérations de thread limitées à la ressource. Lorsque le stockage est configuré, les threads et messages stockés peuvent survivre à la recréation du contrôleur. Ce n’est pas le cas de la Session active et de son bus d’événements.

session.thread.create({ title?, id? })

Crée un thread, y lie la Session et ouvre son flux d’événements.

const thread = await session.thread.create({
  id: 'thread-7',
  title: 'Investigate login failure',
})

Renvoie : Promise<AgentControllerThread>

session.thread.rename({ title })

Renomme le thread actif stocké.

await session.thread.rename({ title: 'Fix login failure' })

session.thread.clone({ sourceThreadId?, title?, resourceId? })

Clone un thread appartenant à la Session ainsi que ses messages, puis lie la Session au clone.

const clone = await session.thread.clone({
  sourceThreadId: 'thread-7',
  title: 'Alternative approach',
})

Renvoie : Promise<AgentControllerThread>

session.thread.switch({ threadId, emitEvent? })

Bascule vers un thread stocké appartenant à la Session et réhydrate ses paramètres de mode, de modèle et de mémoire observationnelle.

await session.thread.switch({ threadId: 'thread-8' })

session.thread.delete({ threadId })

Supprime un thread appartenant à la Session. La suppression du thread actif efface également la liaison actuelle.

await session.thread.delete({ threadId: 'thread-8' })

session.thread.getId()

Renvoie l’ID du thread actif, ou null lorsqu’aucun thread n’est lié.

const threadId = session.thread.getId()

session.thread.list(options?)

Répertorie les threads du stockage. Par défaut, seuls les threads de la ressource actuelle sont renvoyés, et les threads transitoires dérivés des sous-Agents sont masqués.

const threads = await session.thread.list()
const allThreads = await session.thread.list({ allResources: true })
const everything = await session.thread.list({ includeForkedSubagents: true })

session.thread.getById({ threadId })

Renvoie un thread précis à partir de son ID, ou null s’il n’existe pas.

const thread = await session.thread.getById({ threadId: 'thread-abc123' })

session.thread.listActiveMessages(options?)

Récupère les messages du thread actif. Renvoie un tableau vide lorsqu’aucun thread n’est lié.

const messages = await session.thread.listActiveMessages({ limit: 50 })

session.thread.listMessages({ threadId, limit? })

Récupère les messages d’un thread précis.

const messages = await session.thread.listMessages({ threadId: 'thread-abc123' })

Les méthodes de lecture de messages listActiveMessages, listMessages et firstUserMessage renvoient des objets MastraDBMessage, tandis que firstUserMessages renvoie une Map<string, MastraDBMessage> indexée par ID de thread. Chaque message possède un role, un id, un createdAt et un objet content comprenant content.format et un tableau content.parts. Lisez le texte, le raisonnement, les appels de Tool et les pièces jointes depuis content.parts. Les signaux tels que les rappels système et les notifications sont renvoyés comme des messages distincts avec role: 'signal'.

session.thread.firstUserMessage({ threadId })

Récupère le premier message utilisateur d’un thread, ou null s’il n’y en a aucun.

const firstMsg = await session.thread.firstUserMessage({
  threadId: 'thread-abc123',
})

session.thread.firstUserMessages({ threadIds })

Récupère simultanément le premier message utilisateur de plusieurs threads et les renvoie sous forme de map.

const firstByThread = await session.thread.firstUserMessages({
  threadIds: ['thread-a', 'thread-b'],
})

session.thread.getSetting({ key })

Lit un paramètre dans les métadonnées du thread actif.

const value = await session.thread.getSetting({ key: 'omThreshold' })

session.thread.setSetting({ key, value })

Écrit un paramètre dans les métadonnées du thread actif.

await session.thread.setSetting({ key: 'omThreshold', value: 0.8 })

session.thread.deleteSetting({ key })

Supprime un paramètre des métadonnées du thread actif.

await session.thread.deleteSetting({ key: 'omThreshold' })

Mode

session.mode possède la sélection du mode actif.

session.mode.get()

Renvoie l’ID du mode actif.

const modeId = session.mode.get()

session.mode.resolve()

Renvoie l’objet AgentControllerMode complet du mode actif, résolu par rapport aux modes configurés du contrôleur.

const mode = session.mode.resolve()

session.mode.switch({ modeId })

Bascule vers un autre mode. La Session enregistre le modèle du mode sortant avant de persister le nouveau mode dans le thread actif. Elle restaure ensuite le modèle sélectionné ou par défaut du mode entrant. La Session émet immédiatement mode_changed, puis model_changed après la résolution du modèle.

await session.mode.switch({ modeId: 'build' })

Modèle

session.model possède la sélection du modèle actif, notamment la mémorisation du modèle propre à chaque mode.

session.model.get()

Renvoie l’ID du modèle actif.

const modelId = session.model.get()

session.model.displayName()

Renvoie le dernier segment de l’ID du modèle actif comme nom d’affichage court. Renvoie 'unknown' lorsqu’aucun modèle n’est sélectionné.

const name = session.model.displayName()

session.model.hasSelection()

Vérifie si un modèle est actuellement sélectionné.

if (session.model.hasSelection()) {
  // Ready to send messages
}

session.model.switch({ modelId, scope?, modeId? })

Bascule le modèle actif. Lorsque scope vaut 'thread' (valeur par défaut), l’ID du modèle est persisté comme modèle propre au mode afin d’être restauré lors d’un retour à ce mode. Signale la sélection au modelUseCountTracker du contrôleur et émet un événement model_changed.

// Set for the current session only
await session.model.switch({
  modelId: 'anthropic/claude-sonnet-4-6',
  scope: 'global',
})

// Persist to the current thread (default)
await session.model.switch({ modelId: 'anthropic/claude-sonnet-4-6' })

Mémoire observationnelle

La sélection du modèle de mémoire observationnelle est regroupée par rôle sous session.om.observer et session.om.reflector. Les deux rôles exposent les mêmes méthodes. Les lectures renvoient la valeur de l’état de la Session lorsqu’elle est définie, sinon les valeurs par défaut de l’omConfig du contrôleur.

session.om.observer.modelId() / session.om.reflector.modelId()

Renvoie l’ID du modèle du rôle, ou undefined lorsque ni l’état de la Session ni omConfig n’en fournit.

const observer = session.om.observer.modelId()
const reflector = session.om.reflector.modelId()

session.om.observer.threshold() / session.om.reflector.threshold()

Renvoie le seuil du rôle en tokens (seuil d’observation pour l’observateur, seuil de réflexion pour le réflecteur), ou undefined lorsqu’il n’est pas défini.

const observationThreshold = session.om.observer.threshold()
const reflectionThreshold = session.om.reflector.threshold()

session.om.observer.switchModel({ modelId }) / session.om.reflector.switchModel({ modelId })

Bascule le modèle du rôle. Persiste le paramètre dans les métadonnées du thread et émet un événement om_model_changed.

await session.om.observer.switchModel({
  modelId: 'anthropic/claude-haiku-4-5',
})
await session.om.reflector.switchModel({
  modelId: 'anthropic/claude-haiku-4-5',
})

session.om.observer.resolvedModel() / session.om.reflector.resolvedModel()

Résout l’ID du modèle du rôle en une instance de modèle via les passerelles de modèles configurées, ou renvoie undefined lorsqu’aucun ID de modèle n’est défini ou qu’aucune fonction de résolution n’est configurée.

const observerModel = session.om.observer.resolvedModel()
const reflectorModel = session.om.reflector.resolvedModel()

Permissions

session.permissions possède la politique d’approbation des Tools représentée dans session.state : les règles propres à chaque catégorie et à chaque Tool consultées lors de la résolution de l’approbation. Elles sont distinctes des autorisations en mémoire décrites dans Autorisations de la Session. Les autorisations sont réinitialisées avec la Session active. Les règles d’autorisation ne sont pas durables, sauf si l’hôte restaure l’état de Session correspondant.

session.permissions.getRules()

Renvoie les règles d’autorisation actuelles, ou des règles vides ({ categories: {}, tools: {} }) lorsqu’aucune n’est définie.

const rules = session.permissions.getRules()
// { categories: { execute: 'ask' }, tools: { dangerous_tool: 'deny' } }

session.permissions.setForCategory({ category, policy })

Définit la politique d’approbation ('allow' | 'ask' | 'deny') d’une catégorie de Tools. La Promise est résolue une fois la modification persistée dans l’état de la Session.

await session.permissions.setForCategory({ category: 'execute', policy: 'ask' })

session.permissions.setForTool({ toolName, policy })

Définit la politique d’approbation d’un Tool précis. Les politiques propres aux Tools prévalent sur celles des catégories. La Promise est résolue après la persistance.

await session.permissions.setForTool({ toolName: 'dangerous_tool', policy: 'deny' })

Sous-Agents

session.subagents possède la configuration des sous-Agents. Il expose actuellement la sélection du modèle des sous-Agents sous session.subagents.model.

session.subagents.model.get({ agentType? })

Renvoie l’ID du modèle de sous-Agent, en privilégiant la valeur propre à l’agentType lorsqu’elle est fournie, puis le modèle global des sous-Agents, ou null lorsqu’aucun des deux n’est défini.

const modelId = session.subagents.model.get({ agentType: 'explore' })

session.subagents.model.set({ modelId, agentType? })

Définit l’ID du modèle de sous-Agent. Transmettez un agentType pour définir un remplacement propre à ce type, ou omettez-le pour définir la valeur globale par défaut. Persiste la valeur dans les paramètres du thread et émet un événement subagent_model_changed.

// Set the global subagent model
await session.subagents.model.set({ modelId: 'anthropic/claude-sonnet-4-6' })

// Set a per-type override
await session.subagents.model.set({
  modelId: 'anthropic/claude-haiku-4-5',
  agentType: 'explore',
})

Exécution

session.run possède l’identité de l’exécution et de la Trace, ainsi que l’état d’abandon de l’exécution en cours.

session.run.getRunId() / getTraceId()

Renvoie l’ID d’exécution et l’ID de Trace stockés pour l’exécution actuelle, ou null lorsqu’elle est inactive.

const runId = session.run.getRunId()
const traceId = session.run.getTraceId()

session.run.isRunning()

Indique si une exécution est actuellement en cours.

if (session.run.isRunning()) {
  // A run is active
}

Flux

session.stream possède l’abonnement en direct au flux du thread de l’Agent et sa clé de déduplication.

session.stream.activeRunId()

Renvoie l’ID d’exécution actif sur le flux en direct, ou null lorsqu’aucun flux n’est ouvert.

const runId = session.stream.activeRunId()

session.stream.isActive()

Indique si le flux possède actuellement une exécution active.

if (session.stream.isActive()) {
  // The current thread's stream is producing output
}

Suspensions

session.suspensions possède les appels de Tool interactifs mis en attente (tels que ask_user et request_access) jusqu’à leur reprise.

session.suspensions.hasPending()

Indique si au moins un Tool est actuellement suspendu.

if (session.suspensions.hasPending()) {
  // At least one interactive tool is waiting for a response
}

session.suspensions.has({ toolCallId })

Indique si un appel de Tool précis est suspendu.

const waiting = session.suspensions.has({ toolCallId: event.toolCallId })

Reprenez un Tool suspendu avec session.respondToToolSuspension().

Suivis

session.followUps possède la file FIFO des messages envoyés pendant une exécution.

session.followUps.count()

Renvoie le nombre de suivis en attente.

const queued = session.followUps.count()

session.followUps.isEmpty()

Indique si la file d’attente des suivis est vide.

if (!session.followUps.isEmpty()) {
  // Messages are waiting to be processed
}

Approbation

session.approval possède le point de contrôle de l’approbation de Tool en attente.

session.approval.isArmed()

Indique si un Tool attend actuellement une décision d’approbation.

if (session.approval.isArmed()) {
  // Show the approval prompt
}

Répondez avec session.respondToToolApproval().

État d’affichage

session.displayState possède l’instantané AgentControllerDisplayState canonique à partir duquel une interface utilisateur effectue son rendu, ainsi que le réducteur qui le synchronise avec chaque événement de la Session.

session.displayState.get()

Renvoie l’instantané AgentControllerDisplayState actuel pour le rendu de l’interface utilisateur.

const displayState = session.displayState.get()

session.displayState.restoreTasks(tasks)

Restaure la partie de l’instantané consacrée aux tâches après qu’une interface utilisateur a rejoué l’historique persisté des Tools de tâche. Il s’agit d’une mise à jour pure de l’instantané qui n’émet aucun événement ; effectuez donc explicitement un nouveau rendu après l’appel.

session.displayState.restoreTasks(replayedTasks)

Après chaque événement, la Session émet display_state_changed avec le dernier instantané. Abonnez-vous avec session.subscribe() ou lisez la valeur actuelle depuis session.displayState.get().

État

session.state possède l’état AgentController validé par le schéma pour la conversation. Il conserve l’instantané actuel et valide les mises à jour par rapport au stateSchema transmis à l’AgentController. Les mises à jour sont sérialisées et chaque modification émet un événement state_changed.

session.state.get()

Renvoie une copie en lecture seule de l’instantané d’état actuel.

const state = session.state.get()

session.state.set(updates)

Fusionne une mise à jour partielle dans l’état. Les mises à jour sont placées en file d’attente afin que les appels concurrents soient appliqués dans l’ordre, validés par rapport au schéma, puis émettent state_changed avec les clés modifiées.

await session.state.set({ yolo: true })

session.state.update(updater)

Exécute une fonction de mise à jour sur l’instantané actuel et applique son résultat de façon atomique dans la file d’écriture. Utilisez cette méthode pour les modifications lecture-modification-écriture qui doivent voir l’état le plus récent. La fonction renvoie les updates à fusionner, les events facultatifs à émettre et une valeur result à laquelle update() est résolue.

const added = await session.state.update(current => ({
  updates: { count: (current.count ?? 0) + 1 },
  result: (current.count ?? 0) + 1,
}))

Limites de persistance

Une Session est un objet d’exécution actif. Son bus d’événements, son session.state arbitraire, ses règles et autorisations, ses approbations en attente, ses suspensions, ses suivis, son état d’exécution et son état de flux ne survivent pas automatiquement à la recréation du contrôleur ou du processus. L’hôte doit restaurer chacun de ces éléments d’état lors de la recréation d’une Session.

Lorsque le stockage est configuré, les threads, les messages et l’utilisation des tokens persistent. Les paramètres du thread restaurent les choix de mode et de modèle. Ils peuvent également restaurer les paramètres de mémoire observationnelle et les sélections de modèles de sous-Agents, y compris les remplacements propres à chaque type d’Agent. Un canal de discussion peut être réassocié aux threads stockés, mais l’état de correspondance entre canal et Session ainsi que l’état d’approbation automatique détenus par AgentControllerChannels restent en mémoire.

Voir aussi

• Classe AgentController
• Présentation d’AgentController
• Threads et état
• Approbations des Tools