راهنماها

ساختن برنامه‌های Android هوشمند: گردش کارهای عامل‌گرا در برنامه

مدت‌زمان مطالعه: ۹ دقیقه
مشاهده نمایه Jolanda Verhoef
Jolanda Verhoef مهندس روابط توسعه‌دهندگان

به مجموعه پست‌های وبلاگ «ساخت برنامه‌های هوشمند Android» خوش آمدید. در این مجموعه، یک برنامه Android ساده را به تجربه‌ای شخصی‌سازی‌شده، هوشمند، و عامل‌گرا تبدیل می‌کنید. در پست قبلی ما، با نحوه اتصال به سیستم هوشمند بااستفاده از AppFunctions آشنا شدید.

در این پست، با نحوه ساختن گردش‌های کار عامل‌گرای درون‌برنامه خودکار که در فضای ابری اجرا می‌شوند آشنا خواهید شد.

گاهی اوقات یک تکلیف برای یک جلسه دستگاه بسیار پیچیده است. برای مثال، رزرو کردن برنامه سفر کامل برای تعطیلات شامل هماهنگ کردن زمان پرواز، انتخاب اتاق هتل، رزرو کردن بلیت موزه، و برنامه‌ریزی رزرو رستوران است. اگر این فرایند چندمرحله‌ای را مستقیماً در دستگاه همراه اجرا کنید، ممکن است برنامه بسته شود و پیشرفتتان را ازدست بدهید. مدیریت کردن همه این مراحل و اطلاعات کاربری API در تلفن نیز به‌سرعت پیچیده می‌شود.

برای این گردش‌های کار چندمرحله‌ای طولانی‌مدت، می‌توانید از پس‌بست سفارشی خودمیزبان استفاده کنید. بخش پشتیبان، عامل‌های رزرو را در پس‌زمینه اجرا می‌کند، درحالی‌که برنامه Android به جلسه متصل می‌شود، پیشرفت را تجسم می‌کند، و فقط درصورت لزوم ورودی کاربر را درخواست می‌کند.

استفاده از باطن عامل‌گرا با میزبانی ابری چند مزیت دارد:

  • اجرا در پس‌زمینه: نمایندگان رزرو به‌طور مستقل در فضای ابری اجرا می‌شوند، بنابراین اگر برنامه تلفن همراه به پس‌زمینه برود یا اتصال اینترنت قطع شود، پیشرفت هرگز ازبین نمی‌رود.
  • سازمان‌دهی پیچیده چندعاملی: یک عامل هماهنگ‌کننده می‌تواند رزروها را به زیرعامل‌های تخصصی واگذار کند و وابستگی‌های بین آن‌ها را مدیریت کند.
  • ارائه میانای کاربر مستقل از کارخواه: باطن ساختار میانجی را به‌صورت پویا توصیف می‌کند و به شما امکان می‌دهد چیدمان میانای کاربر را بدون انتشار نسخه کارخواه جدید به‌روز کنید.
booking-assistant.png
دستیار رزرو همه پیشرفت‌های رزرو را نشان می‌دهد که براساس نوع رویداد سازمان‌دهی شده‌اند.

با درنظر گرفتن این مزایا، دستیار رزرو را به Jetpacker اضافه کردیم که پروازها، هتل‌ها، موزه‌ها، و رزرو رستوران‌ها را هماهنگ می‌کند. بیایید ببینیم چگونه یک سیستم چندعاملی را که توسط Agent Development Kit (ADK) پشتیبانی می‌شود، با پروتکل Agent-User Interaction (AG-UI) و پروتکل Agent-to-User Interface (A2UI) هماهنگ کردیم تا کارت‌های تعاملی را به‌صورت بومی در Jetpack Compose ارسال و نمایش دهیم.

تقویت گردش‌های کار پیچیده با عامل‌های ADK

به‌جای هماهنگ کردن جریان سازمان‌دهی به‌صورت دستی بااستفاده از نقاط پایانی REST سفارشی یا سوکت‌های وب پیچیده، می‌توانید از Agent Development Kit (ADK) استفاده کنید. با ADK، می‌توانید عامل‌ها را تعریف کنید و آن‌ها را به ابزارهای تابع python مجهز کنید تا پایگاه‌های داده را پُرسمان کنند و رزروها را اجرا کنند.

diagram.png
برنامه Android داده‌های برنامه سفر فعلی را به سرور ارسال می‌کند. عامل هماهنگ‌کننده انتخاب می‌کند کدام عامل‌های فرعی را راه‌اندازی کند. هر زیرنماینده نتایج خود را به صف جلسه مشترکی ارائه می‌دهد که نتایج را به برنامه Android برمی‌گرداند.

