Cycle de vie et liste des sessions

Une session démarre avec agent.start_session() ou agent.run(), exécute des tours et se termine lorsque vous l'annulez, lorsqu'elle atteint une limite ou, pour un appel local à agent.run(), lorsque son tour est terminé. Son statut indique son état. Vous pouvez la retrouver par son identifiant ou dans la liste de vos sessions.

Vous avez besoin d'un agent qui s'exécute dans votre processus, ou d'un agent déployé avec Studio, via agents serve ou agents deploy.

Une session est running lorsqu'un tour est actif, waiting lorsqu'aucun tour n'est actif et qu'elle accepte un nouveau message, et terminated lorsqu'elle est terminée : voir SessionInfo. L'enregistrement du tour indique comment le tour s'est terminé et les actions possibles ensuite.

Dans cet exemple, une session locale exécute un tour, est annulée et refuse un nouveau message. Ses tours restent consultables :

import asyncio

from mistralai import agents

agent = agents.Agent(model="mistral-large-4", name="greeter", instructions="Answer in one word.")


async def main() -> None:
    session = await agent.start_session()
    state = await session.run("Say hi.")
    async for info in agents.list_sessions(host="local"):
        print(info.status, info.termination)

    await session.cancel()
    async for info in agents.list_sessions(host="local"):
        print(info.status, info.termination)

    try:
        await session.run("Say bye.")
    except agents.SessionTerminatedError as error:
        print(type(error).__name__, error)
    if isinstance(state, agents.Completed):
        turn_state = await session.turn(state.turn_id).get()
        print(type(turn_state).__name__, turn_state.text)


asyncio.run(main())

import asyncio

from mistralai import agents

agent = agents.Agent(model="mistral-large-4", name="greeter", instructions="Answer in one word.")


async def main() -> None:
    session = await agent.start_session()
    state = await session.run("Say hi.")
    async for info in agents.list_sessions(host="local"):
        print(info.status, info.termination)

    await session.cancel()
    async for info in agents.list_sessions(host="local"):
        print(info.status, info.termination)

    try:
        await session.run("Say bye.")
    except agents.SessionTerminatedError as error:
        print(type(error).__name__, error)
    if isinstance(state, agents.Completed):
        turn_state = await session.turn(state.turn_id).get()
        print(type(turn_state).__name__, turn_state.text)


asyncio.run(main())

waiting None
terminated CancelledTermination(cause=None)
SessionTerminatedError The local Session has ended
Completed Hi

waiting None
terminated CancelledTermination(cause=None)
SessionTerminatedError The local Session has ended
Completed Hi

await session.cancel() termine la session : cet appel arrête le tour en cours, s'il y en a un, et les sous-agents de la session. Dans votre processus, l'appel ne retourne que lorsque la session est terminée et que sa sandbox est libérée. Pour une session déployée, il retourne dès que l'agent a accepté l'annulation. La session terminée passe à l'état terminated, sa valeur termination est CancelledTermination(cause=None) et vous pouvez toujours consulter ses tours. Lui envoyer un nouveau message lève agents.SessionTerminatedError.

Sur un agent déployé, une session reste ouverte jusqu'à son annulation, même après le retour de l'appel qui l'a démarrée. agent.run() ne fait pas exception : sa session reste à l'état waiting après le tour. Terminez-la donc par son identifiant :

state = await agent.run("Review alert A-1042")
await agent.session(state.session_id).cancel()

state = await agent.run("Review alert A-1042")
await agent.session(state.session_id).cancel()

Dans votre processus, une session démarrée par agent.run() sans idempotency_key= se ferme une fois son tour et ses sous-agents terminés. Ses tours restent consultables. Dans un bloc async with agents.local_runtime(), elle reste ouverte jusqu'à la sortie du bloc ou jusqu'à son annulation.

