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

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

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

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

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

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

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

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

  1. يرسل مستخدم رسالة إلى تطبيق Chat، إما في رسالة مباشرة أو في مساحة Chat.
  2. تتلقّى منطق تطبيق Chat الذي يتم تنفيذه إما في برمجة تطبيقات أو كخادم ويب مع نقاط نهاية HTTP الرسالة وتعالجها.
  3. يتلقّى وكيل الذكاء الاصطناعي A2UI المستضاف باستخدام Vertex AI Agent Engine التفاعل ويعالجه.
  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 API Console، انتقِل إلى القائمة > منصة Google Auth > العلامة التجارية.

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

  2. إذا سبق لك ضبط منصة Google Auth، يمكنك ضبط إعدادات شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth التالية في العلامة التجارية والجمهور والوصول إلى البيانات. إذا ظهرت لك رسالة لم يتم إعداد منصة Google Auth بعد، انقر على البدء:
    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، انتقِل إلى "القائمة" > المشرف وإدارة الهوية وإمكانية الوصول > حسابات الخدمة.

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

    تظهر الخطوات المتبقية في Google Cloud Console.

  2. اختَر مشروعًا على Google Cloud.
  3. انقر على إنشاء حساب خدمة.
  4. أدخِل اسم حساب خدمة ليتم عرضه في Google Cloud Console.
  5. إذا كنت لا تريد ضبط عناصر التحكّم في الوصول الآن، انقر على تم لإنهاء عملية إنشاء حساب الخدمة. لضبط عناصر التحكّم في الوصول الآن، انقر على إنشاء ومتابعة وانتقِل إلى الخطوة التالية.
  6. اختياري: يمكنك منح أدوار لحساب الخدمة من أجل السماح بالوصول إلى موارد مشروع على السحابة الإلكترونية على Google Cloud بالإضافة إلى موارد Google Workspace. لمزيد من التفاصيل، يُرجى الاطّلاع على إدارة الوصول إلى المشاريع والمجلدات والمؤسسات.
  7. انقر على متابعة.
  8. اختياري: أدخِل المستخدمين أو المجموعات التي يمكنها إدارة حساب الخدمة هذا وتنفيذ إجراءات فيه. لمزيد من التفاصيل، يُرجى الاطّلاع على انتحال هوية حساب الخدمة.
  9. انقر على تم للانتهاء من إنشاء حساب الخدمة.

    دوِّن عنوان البريد الإلكتروني لحساب الخدمة.

gcloud CLI

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

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

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

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

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

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

    تظهر الخطوات المتبقية في Google Cloud Console.

  2. اختَر مشروعًا على Google Cloud.
  3. انقر على عنوان البريد الإلكتروني لحساب الخدمة الذي تريد إنشاء مفتاح له.
  4. انقر على علامة التبويب المفاتيح.
  5. انقر على القائمة المنسدلة إضافة مفتاح، ثمّ اختَر إنشاء مفتاح جديد.
  6. اختَر JSON كـ نوع المفتاح وانقر على إنشاء.

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

لمزيد من المعلومات حول حسابات الخدمة، يُرجى الاطّلاع على حسابات الخدمة في مستندات Cloud IAM في 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 بمعرّف مشروعك على السحابة الإلكترونية.

  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 وكيل الذكاء الاصطناعي Quickstart في برمجة تطبيقات.

    فتح المشروع

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

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

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

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

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

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

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

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

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

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

  10. انقر على ضبط المشروع. تم ربط مشروع على السحابة الإلكترونية بمشروع "برمجة التطبيقات".

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

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

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

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

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

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

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

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

    1. في حقل اسم التطبيق، أدخِل A2UI Quickstart.
    2. في حقل عنوان URL للأفاتار، أدخِل https://developers.google.com/workspace/chat/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 مقابل الموارد المستخدَمة في هذا البرنامج التعليمي، ننصحك بحذف مشروع على السحابة الإلكترونية.

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

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

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