إنشاء تطبيق Google Chat باستخدام وكيل Agent2UI

توضّح هذه الصفحة كيفية إنشاء إضافة Google Workspace تعمل في Google Chat وتتفاعل مع وكيل مستند إلى الذكاء الاصطناعي يستخدم بروتوكول Agent2UI (A2UI). يمكنك تطوير الوكيل باستخدام حزمة تطوير الوكيل (ADK) واستضافته في محرك وكلاء Vertex AI.

تستطيع وكلاء الذكاء الاصطناعي بشكل مستقل إدراك البيئة المحيطة بهم، والاستدلال المنطقي، وتنفيذ إجراءات معقّدة ومتعددة الخطوات لتحقيق هدف محدّد. في هذا البرنامج التعليمي، ستنشئ وكيل ذكاء اصطناعي أساسيًا يعرض معلومات ثابتة عن الملف الشخصي تم استردادها من إحدى الأدوات.

تتيح أداة A2UI لوكلاء الذكاء الاصطناعي إنشاء واجهات مستخدم تفاعلية وغنية بصريًا ومتكيّفة يتم عرضها بشكل أصلي. يمكنك بعد ذلك التركيز على منطق وكلاء الذكاء الاصطناعي، وليس واجهات المستخدم.

  • يردّ وكيل A2UI على المستخدم برسالة تتضمّن نصًا وبطاقة تحتوي على اسم الملف الشخصي والصورة وزر LinkedIn.
    الشكل 1. يردّ وكيل A2UI على المستخدم بنص وبطاقة تحتوي على الاسم والصورة وزر LinkedIn.
  • تم تعديل وكيل A2UI لعرض عنوان الملف الشخصي أيضًا.
    الشكل 2. تم تعديل وكيل A2UI لعرض عنوان الملف الشخصي أيضًا.
  • يردّ وكيل A2UI على المستخدم برسالة تعرض اسم الملف الشخصي في البطاقة.
    الشكل 3. يردّ وكيل A2UI على المستخدم برسالة تعرض اسم الملف الشخصي في البطاقة.

يوضّح المخطّط التالي بنية النظام ونمط المراسلة:

بنية تطبيق Chat تم تنفيذه باستخدام وكيل الذكاء الاصطناعي A2UI

في المخطّط البياني، يتفاعل المستخدم مع تطبيق دردشة تم تنفيذه باستخدام وكيل A2UI، ويكون تدفّق المعلومات على النحو التالي:

  1. يرسل مستخدم رسالة إلى تطبيق Chat، إما في رسالة مباشرة أو في مساحة Chat.
  2. تتلقّى منطق تطبيق Chat الذي يتم تنفيذه إما في Apps Script أو كخادم ويب مع نقاط نهاية HTTP الرسالة وتعالجها.
  3. يتلقّى وكيل A2UI المستضاف باستخدام "محرك وكلاء Vertex AI" التفاعل ويعالجه.
  4. يمكن للتطبيق Chat أو وكيل الذكاء الاصطناعي أن يتكامل مع خدمات Google Workspace، مثل "تقويم Google" أو "جداول بيانات Google"، أو خدمات Google الأخرى، مثل "خرائط Google" أو YouTube.
  5. ينشئ تطبيق Chat الردود التكيّفية ويرسلها بشكل غير متزامن، وذلك باستخدام Google Chat API لإعلام وكيل الذكاء الاصطناعي بمستوى تقدّمه.
  6. يتم تسليم الردود إلى المستخدم.

الأهداف

  • إعداد البيئة
  • نشر وكيل A2UI
  • نشر تطبيق Chat
  • ضبط إعدادات تطبيق Chat
  • اختبِر تطبيق Chat.

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

إعداد البيئة

تفعيل واجهات Google Cloud APIs

قبل استخدام واجهات Google APIs، عليك تفعيلها في مشروع على Google Cloud. يمكنك تفعيل واجهة برمجة تطبيق واحدة أو أكثر في مشروع واحد على Google Cloud.

إعداد شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth

