أحداث البث ودمج واجهة المستخدم

أثناء سير العمل المستند إلى الوكلاء، تُصدر فئة AgentRunner وواجهة AgentSession سلاسل أحداث تفاعلية تمثّل عملية الاستدلال في النموذج واستدعاءات الأدوات والردود النصية. توضّح هذه الصفحة كيفية جمع الأحداث وربطها بواجهة المستخدم باستخدام Kotlin Coroutines وJetpack Compose.

التعرّف على واجهة "AgentEvent"

يعرض الإجراءان AgentSession.runAsync() وAgentRunner.runSingleTurnAsync() بث Flow<AgentEvent>. بدلاً من انتظار انتهاء حلقة الاستدلال بأكملها، يتلقّى تطبيقك تحديثات في الوقت الفعلي أثناء تنفيذ الوكيل:

نوع الحدث	الوصف	إجراء نموذجي في واجهة المستخدم
AgentEvent.TextMessage	يُصدر أجزاء نصية متزايدة (isPartial = true) متبوعة بالرد النهائي الكامل (isPartial = false) الذي تم إنشاؤه بواسطة Gemini Nano.	إضافة event.text إلى فقاعة المحادثة النشطة عندما تكون قيمة event.isPartial هي true (أو استخدام دالة الإضافة textTokens())
AgentEvent.FunctionCall	يتم إرسال هذا الحدث عندما يختار Gemini Nano أداة ويستعد لتنفيذها (يوفّر event.name وevent.args).	اعرض مؤشرًا يشير إلى أنّ العملية قيد التقدّم (على سبيل المثال، "جارٍ التحقّق من حالة الطلب...").
AgentEvent.FunctionResponse	يتم إرسال هذا الحدث عندما ينتهي التطبيق من تنفيذ وظيفة الأداة (يوفّر event.name وevent.response).	انقل حالة الأداة إلى "مكتملة".

ملاحظة: واجهة AgentEvent هي sealed interface قائمة غير شاملة، لذا يمكن إضافة أنواع أحداث مستقبلية بدون التأثير في توافق المصدر. احرص دائمًا على تضمين فرع else -> عند مطابقة قيم AgentEvent في تعبير when.

جمع الأحداث في فئة ViewModel

استخدِم فئة ViewModel في Android لتنسيق إرسال الطلبات وعرض حالة واجهة المستخدم على شاشات Compose:

package com.example.ai.agent.ui

import androidx.lifecycle.ViewModel
import androidx.lifecycle.viewModelScope
import com.google.mlkit.genai.agent.AgentEvent
import com.google.mlkit.genai.agent.AgentRunner
import com.google.mlkit.genai.agent.AgentSession
import com.google.mlkit.genai.common.GenAiException
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.catch
import kotlinx.coroutines.flow.update
import kotlinx.coroutines.launch

data class AgentUiState(
    val messages: List<String> = emptyList(),
    val currentResponse: String = "",
    val activeToolStatus: String? = null,
    val isLoading: Boolean = false,
    val errorMessage: String? = null
)

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

    private val session: AgentSession = runner.getOrCreateSession(sessionId)

    private val _uiState = MutableStateFlow(AgentUiState())
    val uiState: StateFlow<AgentUiState> = _uiState.asStateFlow()

    fun sendMessage(userText: String) {
        _uiState.update {
            it.copy(
                messages = it.messages + userText,
                currentResponse = "",
                activeToolStatus = null,
                isLoading = true,
                errorMessage = null
            )
        }

        viewModelScope.launch {
            val content = Content.builder().text(userText).build()
            session.runAsync(content)
                .catch { e ->
                    val message = when {
                        e is GenAiException && e.errorCode == GenAiException.ErrorCode.MAX_TURNS_EXCEEDED ->
                            "Agent exceeded the maximum reasoning turns allowed."
                        e is GenAiException && e.errorCode == GenAiException.ErrorCode.NOT_AVAILABLE ->
                            "On-device AI is currently unavailable."
                        e is GenAiException && e.errorCode == GenAiException.ErrorCode.BUSY ->
                            "On-device AI is busy. Please try again."
                        else -> e.localizedMessage ?: "Agent error"
                    }
                    _uiState.update {
                        it.copy(
                            isLoading = false,
                            activeToolStatus = null,
                            errorMessage = message
                        )
                    }
                }
                .collect { event ->
                    when (event) {
                        is AgentEvent.TextMessage -> {
                            _uiState.update {
                                it.copy(
                                    currentResponse = if (event.isPartial) {
                                        it.currentResponse + event.text
                                    } else {
                                        event.text.ifEmpty { it.currentResponse }
                                    },
                                    activeToolStatus = null
                                )
                            }
                        }
                        is AgentEvent.FunctionCall -> {
                            _uiState.update {
                                it.copy(
                                    activeToolStatus =
                                        "Executing ${event.name}..."
                                )
                            }
                        }
                        is AgentEvent.FunctionResponse -> {
                            _uiState.update {
                                it.copy(
                                    activeToolStatus =
                                        "Received data from ${event.name}"
                                )
                            }
                        }
                        else -> {}
                    }
                }

            // Finalize message once stream completes
            _uiState.update {
                it.copy(
                    messages = it.messages + it.currentResponse,
                    currentResponse = "",
                    activeToolStatus = null,
                    isLoading = false
                )
            }
        }
    }

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

