Gérer les sessions et le cycle de vie

Les workflows agentiques sur l'appareil (à l'aide de la classe AgentRunner) fournissent des sessions multitours gérées qui enregistrent automatiquement l'historique des conversations en mémoire d'un tour à l'autre. Vous n'avez donc pas besoin de gérer les transcriptions manuellement. (Si vous préférez gérer directement votre propre historique de discussions, vous pouvez transmettre un objet List<Content> multitour avec les rôles USER et MODEL et une valeur sessionId à un objet GenerateContentRequest à l'aide de l'accès direct au modèle.)

Cette page explique comment gérer les instances AgentSession tout au long du cycle de vie des composants Android, des modifications de configuration et de la récupération de mémoire.

Sessions multitours

Gérez les conversations multitours à l'aide d'instances AgentSession limitées obtenues à l'aide de la méthode runner.getOrCreateSession(sessionId). Les tours de dialogue (messages utilisateur, appels d'outils et réponses du modèle) sont automatiquement enregistrés en mémoire au cours de la session. Les appels ultérieurs à la méthode session.runAsync(content) conservent les tours précédents en tant que contexte.

Les identifiants de session ne doivent pas être vides, doivent comporter au maximum 128 caractères et ne doivent contenir que des caractères alphanumériques, des traits de soulignement, des traits d'union ou des points (^[a-zA-Z0-9_.-]+$, à l'exclusion de . et ..). Les chaînes UUID générées à l'aide de la méthode UUID.randomUUID().toString() respectent ces contraintes.

Pour démarrer une conversation multitour, créez un identifiant de session et obtenez une instance AgentSession à partir de votre instance AgentRunner :

val sessionId = "user_chat_${System.currentTimeMillis()}"
val session = runner.getOrCreateSession(sessionId)

Chaque appel de la méthode session.runAsync(content) envoie un nouveau tour de requête dans cette session. Le modèle conserve le contexte des tours précédents de la conversation.

Conserver les sessions lors des changements de configuration

L'interface AgentSession conserve l'historique des dialogues en mémoire et n'implémente pas l'interface Parcelable. Dans les applications Android, les activités et les fragments sont détruits et recréés lors des modifications de configuration (comme la rotation de l'écran). Si vous stockez la session directement dans une activité, l'historique des conversations est perdu lors de la rotation.

Pour conserver l'historique des conversations lors des modifications de configuration, conservez votre instance AgentSession dans une classe ViewModel AndroidX :

package com.example.ai.agent.ui

import androidx.lifecycle.ViewModel
import androidx.lifecycle.viewModelScope
import com.google.mlkit.genai.agent.AgentRunner
import com.google.mlkit.genai.agent.AgentSession
import com.google.mlkit.genai.agent.textTokens
import com.google.mlkit.genai.prompt.Content
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.flow.update
import kotlinx.coroutines.launch

class ChatViewModel(
    private val runner: AgentRunner,
    private val sessionId: String = "default_chat_session"
) : ViewModel() {

    // Retain the session inside the ViewModel to survive screen rotations
    private val session: AgentSession = runner.getOrCreateSession(sessionId)

    private val _responseText = MutableStateFlow("")
    val responseText: StateFlow<String> = _responseText.asStateFlow()

    fun sendMessage(userPrompt: String) {
        viewModelScope.launch {
            val content = Content.builder().text(userPrompt).build()
            session.runAsync(content)
                .textTokens()
                .collect { token ->
                    _responseText.update { it + token }
                }
        }
    }

    override fun onCleared() {
        super.onCleared()
        // Release session memory and cancel active coroutines when ViewModel is destroyed
        session.close()
    }
}

Gestion de la mémoire et nettoyage des sessions

Limitez l'état de la conversation en mémoire pour maintenir les performances de l'application :

  • Suppression explicite de session : lorsqu'un utilisateur quitte un fil de conversation ou appuie sur "Nouvelle discussion", appelez la méthode session.delete() ou runner.deleteSession(sessionId) pour libérer de manière synchrone la mémoire allouée aux tours précédents et aux sorties d'outils. Vous pouvez également appeler la méthode session.close() pour déclencher l'éviction en arrière-plan.
  • Nettoyage à la déconnexion : appelez la méthode runner.clearAllSessions() lorsque l'utilisateur se déconnecte ou efface les données de l'application.
  • Nettoyage de la session à la fin du cycle de vie : appelez la méthode session.close() lorsque votre classe ViewModel ou votre composant parent est définitivement détruit (dans la méthode onCleared()). Cela annule les coroutines en cours d'exécution et distribue l'éviction en arrière-plan pour cette session de conversation.

Exécution éphémère à un seul tour

Pour les tâches d'agent ponctuelles (comme la génération d'un résumé rapide, la validation d'une entrée ou la réponse à une question autonome) pour lesquelles le contexte passé n'est pas nécessaire, appelez directement la méthode runner.runSingleTurnAsync(content) :

import com.google.mlkit.genai.agent.AgentEvent
import com.google.mlkit.genai.prompt.Content

val content = Content.builder()
    .text("Summarize order history for customer #1042: ...")
    .build()

runner.runSingleTurnAsync(content)
    .collect { event ->
        if (event is AgentEvent.TextMessage && !event.isPartial) {
            displaySummary(event.text)
        }
    }

Lorsque vous appelez directement la méthode runner.runSingleTurnAsync(content), la classe AgentRunner alloue une session temporaire en interne et purge automatiquement l'état de la conversation de la mémoire une fois que le flux de réponse est terminé ou annulé, ce qui évite les fuites de mémoire.

Étapes suivantes