تتطلّب جميع التطبيقات التي تستخدم OAuth 2.0 إعداد شاشة موافقة. يؤدي ضبط شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth في تطبيقك إلى تحديد ما سيظهر للمستخدمين ومراجعي التطبيق، كما يؤدي إلى تسجيل تطبيقك لتتمكّن من نشره لاحقًا.

  1. في "وحدة تحكّم Google Cloud"، انتقِل إلى "القائمة" > Google Auth platform > العلامة التجارية.

    الانتقال إلى "هوية العلامة التجارية"

  2. إذا سبق لك ضبط Google Auth platform، يمكنك ضبط إعدادات "شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth" التالية في العلامة التجارية والجمهور والوصول إلى البيانات. إذا ظهرت لك الرسالة Google Auth platform لم يتم ضبطه بعد، انقر على البدء:
    1. ضمن معلومات التطبيق، في اسم التطبيق، أدخِل اسمًا للتطبيق.
    2. في حقل البريد الإلكتروني لدعم المستخدمين، اختَر عنوان بريد إلكتروني للدعم يمكن للمستخدمين التواصل معك من خلاله إذا كانت لديهم أسئلة حول موافقتهم.
    3. انقر على التالي.
    4. ضمن الجمهور، اختَر داخلي.
    5. انقر على التالي.
    6. ضمن معلومات الاتصال، أدخِل عنوان بريد إلكتروني يمكنك تلقّي إشعارات فيه بشأن أي تغييرات تطرأ على مشروعك.
    7. انقر على التالي.
    8. ضمن إنهاء، راجِع سياسة بيانات المستخدمين في خدمات Google API، وإذا كنت توافق عليها، ضَع علامة في المربّع أوافق على "سياسة بيانات المستخدمين في خدمات Google API".
    9. انقر على متابعة.
    10. انقر على إنشاء.
  3. يمكنك حاليًا تخطّي إضافة النطاقات. في المستقبل، عند إنشاء تطبيق لاستخدامه خارج مؤسسة Google Workspace، عليك تغيير نوع المستخدم إلى خارجي. بعد ذلك، أضِف نطاقات التفويض التي يتطلّبها تطبيقك. لمزيد من المعلومات، يُرجى الاطّلاع على الدليل الكامل حول ضبط موافقة OAuth.

إنشاء حساب خدمة في Google Cloud Console

أنشِئ حساب خدمة جديدًا بالدور Vertex AI User باتّباع الخطوات التالية:

Google Cloud Console

  1. في Google Cloud Console، انتقِل إلى "القائمة" > المشرف وإدارة الهوية وإمكانية الوصول > حسابات الخدمة.

    الانتقال إلى "حسابات الخدمة"

  2. انقر على إنشاء حساب خدمة.
  3. املأ تفاصيل حساب الخدمة، ثم انقر على إنشاء ومتابعة.
  4. اختياري: يمكنك منح أدوار لحساب الخدمة من أجل السماح بالوصول إلى موارد مشروعك على Google Cloud. لمزيد من التفاصيل، يُرجى الرجوع إلى منح إذن الوصول إلى الموارد وتغييره وإبطاله.
  5. انقر على متابعة.
  6. اختياري: أدخِل المستخدمين أو المجموعات التي يمكنها إدارة حساب الخدمة هذا وتنفيذ إجراءات فيه. لمزيد من التفاصيل، يُرجى الاطّلاع على إدارة انتحال هوية حساب الخدمة.
  7. انقر على تم. دوِّن عنوان البريد الإلكتروني لحساب الخدمة.

gcloud CLI

  1. أنشئ حساب الخدمة: 
    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
  --display-name="SERVICE_ACCOUNT_NAME"
  2. اختياري: يمكنك منح أدوار لحساب الخدمة من أجل السماح بالوصول إلى موارد مشروعك على Google Cloud. لمزيد من التفاصيل، يُرجى الرجوع إلى منح إذن الوصول إلى الموارد وتغييره وإبطاله.

يظهر حساب الخدمة في صفحة حساب الخدمة.

إنشاء مفتاح خاص

لإنشاء مفتاح خاص لحساب الخدمة وتنزيله، اتّبِع الخطوات التالية:

  1. في Google Cloud Console، انتقِل إلى "القائمة" > المشرف وإدارة الهوية وإمكانية الوصول > حسابات الخدمة.

    الانتقال إلى "حسابات الخدمة"

  2. اختَر حساب الخدمة.
  3. انقر على المفاتيح > إضافة مفتاح > إنشاء مفتاح جديد.
  4. اختَر JSON، ثمّ انقر على إنشاء.

    يتم إنشاء زوج المفتاح العام/الخاص وتنزيله على جهازك كملف جديد. احفظ ملف JSON الذي تم تنزيله باسم credentials.json في دليل العمل. هذا الملف هو النسخة الوحيدة من هذا المفتاح. للحصول على معلومات عن طريقة التخزين الآمن للمفتاح، راجِع إدارة مفاتيح حساب الخدمة.

  5. انقر على إغلاق (Close).