Annulez chaque session que vous démarrez dès que vous n'en avez plus besoin. Sinon, une session déployée ne se termine que lorsqu'elle atteint une limite de session, et une session locale lorsque la boucle d'événements s'arrête ou que le bloc async with agents.local_runtime() dans lequel elle s'exécutait se termine : voir Cycle de vie des sessions locales.

Pour arrêter uniquement le tour en cours et conserver la session, appelez await turn.interrupt() : voir Turn.interrupt.

:::warning Abandonner un handle ne termine pas une session Un handle de session ne maintient rien ouvert. L'abandonner ou sortir de l'appel qui l'a créé ne change donc rien. Une session déployée et sa sandbox restent ouvertes jusqu'à ce qu'une limite de session les termine. Pour terminer une session, appelez await session.cancel(). :::

Par défaut, une session déployée se termine automatiquement après 4 heures d'inactivité ou après 24 heures au total, selon la première limite atteinte :

Une session est inactive lorsqu'aucun tour ne travaille, ou lorsque le tour en cours attend uniquement une action de l'utilisateur ou de votre application, par exemple l'approbation d'un outil. Elle n'est pas inactive tant que l'un de ses sous-agents travaille pour elle.

Lorsqu'une limite est atteinte, la session s'arrête comme si elle avait été annulée : un tour en cours renvoie agents.Interrupted, et ses sous-agents s'arrêtent également. Sa terminaison est un agents.CancelledTermination, dont cause vaut "lifetime_limit" ou "idle_limit". Si la session ne s'arrête pas d'elle-même dans les 5 minutes, elle est arrêtée de force. Une session terminée par une limite ne peut pas reprendre : démarrez-en une nouvelle.

Définissez les limites en secondes dans l'environnement de déploiement de l'agent. Elles s'appliquent à toutes ses sessions. Avec agents serve, définissez-les dans son environnement :

export AGENTS_SDK_IDLE_TIMEOUT_SECONDS=3600      # end a session after 1 hour idle
export AGENTS_SDK_LIFETIME_LIMIT_SECONDS=28800   # and after 8 hours in total
agents serve

export AGENTS_SDK_IDLE_TIMEOUT_SECONDS=3600      # end a session after 1 hour idle
export AGENTS_SDK_LIFETIME_LIMIT_SECONDS=28800   # and after 8 hours in total
agents serve

Avec agents deploy, définissez-les avec ENV dans le Dockerfile, sans dépasser les maxima ci-dessus : voir Limites des sessions.

Pour porter la limite totale à une semaine, ou au-delà avec agents serve, augmentez également AGENTS_SDK_EXECUTION_TIMEOUT_SECONDS. Sa valeur par défaut est d'une semaine et doit dépasser la limite totale de plus de 5 minutes. Sinon, agents serve ou l'agent déployé échoue au démarrage. Pour des sessions allant jusqu'à un an avec agents serve :

export AGENTS_SDK_LIFETIME_LIMIT_SECONDS=31536000      # a year in total
export AGENTS_SDK_IDLE_TIMEOUT_SECONDS=31536000        # and a year idle
export AGENTS_SDK_EXECUTION_TIMEOUT_SECONDS=31622400   # a year and a day
agents serve

export AGENTS_SDK_LIFETIME_LIMIT_SECONDS=31536000      # a year in total
export AGENTS_SDK_IDLE_TIMEOUT_SECONDS=31536000        # and a year idle
export AGENTS_SDK_EXECUTION_TIMEOUT_SECONDS=31622400   # a year and a day
agents serve

Les sessions déjà en cours conservent le délai d'exécution maximal avec lequel elles ont démarré. Une MistralSandbox a sa propre durée de vie, de 24 heures par défaut : augmentez sa valeur ttl_seconds pour des sessions plus longues.

Une session persiste au-delà de l'appel qui l'a démarrée. Conservez donc son identifiant pour la rouvrir plus tard. Pour un agent déployé, chargez l'agent par son nom, puis associez un handle à la session depuis n'importe quel processus :