استخراج الرموز المميّزة للنص مباشرةً

بالنسبة إلى واجهات المحادثة التي لا تتطلّب عرض تفاصيل تنفيذ الأداة بشكل منفصل في واجهة المستخدم، استخدِم دالة الإضافة textTokens() في واجهة Flow<AgentEvent>:

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

val content = Content.builder().text(userText).build()
session.runAsync(content)
    .textTokens()
    .collect { token ->
        appendTokenToChatBubble(token)
    }

العرض في Jetpack Compose

استخدِم حالة AgentUiState في دالة مركّبة لعرض النص الذي يتم بثه ونشاط الأداة المباشر:

package com.example.ai.agent.ui

import androidx.compose.foundation.layout.*
import androidx.compose.foundation.lazy.LazyColumn
import androidx.compose.foundation.lazy.items
import androidx.compose.material3.*
import androidx.compose.runtime.*
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp

@Composable
fun AgentChatScreen(
    viewModel: ChatViewModel,
    modifier: Modifier = Modifier
) {
    val state by viewModel.uiState.collectAsState()
    var inputText by remember { mutableStateOf("") }

    Column(modifier = modifier.fillMaxSize().padding(16.dp)) {
        LazyColumn(
            modifier = Modifier.weight(1f).fillMaxWidth(),
            verticalArrangement = Arrangement.spacedBy(8.dp)
        ) {
            items(state.messages) { message ->
                Card(modifier = Modifier.fillMaxWidth()) {
                    Text(text = message, modifier = Modifier.padding(12.dp))
                }
            }

            if (state.activeToolStatus != null) {
                item {
                    Text(
                        text = state.activeToolStatus ?: "",
                        style = MaterialTheme.typography.bodySmall,
                        color = MaterialTheme.colorScheme.secondary
                    )
                }
            }

            if (state.currentResponse.isNotEmpty()) {
                item {
                    Card(
                        colors = CardDefaults.cardColors(
                            containerColor =
                                MaterialTheme.colorScheme.surfaceVariant
                        ),
                        modifier = Modifier.fillMaxWidth()
                    ) {
                        Text(
                            text = state.currentResponse,
                            modifier = Modifier.padding(12.dp)
                        )
                    }
                }
            }
        }

        Row(
            modifier = Modifier.fillMaxWidth().padding(top = 8.dp),
            horizontalArrangement = Arrangement.spacedBy(8.dp)
        ) {
            TextField(
                value = inputText,
                onValueChange = { inputText = it },
                modifier = Modifier.weight(1f),
                placeholder = { Text("Ask about an order...") }
            )
            Button(
                onClick = {
                    if (inputText.isNotBlank()) {
                        viewModel.sendMessage(inputText)
                        inputText = ""
                    }
                },
                enabled = !state.isLoading
            ) {
                Text("Send")
            }
        }
    }
}

الخطوات التالية

• تعرَّف على كيفية تحديد الأدوات في مقالة تحديد الأدوات.
• إدارة ذاكرة الجلسة والتعامل مع عمليات التدوير في إدارة الجلسات ومراحل النشاط