لمزيد من المعلومات حول حسابات الخدمة، يُرجى الاطّلاع على حسابات الخدمة في مستندات "إدارة الهوية وإمكانية الوصول" في Google Cloud.

نشر وكيل A2UI

  1. إذا لم يسبق لك إجراء ذلك، عليك إثبات ملكية حسابك على Google Cloud وإعداد Google Cloud CLI لاستخدام مشروعك على Google Cloud.

    gcloud auth application-default login
gcloud config set project PROJECT_ID
gcloud auth application-default set-quota-project PROJECT_ID

    استبدِل PROJECT_ID بمعرّف مشروعك على Cloud.

  2. نزِّل مستودع googleworkspace/add-ons-samples GitHub باستخدام هذا الزر:

    تنزيل المستودع

  3. في بيئة التطوير المحلية المفضّلة لديك، استخرِج ملف الأرشيف الذي تم تنزيله وافتح الدليل add-ons-samples/apps-script/chat/a2ui-ai-agent/a2ui.

    unzip add-ons-samples-main.zip
cd add-ons-samples/apps-script/chat/a2ui-ai-agent/a2ui

  4. أنشِئ حزمة جديدة في Cloud Storage مخصَّصة لعامل ADK.

    gcloud storage buckets create gs://CLOUD_STORAGE_BUCKET_NAME --project=PROJECT_ID --location=PROJECT_LOCATION

    غيِّر القيم في السلسلة على الشكل التالي:

    1. استبدِل CLOUD_STORAGE_BUCKET_NAME باسم حزمة فريد تريد استخدامه.
    2. استبدِل PROJECT_ID بمعرّف مشروعك على السحابة الإلكترونية.
    3. استبدِل PROJECT_LOCATION بموقع مشروعك على السحابة الإلكترونية.

  5. اضبط متغيرات البيئة التالية:

    export GOOGLE_GENAI_USE_VERTEXAI=true
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
export GOOGLE_CLOUD_LOCATION=PROJECT_LOCATION
export GOOGLE_CLOUD_STORAGE_BUCKET=CLOUD_STORAGE_BUCKET_NAME

    غيِّر القيم في السلسلة على الشكل التالي:

    1. استبدِل CLOUD_STORAGE_BUCKET_NAME باسم الحزمة التي أنشأتها.
    2. استبدِل PROJECT_ID بمعرّف مشروعك على السحابة الإلكترونية.
    3. PROJECT_LOCATION مع الموقع الجغرافي لمشروعك على السحابة الإلكترونية.

  6. تثبيت وكيل ADK ونشره من بيئة افتراضية

    python3 -m venv myenv
source myenv/bin/activate
poetry install --with deployment
python3 deployment/deploy.py --create

  7. استرداد معرّف الوكيل ستحتاج إليه لاحقًا عند إعداد تطبيق Chat.

    python3 deployment/deploy.py --list

إنشاء مشروع تطبيق Chat وإعداده

  1. انقر على الزر التالي لفتح مشروع A2UI AI Agent Quickstart في Apps Script.

    فتح المشروع

  2. انقر على نظرة عامة > رمز إنشاء نسخة إنشاء نسخة.

  3. في مشروع Apps Script، انقر على رمز إعدادات المشروع إعدادات المشروع > تعديل خصائص النص البرمجي > إضافة خاصية نص برمجي لإضافة خصائص النص البرمجي التالية:

    1. استبدِل REASONING_ENGINE_RESOURCE_NAME باسم مورد وكيل Vertex AI الذي تم نسخه في الخطوات السابقة.
    2. استبدِل SERVICE_ACCOUNT_KEY بمفتاح JSON من حساب الخدمة الذي تم تنزيله في الخطوات السابقة، مثل { ... }.

  4. انقر على حفظ مواقع النص البرمجي.

  5. في وحدة تحكّم Google Cloud، انتقِل إلى "القائمة" > إدارة الهوية وإمكانية الوصول > الإعدادات.

    الانتقال إلى إعدادات "إدارة الهوية وإمكانية الوصول" و"المشرف"

  6. في حقل رقم المشروع، انسخ القيمة.

  7. في مشروعك على "برمجة تطبيقات Google"، انقر على رمز إعدادات المشروع إعدادات المشروع.

  8. ضمن مشروع Google Cloud Platform (GCP)، انقر على تغيير المشروع.

  9. في رقم مشروع Google Cloud Platform، ألصِق رقم مشروع Google Cloud الذي نسخته في الخطوات السابقة.

  10. انقر على تحديد المشروع. تم ربط مشروع Cloud بمشروع "برمجة التطبيقات" الآن.