from mistralai import agents

agent = agents.Agent.load_from(agent_name="hello-agent")
session = agent.session(stored_id)
state = await session.run("Where were we?")

from mistralai import agents

agent = agents.Agent.load_from(agent_name="hello-agent")
session = agent.session(stored_id)
state = await session.run("Where were we?")

Une session exécutée dans votre processus ne peut être ouverte que dans la boucle d'événements qui l'a démarrée : chaque boucle d'événements dispose de son propre environnement d'exécution local. Pour reprendre une session dans un processus ultérieur, enregistrez-la avec le journal expérimental : voir JsonFileSessionJournal.

agent.session(id) n'envoie rien. Si aucune session ne correspond à l'identifiant, la première requête le détecte et lève agents.SessionNotFoundError. Voir Handles de session.

agents.list_sessions() parcourt vos sessions racines, des plus récentes aux plus anciennes, sous forme d'enregistrements agents.SessionInfo. Pour agir sur une session de la liste, par exemple pour l'annuler, associez-lui un handle avec agent.session(info.id) :

async for info in agents.list_sessions(status="waiting", limit=2):
    print(info.id, info.status, info.created_at)

async for info in agents.list_sessions(status="waiting", limit=2):
    print(info.id, info.status, info.created_at)

01a18cb6-01c2-75dd-baba-b9d46f52d640 waiting 2026-10-30 12:08:20.554000+00:00
01a18cb5-5c3e-72b4-a90f-63a92036b762 waiting 2026-10-30 12:07:38.207000+00:00

01a18cb6-01c2-75dd-baba-b9d46f52d640 waiting 2026-10-30 12:08:20.554000+00:00
01a18cb5-5c3e-72b4-a90f-63a92036b762 waiting 2026-10-30 12:07:38.207000+00:00

Lorsqu'une session se termine, sa valeur termination en indique la cause. Faites la correspondance sur la classe et conservez un case pour UnknownTermination, afin que votre code continue de fonctionner si un nouveau type de terminaison est ajouté après votre version du SDK :

match info.termination:
    case agents.CompletedTermination(stop_reason=reason):
        print("completed", reason)
    case agents.CancelledTermination(cause=cause):
        print("cancelled", cause)
    case agents.FailedTermination(error=error):
        print("failed", error.message)
    case agents.UnknownTermination(outcome=outcome, raw=raw):
        print("ended:", outcome)  # e.g. "future_outcome"
    case None:
        print("still running")

match info.termination:
    case agents.CompletedTermination(stop_reason=reason):
        print("completed", reason)
    case agents.CancelledTermination(cause=cause):
        print("cancelled", cause)
    case agents.FailedTermination(error=error):
        print("failed", error.message)
    case agents.UnknownTermination(outcome=outcome, raw=raw):
        print("ended:", outcome)  # e.g. "future_outcome"
    case None:
        print("still running")

L'enregistrement d'une session déployée contient toujours stop_reason=None. La raison d'arrêt se trouve dans le résultat de son dernier tour : il s'agit de stop_reason sur l'objet Completed renvoyé par turn.result().

Tous les champs, mots-clés et classes de terminaison, les périmètres des sous-agents et agents.Client pour une autre clé API ou un autre cloud : Liste et client.

agents.list_sessions(host="local") liste plutôt les sessions exécutées dans le processus de la boucle d'événements en cours, avec les mêmes mots-clés. Parcourez-les dans la boucle d'événements qui les a démarrées : chaque appel à asyncio.run a son propre environnement d'exécution. Une session terminée dans le processus reste répertoriée à l'état "terminated" jusqu'à l'arrêt de la boucle d'événements.

• Sessions : démarrer des sessions et envoyer des messages.
• En local, dans le processus : terminer les sessions locales et les conserver après l'arrêt du processus.
• Cycle de vie de l'agent : mettre à jour et arrêter un agent déployé.