در اینجا نحوه تعریف یک عامل ساده و اجرای آن بااستفاده از ADK آورده شده است:

# server/main.py

# Note: ADK supports many different coding languages. For now, we use the Python version as it includes support for A2UI which we'll use later in this blog post.

from google.adk import Agent
from google.adk.runners import InMemoryRunner
from google.adk.tools import FunctionTool

# Define custom tools to interact with database
def search_flights(destination: str, date: str) -> list[str]:
    # In production, here you would query our flight database and return dynamic results
    return ["10:00 AM", "2:00 PM"]

def reserve_flight(flight_time: str) -> str:
    # In production, here you would save the reservation transaction
    return "Reserved flight at " + flight_time

# Instantiate the booking agent with specialized tools
flight_agent = Agent(
    name="Flight Booker",
    model="gemini-3.1-flash-lite",
    instruction="Help the user search for flights and book a reservation.",
    tools=[
        FunctionTool(search_flights),
        FunctionTool(reserve_flight, require_confirmation=True)
    ]
)

# Run the agent in memory using a session ID
runner = InMemoryRunner(flight_agent)
async for event in runner.run_async(user_id=user_id, session_id=session_id):
    if event.content:
        print("Agent said:", event.content)

وقتی عاملی را بااستفاده از این راه‌اندازی اجرا می‌کنید، ADK مراحل اجرا را برای شما مدیریت می‌کند. این کلاس به‌طور خودکار بافت مکالمه را ردیابی می‌کند، پیام‌ها را بین کاربر و مدل هدایت می‌کند، و ابزارهای ثبت‌شده را زمانی که مدل درخواست می‌کند اجرا می‌کند. این به شما امکان می‌دهد تا بر نوشتن منطق رویه‌ای تمیز تمرکز کنید، درحالی‌که چارچوب هماهنگ‌سازی را در پس‌زمینه مدیریت می‌کند.

web_debug.png


برای متصل کردن این عامل باطن به برنامه Jetpacker، سرور به روشی برای جاری‌سازی به‌روزرسانی‌ها به‌صورت هم‌زمان در دستگاه نیاز دارد که بااستفاده از پروتکل AG-UI انجام می‌شود. همچنین نماینده به روشی ساختاریافته برای توصیف و به‌روزرسانی پویای مؤلفه‌های تعاملی (مانند انتخابگرهای گزینه و شبکه‌های صندلی) در تلفن نیاز دارد، که در اینجا پروتکل A2UI وارد عمل می‌شود.

استانداردسازی ارتباط عامل-کارخواه با AG-UI

اجرای عامل‌ها در فضای ابری و ارائه میانای کاربر در Android به کانال ارتباطی استاندارد نیاز دارد. برای این کار، از پروتکل AG-UI استفاده خواهید کرد.

‫AG-UI یک پروتکل لایه انتقال دوطرفه است که انواع پیام بین عامل‌ها و کلاینت‌های میانای کاربر را استانداردسازی می‌کند. نماینده می‌تواند مشتری را از رویدادهای چرخه حیات، پیام‌های نوشتاری، فراخوانی‌های ابزار، و مدیریت وضعیت مطلع کند. کارخواه نیز به‌نوبه خود می‌تواند پیام‌های نوشتاری کاربر، نتایج فراخوانی ابزار، و رویدادهای کنش سفارشی را به نماینده ارسال کند.

در سمت سرور، به‌روزرسانی‌ها را به‌صورت «رویدادهای استاندارد ارسال‌شده از سرور» (مانند event: TEXT_MESSAGE_CONTENT حاوی دلتای JSON) ارائه می‌دهد. در Android، کیت توسعه نرم‌افزار Kotlin به این جاری‌سازی گوش می‌دهد و به‌طور خودکار محموله‌ها را به رویدادهای کارخواه ایمن ازنظر نوع نگاشت می‌کند:

// BookingAssistantViewModel.kt

import com.agui.client.agent.HttpAgent
import com.agui.client.agent.HttpAgentConfig
import com.agui.core.types.RunAgentInput
import com.agui.core.types.UserMessage
import com.agui.core.types.TextMessageStartEvent
import com.agui.core.types.TextMessageContentEvent
import com.agui.core.types.TextMessageEndEvent