إنشاء عملية نشر تجريبية

تحتاج إلى معرّف نشر لمشروع Apps Script هذا، حتى تتمكّن من استخدامه في الخطوة التالية.

للحصول على رقم تعريف عملية نشر العنوان، اتّبِع الخطوات التالية:

  1. في مشروع "برمجة التطبيقات" لتطبيق Chat، انقر على نشر > اختبار عمليات النشر.
  2. ضمن رقم تعريف عملية نشر العنوان، انقر على رمز إنشاء نسخة نسخ.
  3. انقر على تم.

ضبط إعدادات تطبيق Chat

باستخدام عملية نشر Apps Script، اتّبِع الخطوات التالية لنشر تطبيق Google Chat بغرض الاختبار:

  1. في وحدة التحكّم، ابحث عن Google Chat API، ثم انقر على Google Chat API.
  2. انقر على إدارة.

  3. انقر على الإعداد وأعِدّ تطبيق Chat على النحو التالي:

    1. في حقل اسم التطبيق، أدخِل A2UI Quickstart.
    2. في الحقل عنوان URL للصورة الرمزية، أدخِل https://developers.google.com/workspace/add-ons/images/quickstart-app-avatar.png.
    3. في حقل الوصف، أدخِل A2UI Quickstart.
    4. ضمن الوظائف، اختَر الانضمام إلى المساحات والمحادثات الجماعية.
    5. ضِمن "إعدادات الربط"، اختَر مشروع "برمجة التطبيقات".
    6. في حقل رقم تعريف عملية النشر، ألصِق رقم تعريف عملية نشر Head الذي نسخته سابقًا.
    7. ضمن "إذن الوصول"، اختَر مستخدمون ومجموعات محدّدة في نطاقك، وأدخِل عنوان بريدك الإلكتروني.

  4. انقر على حفظ.

تطبيق Chat جاهز للردّ على الرسائل.

اختبار تطبيق Chat

لاختبار تطبيق Chat، افتح مساحة رسالة مباشرة باستخدام تطبيق Chat وأرسِل رسالة:

  1. افتح Google Chat باستخدام حساب Google Workspace الذي قدّمته عند إضافة نفسك كمختبِر موثوق به.

    الانتقال إلى Google Chat

  2. انقر على محادثة جديدة.
  3. في حقل إضافة مستخدم واحد أو أكثر، اكتب اسم تطبيق Chat.

  4. اختَر تطبيق Chat من النتائج. سيتم فتح رسالة مباشرة.

  5. في الرسالة المباشرة الجديدة مع التطبيق، اكتب Hello! واضغط على enter.

    يردّ تطبيق Chat برسالة تتضمّن نص تحية وبطاقة تحتوي على اسم الملف الشخصي والصورة وزر LinkedIn.

  6. عدِّل عملية تنفيذ وكيل A2UI لبدء عرض عنوان الملف الشخصي أيضًا.

    في بيئة التطوير المحلية، افتح الملف a2ui/agent.py وأزِل التعليق من السطر في الأداة الذي يضيف العنوان إلى البيانات التي يتم عرضها.

    apps-script/chat/a2ui-ai-agent/a2ui/a2ui/agent.py
    # Copyright 2026 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

"""A2UI agent."""

from google.adk.agents import LlmAgent
from google.adk.tools.tool_context import ToolContext
import json

# The schema for any A2UI message. This never changes.
from .a2ui_schema import A2UI_SCHEMA

