بدء استخدام سير العمل المستند إلى الوكلاء

توضّح هذه الصفحة كيفية إعداد مشروع Android وضبط مكتبة genai-agent وإنشاء أول وكيل على الجهاز فقط.

المتطلبات الأساسية

قبل إنشاء سير عمل مستند إلى الوكلاء باستخدام Gemini Nano، تأكَّد من أنّ بيئتك تستوفي المتطلبات التالية:

ضبط إعدادات مشروعك

أضِف اعتمادية genai-agent إلى ملف build.gradle.kts الخاص بالوحدة:

dependencies {
    // Gemini Nano agentic workflows
    implementation("com.google.mlkit:genai-agent:1.0.0-alpha1")

    // Optional: Only required when defining tools using Android AppFunctions
    implementation("androidx.appfunctions:appfunctions:1.0.0-alpha13")
    ksp("androidx.appfunctions:appfunctions-compiler:1.0.0-alpha13")
}

إنشاء وكيلك الأول

يتضمّن الوكيل مكوّنَين أساسيَّين:

  • تعريف الوكيل: التعليمات والقيود التي تضبط سلوك الوكيل
  • مشغّل الوكيل: محرّك التنفيذ الذي يتواصل مع AICore ويدير المحادثات

1. ضبط الوكيل والمشغّل

يوضّح عينة تعليمات برمجية التالي كيفية تحديد وكيلك باستخدام تعليمات النظام وإعداد فئة AgentRunner:

import com.google.mlkit.genai.agent.Agent
import com.google.mlkit.genai.agent.AgentRunner

// 1. Build the agent configuration
val agent = Agent.builder()
    .setName("Assistant")
    .setInstructions("You are a helpful on-device assistant.")
    .build()

// 2. Initialize the runner
val runner = AgentRunner(agent)

2. إجراء محادثة

تحتفظ المحادثات المتعدّدة الجولات بسجلّ الحوار على مستوى الجولات باستخدام مثيل AgentSession. أضِف نص الطلب في عنصر Content واجمع الردّ الذي يتم بثه:

import android.util.Log
import androidx.lifecycle.lifecycleScope
import com.google.mlkit.genai.agent.textTokens
import com.google.mlkit.genai.prompt.Content
import kotlinx.coroutines.launch

// Create or retrieve a conversation session
val session = runner.getOrCreateSession("chat_session")

val prompt = Content.builder()
    .text("Hello! Can you help me organize my day?")
    .build()

// Collect streamed tokens in a coroutine
lifecycleScope.launch {
    session.runAsync(prompt)
        .textTokens()
        .collect { token ->
            Log.d("Agent", token)
        }
}

بالنسبة إلى الطلبات التي لا تتطلب الاحتفاظ بسجلّ المحادثات، يمكنك استدعاء طريقة runner.runSingleTurnAsync(prompt) مباشرةً:

lifecycleScope.launch {
    runner.runSingleTurnAsync(prompt)
        .textTokens()
        .collect { token ->
            Log.d("Agent", token)
        }
}

3- حذف الموارد

تنفّذ الفئة AgentRunner واجهة AutoCloseable. عند تدمير مكوّن ViewModel أو Activity، يجب إغلاق المشغّل لإغلاق الجلسات النشطة وإلغاء الكوروتينات في الخلفية:

runner.close()

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

  • إضافة إمكانات باستخدام الأدوات: يمكنك منح وكيلك القدرة على اتخاذ الإجراءات أو طلب بيانات التطبيق باستخدام Android AppFunctions. يُرجى الاطّلاع على تحديد الأدوات.
  • الحفاظ على الجلسات أثناء تدوير الشاشة: تعرَّف على كيفية الاحتفاظ بمثيل AgentSession داخل فئة ViewModel أثناء تغييرات الإعدادات في مقالة إدارة الجلسات ومراحل النشاط.
  • الربط بـ Compose: يمكنك بث الأحداث وعرض فقاعات المحادثة التفاعلية في بث الأحداث ودمج واجهة المستخدم.