val config = HttpAgentConfig(
    agentId = "booking-assistant",
    threadId = threadId,
    url = "https://<your-backend-url>"
)
val agent = HttpAgent(config, httpClient)

// Set up the input with the session thread and user instruction
val input = RunAgentInput(
    threadId = threadId,
    runId = runId,
    messages = listOf(UserMessage("Book a flight to Paris"))
)

// Run the agent flow and collect lifecycle events
agent.runAgentObservable(input)
    .collect { event ->
        when (event) {
            is TextMessageStartEvent -> { /* ... */ }
            is TextMessageContentEvent -> { /* ... */ }
            is TextMessageEndEvent -> {
                // Handle the completed message
            }
        }
    }

سپس می‌توانید میانای کاربری بنویسید تا این انواع مختلف رویدادهای استانداردشده AG-UI را پرداز بزند. این کار تجربه نمونه اولیه «روبات گپ» را به شما می‌دهد:

manage_bookings.png
یک میانای ساده که به کاربر اجازه می‌دهد با دستیار گپ بزند.

Letting the agent speak UI with A2UI

روبات‌های گپ سنتی معمولاً نوشتار ساده یا پایه‌بارهای JSON سفارشی را برمی‌گردانند. هنگام ساختن میاناهای پیچیده، برنامه کارخواه باید این محموله‌های داده را تجزیه کند و آن‌ها را به صفحه‌های ازپیش‌ساخته‌شده خاصی نگاشت کند. این امر وابستگی ایجاد می‌کند: هربار که ویژگی جدیدی اضافه می‌کنید، چیدمان را تغییر می‌دهید، یا از تعامل کاربر جدیدی پشتیبانی می‌کنید، باید هم عامل پس‌نهایی و هم برنامه تلفن همراه را به‌روز کنید. این کار مستلزم انتشار به‌روزرسانی برنامه و منتظر ماندن برای نصب آن توسط کاربران است.

برای حل این مشکل، از پروتکل A2UI استفاده کنید. A2UI به نماینده‌ها اجازه می‌دهد مؤلفه‌های واسط کاربر را برای ارائه پویا در کارخواه توصیف کنند. برنامه کارخواه کاتالوگی از مؤلفه‌هایی را که پشتیبانی می‌کند اعلام می‌کند و سرور یک پایه‌بار JSON ارسال می‌کند که چیدمان و ویژگی‌های مؤلفه را مشخص می‌کند:

{
  "version": "v0.9",
  "updateComponents": {
    "surfaceId": "Flight Reservation",
    "components": [
      {
        "id": "flight_option_picker",
        "component": "InteractiveOptionPicker",
        "properties": {
          "prompt": "Select a flight time:",
          "options": [
            "10:00 AM",
            "2:00 PM"
          ],
          "selectedIdx": null,
          "confirmBtnText": "Confirm Flight"
        }
      }
    ]
  }
}

سرور مشخص می‌کند که کدام مؤلفه‌های کاتالوگ همراه با مقادیر ویژگی فعال آن‌ها ارائه شوند، و جزئیات پیاده‌سازی بصری کارخواه را به‌طور تمیز از وضعیت گردش کار نماینده جدا می‌کند.

درحال طراحی طرح‌واره واسط کاربر پسین

برای اینکه نماینده بتواند این محموله‌های JSON را به‌درستی تولید کند، باید بداند کدام مؤلفه‌ها دردسترس هستند و چه ویژگی‌هایی را می‌پذیرند.

برای انجام این کار، از ادغام ADK A2UI استفاده کنید. به‌جای نوشتن دستی دستورالعمل‌های پیام‌واره برای هر مؤلفه در کاتالوگ ما، A2uiSchemaManager طرح‌واره‌های JSON و دستورالعمل‌های چیدمان آن‌ها را مستقیماً در پیام‌واره سیستم کامپایل می‌کند. این کار باعث می‌شود مدل ساختار دقیق و قوانین قالب‌بندی را که باید برای تولید بارداده‌های معتبر A2UI دنبال کند یاد بگیرد:

# server/main.py

from a2ui.schema.manager import A2uiSchemaManager
from a2ui.schema.constants import VERSION_0_9
from a2ui.schema.catalog import CatalogConfig
from a2ui.basic_catalog.provider import BasicCatalog

# Initialize A2UI Schema Manager with custom booking component catalog
schema_manager = A2uiSchemaManager(
    version=VERSION_0_9,
    catalogs=[
        BasicCatalog.get_config(version=VERSION_0_9),
        CatalogConfig.from_path(
            name="https://example.com/catalogs/booking_assistant/v1/catalog.json",
            catalog_path="booking_catalog.json"
        )
    ]
)