def get_user_profile(tool_context: ToolContext) -> str:
    """Call this tool to get the current user profile."""
    return json.dumps({
        "name": "Pierrick Voulet",
        # "title": "DevRel Engineer @ Google Workspace | Gen AI & AI Agents & Agentic AI | Automation & Digital Transformation",
        "imageUrl": "https://io.google/2024/speakers/3ea87822-3160-4d54-89dd-57e185085f79_240.webp",
        "linkedin": "https://www.linkedin.com/in/pierrick-voulet/"
    })

AGENT_INSTRUCTION="""
You are a user profile assistant. Your goal is to help users get their profile information using a rich UI.

To achieve this, you MUST follow these steps to answer user requests:

1.  You MUST call the `get_user_profile` tool and extract all the user profile information from the result.
2.  You MUST generate a final a2ui UI JSON based on the user profile information extracted in the previous step."""

A2UI_AND_AGENT_INSTRUCTION = AGENT_INSTRUCTION + f"""

To generate a valid a2ui UI JSON, you MUST follow these rules:
1.  Your response MUST be in two parts, separated by the delimiter: `---a2ui_JSON---`.
2.  The first part is your conversational text response.
3.  The second part is a single, raw JSON object which is a list of A2UI messages.
4.  The JSON part MUST validate against the A2UI JSON SCHEMA provided below.

To represent the user profile, you MUST use the following A2UI message types:
1.  Buttons MUST be used to represent links (e.g., LinkedIn profile link).
2.  Image MUST be used to represent the user's profile picture.

---BEGIN A2UI JSON SCHEMA---
{A2UI_SCHEMA}
---END A2UI JSON SCHEMA---
"""

root_agent = LlmAgent(
    name="user_profile",
    model="gemini-2.5-flash",
    instruction=A2UI_AND_AGENT_INSTRUCTION,
    description="An agent that returns the current user profile.",
    tools=[get_user_profile]
)

  7. عدِّل حزمة ADK التي تم نشرها سابقًا باستخدام الإصدار الجديد من التنفيذ.

    python3 deployment/deploy.py --update --resource_id=RESOURCE_ID

    استبدِل RESOURCE_ID باسم مورد وكيل Vertex AI الذي تم نسخه في الخطوات السابقة.

  8. في الرسالة المباشرة مع التطبيق، اكتب Hello again! واضغط على enter.

    يردّ تطبيق Chat على الرسالة بنص وبطاقة تحتوي على عنوان الملف الشخصي.

لإضافة مختبِرين موثوق بهم والتعرّف على مزيد من المعلومات حول اختبار الميزات التفاعلية، يُرجى الاطّلاع على مقالة اختبار الميزات التفاعلية لتطبيقات Google Chat.

تحديد المشاكل وحلّها

عندما يعرض تطبيق أو بطاقة في Google Chat خطأً، تعرض واجهة Chat رسالة تفيد بأنّه "حدث خطأ". أو "تعذّر معالجة طلبك". في بعض الأحيان، لا تعرض واجهة مستخدم Chat أي رسالة خطأ، ولكن ينتج تطبيق Chat أو البطاقة نتيجة غير متوقّعة، على سبيل المثال، قد لا تظهر رسالة البطاقة.

على الرغم من أنّه قد لا تظهر رسالة خطأ في واجهة مستخدم Chat، تتوفّر رسائل خطأ وصفية وبيانات سجلّات لمساعدتك في إصلاح الأخطاء عند تفعيل تسجيل الأخطاء لتطبيقات Chat. للحصول على مساعدة في عرض الأخطاء وتصحيحها وتحديد المشاكل فيها، يُرجى الاطّلاع على تحديد مشاكل Google Chat وحلّها.

تَنظيم

لتجنُّب تحمّل رسوم في حسابك على Google Cloud مقابل الموارد المستخدَمة في هذا البرنامج التعليمي، ننصحك بحذف مشروع Cloud.

  1. في Google Cloud Console، انتقِل إلى صفحة إدارة الموارد. انقر على القائمة > إدارة الهوية وإمكانية الوصول والمشرف > إدارة الموارد.

    الانتقال إلى "إدارة الموارد"

  2. في قائمة المشاريع، اختَر المشروع الذي تريد حذفه، ثم انقر على حذف .
  3. في مربّع الحوار، اكتب رقم تعريف المشروع، ثم انقر على إيقاف لحذف المشروع.