مدیریت جلسه‌ها و چرخه حیات

گردش‌های کار عاملی درون‌دستگاهی (بااستفاده از کلاس AgentRunner) جلسه‌های چندنوبتی مدیریت‌شده‌ای ارائه می‌دهند که سابقه مکالمه را به‌طور خودکار در حافظه درطول نوبت‌ها ضبط می‌کنند، بنابراین لازم نیست ترانویسی‌ها را به‌صورت دستی مدیریت کنید. (اگر ترجیح می‌دهید سابقه گپ خود را مستقیماً مدیریت کنید، می‌توانید بااستفاده از دسترسی مستقیم به مدل، یک شیء List<Content> چندنوبتی با نقش‌های USER و MODEL و مقدار sessionId را به شیء GenerateContentRequest ارسال کنید.)

این صفحه مدیریت نمونه‌های AgentSession را در سراسر چرخه‌های حیات مؤلفه Android، تغییرات پیکربندی، و بازیابی حافظه پوشش می‌دهد.

جلسه‌های چندنوبتی

مکالمه‌های چندنوبتی را بااستفاده از نمونه‌های AgentSession محدودشده که بااستفاده از روش runner.getOrCreateSession(sessionId) به‌دست آمده‌اند مدیریت کنید. نوبت‌های مکالمه (پیام‌های کاربر، فراخوانی‌های ابزار، و پاسخ‌های مدل) به‌طور خودکار درطول جلسه در حافظه ضبط می‌شوند. فراخوانی‌های بعدی به روش session.runAsync(content)، نوبت‌های قبلی را به‌عنوان بافت حفظ می‌کنند.

شناسه‌های جلسه نباید خالی باشند، حداکثر ۱۲۸ نویسه داشته باشند، و فقط حاوی نویسه‌های الفباعددی، زیرخط، خط تیره، یا نقطه باشند (^[a-zA-Z0-9_.-]+$، به‌استثنای . و ..). رشته‌های UUID تولیدشده بااستفاده از روش UUID.randomUUID().toString() با این محدودیت‌ها مطابقت دارند.

برای شروع مکالمه چندنوبتی، شناسه جلسه ایجاد کنید و نمونه AgentSession را از نمونه AgentRunner خود دریافت کنید:

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

هر فراخوانی به روش session.runAsync(content) یک نوبت پیام‌واره جدید در آن جلسه ارسال می‌کند. مدل بافت را از نوبت‌های قبلی در مکالمه حفظ می‌کند.

حفظ جلسه‌ها در تغییرات پیکربندی

میانای AgentSession سابقه مکالمه را در حافظه نگه می‌دارد و میانای Parcelable را پیاده‌سازی نمی‌کند. در برنامه‌های Android، «فعالیت‌ها» و «قطعه‌ها» درطول تغییرات پیکربندی (مانند چرخش صفحه‌نمایش) ازبین می‌روند و دوباره ایجاد می‌شوند. اگر جلسه را مستقیماً در «فعالیت» ذخیره کنید، سابقه مکالمه پس‌از چرخش ازبین می‌رود.

برای حفظ سابقه مکالمه در تغییرات پیکربندی، نمونه AgentSession خود را در کلاس AndroidX ViewModel نگه دارید:

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()
    }
}

مدیریت حافظه و پاک‌سازی جلسه

برای حفظ عملکرد برنامه، وضعیت مکالمه درون‌حافظه‌ای را محدود نگه دارید:

  • حذف صریح جلسه: وقتی کاربر رشته مکالمه‌ای را ترک می‌کند یا روی «گپ جدید» تک‌ضرب می‌زند، روش session.delete() یا runner.deleteSession(sessionId) را فراخوانی کنید تا حافظه اختصاص‌داده‌شده برای نوبت‌های گذشته و خروجی‌های ابزار به‌صورت هم‌زمان آزاد شود. همچنین، فراخوانی روش session.close() باعث ارسال اخراج پس‌زمینه می‌شود.
  • پاک‌سازی خروج از سیستم: وقتی کاربر از سیستم خارج می‌شود یا داده‌های برنامه را پاک می‌کند، روش runner.clearAllSessions() را فراخوانی کنید.
  • پاک‌سازی جلسه در پایان چرخه حیات: وقتی کلاس ViewModel یا مؤلفه اصلی برای همیشه ازبین می‌رود (در روش onCleared())، روش session.close() را فراخوانی کنید. این کار روال‌های هم‌زمان درحال اجرا را لغو می‌کند و تخلیه پس‌زمینه را برای آن جلسه مکالمه ارسال می‌کند.

اجرای زودگذر تک‌نوبتی

برای تکالیف یک‌باره عامل (مثل تولید خلاصه سریع، اعتبارسنجی ورودی، یا پاسخ دادن به سؤال مستقل) که در آن به بافت گذشته نیازی نیست، مستقیماً روش 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)
        }
    }

هنگام فراخوانی مستقیم روش runner.runSingleTurnAsync(content)، کلاس AgentRunner یک جلسه موقت را به‌طور داخلی اختصاص می‌دهد و به‌طور خودکار همه وضعیت مکالمه را از حافظه پاک می‌کند، به‌محض اینکه جریان پاسخ تکمیل یا لغو شود، از نشت حافظه جلوگیری می‌کند.

مراحل بعدی