# Compile prompt instructions including the A2UI JSON schema
A2UI_SYSTEM_INSTRUCTION = schema_manager.generate_system_prompt(
    role_description="You are a helpful travel booking assistant.",
    ui_description="Use InteractiveOptionPicker for choices, SeatSelectionPicker for seat selection...",
    include_schema=True,
    include_examples=True,
    allowed_components=["InteractiveOptionPicker", "SeatSelectionPicker", "BookingStatus"]
)

با این دستورالعمل سیستم تولیدشده، مدل زبانی بزرگ در طرح‌بندی طرح‌واره زمینه‌سازی می‌شود و دقیقاً می‌داند که چگونه به‌روزرسانی‌های مؤلفه را که کارخواه Android قادر به ارائه آن است فرمول‌بندی کند.

پرداز داخلی A2UI با Jetpack Compose

برای پردازش این درخت‌های مؤلفه به‌صورت بومی در Android، از کتابخانه جدید Jetpack Compose A2UI Renderer استفاده کنید.

ابتدا، وابستگی‌ها را به فایل build.gradle.kts واحد اضافه کنید:

// android/feature/trip/booking_assistant/build.gradle.kts
dependencies {
    implementation("androidx.a2ui:a2ui-model:1.0.0-alpha01")
    implementation("androidx.a2ui.compose:compose-runtime:1.0.0-alpha01")
    implementation("androidx.a2ui.compose:compose-ui:1.0.0-alpha01")
    implementation("androidx.compose.material3:material3-a2ui:1.0.0-alpha01")
}

هر کلاس مؤلفه در کاتالوگ (مانند BookingStatusComponent) نحوه نگاشت ویژگی‌های دریافتی از بار JSON به تابع ترکیب‌پذیر Jetpack Compose را تعریف می‌کند.

ثبت کردن اجزای سفارشی در کاتالوگ:

// CustomBookingAssistantCatalog.kt

import androidx.a2ui.compose.ui.A2uiCatalog

fun bookingAssistantCatalog(): A2uiCatalog {
    return A2uiCatalog(
        catalogId = "https://example.com/catalogs/booking_assistant/v1/catalog.json",
        components = listOf(
            InteractiveOptionPickerComponent(),
            SeatSelectionPickerComponent(),
            BookingStatusComponent()
        )
    )
}

نکته: Jetpacker مؤلفه‌های سفارشی (InteractiveOptionPicker، SeatSelectionPicker، BookingStatus) را که برای جریان‌های رزرو سفارشی‌سازی شده‌اند پیاده‌سازی می‌کند. اگر نماینده شما از عناصر استاندارد (مانند نوشتار، کارت، دکمه، ردیف، ستون، چارگوش انتخاب، و انتخابگر تاریخ-زمان) استفاده می‌کند، material3-a2ui همچنین materialA2uiBasicCatalogV1(...) را ارائه می‌دهد که پیاده‌سازی‌های آماده برای استفاده Material 3 را بدون نیاز به نوشتن مؤلفه‌های سفارشی دراختیارتان قرار می‌دهد.

توجه: برای هم‌راستا نگه داشتن کارخواه برنامه همراه و پس‌زمینه، هر دو به یک شناسه تعریف کاتالوگ (https://example.com/catalogs/booking_assistant/v1/catalog.json) متکی هستند. اگر ویژگی‌هایی را در کاتالوگ پس‌زمینه اضافه یا اصلاح کنید، باید شماره نسخه را افزایش دهید و کلاس مؤلفه Kotlin منطبق را به‌روز کنید تا از خطاهای تجزیه جلوگیری شود.

در BookingAssistantViewModel، پیام‌های A2UI را بااستفاده از A2uiMessageProcessor پردازش کنید و سطوح فعال ما را به‌روز کنید:

// BookingAssistantViewModel.kt
import androidx.lifecycle.ViewModel
import androidx.a2ui.model.processor.A2uiSurfaceModel
import androidx.a2ui.compose.ui.A2uiMessageProcessor
import kotlinx.coroutines.flow.StateFlow

class BookingAssistantViewModel : ViewModel() {
    private val messageProcessor = A2uiMessageProcessor(
        catalogs = listOf(bookingAssistantCatalog())
    )
    val activeSurfaces: StateFlow<List<A2uiSurfaceModel>> = messageProcessor.activeSurfaces
    
    init {
        viewModelScope.launch(Dispatchers.Default) { processor.collectMessages() }
    }

    // ...
}

در صفحه Compose، این سطوح را جمع‌آوری کنید و هرکدام را بااستفاده از A2uiSurface ترکیب‌پذیر رسمی از androidx.compose.material3:material3-a2ui رندر کنید. ‫A2uiSurface به‌طور خودکار مشاهده وضعیت مؤلفه واکنشی، نشانگرهای بار کردن Material 3، بازگشت‌های خطا، و انتقال‌های پویانمایی‌شده بین به‌روزرسانی‌ها را مدیریت می‌کند:

// BookingAssistantScreen.kt
import androidx.compose.runtime.Composable
import androidx.compose.runtime.collectAsState
import androidx.compose.foundation.lazy.LazyColumn
import androidx.compose.foundation.lazy.items
import androidx.compose.material3.a2ui.A2uiSurface

@Composable
fun BookingAssistantScreen(
    viewModel: BookingAssistantViewModel,
    modifier: Modifier = Modifier
) {
    val activeSurfaces by viewModel.activeSurfaces.collectAsState()
    LazyColumn(
        modifier = modifier.fillMaxWidth(),
        verticalArrangement = Arrangement.spacedBy(16.dp)
    ) {
        items(activeSurfaces) { surfaceModel ->
            Card(modifier = Modifier.fillMaxWidth()) {
                A2uiSurface(
                    surfaceModel = surfaceModel,
                    modifier = Modifier.fillMaxWidth().wrapContentHeight()
                )
            }
        }
    }
}

اکنون چندین سطح میانای کاربر را خواهید دید که توسط عامل ما درحال اجرا در پس‌زمینه تولید شده‌اند:

booking-assistant.png
دستیار رزرو با طراحی خوب که برای تعامل با کاربر به‌جای نوشتار به میانای کاربر متکی است.

درحال جمع‌بندی کردن

با میزبانی گردش‌های کاری عامل در فضای ابری و استفاده هم‌زمان از پروتکل‌های AG-UI و A2UI، می‌توانیم میاناهای Android پویا و بومی بسازیم که مستقیماً توسط مدل‌های هوش مصنوعی هدایت می‌شوند. AG-UI کانال جاری‌سازی دوطرفه هم‌زمان را برای پیام‌ها و رویدادهای چرخه حیات ایجاد می‌کند، درحالی‌که A2UI به عامل ابری امکان می‌دهد تا مؤلفه‌های میانای کاربر تعاملی را به‌طور پویا توصیف کند و برنامه کارخواه را کاملاً از منطق هماهنگ‌سازی گام‌به‌گام پس‌بک جدا نگه دارد.

کد منبع کامل Jetpacker را در GitHub بررسی کنید و ویدیو ساخت برنامه‌های هوشمند Android با هوش مصنوعی Google را تماشا کنید تا درباره نحوه ادغام گردش‌های کاری عامل‌گرا مستقیماً در برنامه‌تان بیشتر بدانید.

بخش‌های دیگر این مجموعه پست وبلاگ را بررسی کنید:
▪️ بخش ۱: معرفی برنامه و نمای کلی سطح بالا.
📱 بخش ۲: هوش درون‌دستگاهی. با GenAI API در ML Kit و Gemini Nano آشنا شوید تا ویژگی‌های متمرکز بر حریم خصوصی مانند خلاصه کردن برنامه سفر، تجزیه رسید، و پردازش صوتی محلی را بسازید.
☁️ بخش ۳: استدلال ترکیبی و ابری. با نحوه استفاده از Firebase AI Logic برای زمینه‌سازی پاسخ‌های مدل زبانی بزرگ در داده‌های دنیای واقعی مانند Google Maps و بافت وب آشنا شوید.
⚙️ بخش ۴: ادغام سیستم. ادغام با سیستم هوش Android بااستفاده از AppFunctions.
🤖 بخش ۵ (این پست!): گردش کارهای عامل‌گرا درون‌برنامه. برنامه را با دستیارهای رزرو سرتاسر مجهز به A2UI و ADK گسترش دهید.

به اطلاعات بیشتر درباره «توسعه Android» علاقه دارید؟ «توسعه‌دهندگان برنامه Android» را در YouTube یا LinkedIn دنبال کنید!

همه تکه‌کدهای این پست وبلاگ از این اعلامیه حق نشر پیروی می‌کنند:

Copyright 2026 Google LLC.
SPDX-License-Identifier: Apache-2.0
نویسنده:
ادامه خواندن