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

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

تستطيع وكلاء الذكاء الاصطناعي إدراك البيئة المحيطة بهم بشكل مستقل، والاستدلال المنطقي، وتنفيذ إجراءات معقّدة ومتعددة الخطوات لتحقيق هدف محدّد. في هذا البرنامج التعليمي، ستنفّذ نموذج LLM Auditor متعدد الوكلاء الذي يقيّم الحقائق ويراجعها باستخدام Gemini وتحديد المصدر من خلال "بحث Google".

نموذج LLM Auditor متعدد الوكلاء كتطبيق Chat

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

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

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

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

الأهداف

  • إعداد البيئة
  • نشر وكيل A2A
  • نشر تطبيق 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.

نشر وكيل A2A

  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. نزِّل مستودع GitHub لعيّنات ADK باستخدام هذا الزر:

    تنزيل adk-samples

  3. في بيئة التطوير المحلية المفضّلة لديك، استخرِج ملف الأرشيف الذي تم تنزيله وافتح الدليل adk-samples/python/agents/llm-auditor.

    unzip adk-samples-main.zip
    cd adk-samples-main/python/agents/llm-auditor
  4. عدِّل عملية التنفيذ لنشر وكيل ADK كوكيل A2A بعيد:

    1. pyproject.toml: أضِف عناصر اعتماد حزمة تطوير البرامج (SDK) الخاصة بـ "حزمة تطوير تطبيقات Android" و"التطبيق إلى التطبيق" في مجموعة النشر.

      apps-script/chat/a2a-ai-agent/llm-auditor/pyproject.toml
      [project]
      name = "llm-auditor"
      version = "0.1.0"
      description = "The LLM Auditor evaluates LLM-generated answers, verifies actual accuracy using the web, and refines the response to ensure alignment with real-world knowledge."
      authors = [
          { name = "Chun-Sung Ferng", email = "csferng@google.com" },
          { name = "Cyrus Rashtchian", email = "cyroid@google.com" },
          { name = "Da-Cheng Juan", email = "dacheng@google.com" },
          { name = "Ivan Kuznetsov", email = "ivanku@google.com" },
      ]
      license = "Apache License 2.0"
      readme = "README.md"
      
      [tool.poetry.dependencies]
      python = "^3.10"
      google-adk = "^1.0.0"
      google-cloud-aiplatform = { extras = [
          "adk",
          "agent-engines",
      ], version = "^1.93.0" }
      google-genai = "^1.9.0"
      pydantic = "^2.10.6"
      python-dotenv = "^1.0.1"
      
      [tool.poetry.group.dev]
      optional = true
      
      [tool.poetry.group.dev.dependencies]
      google-adk = { version = "^1.0.0", extras = ["eval"] }
      pytest = "^8.3.5"
      pytest-asyncio = "^0.26.0"
      
      [tool.poetry.group.deployment]
      optional = true
      
      [tool.poetry.group.deployment.dependencies]
      absl-py = "^2.2.1"
      google-adk = "^1.0.0"
      a2a-sdk = "^0.3.0"
      
      [build-system]
      requires = ["poetry-core>=2.0.0,<3.0.0"]
      build-backend = "poetry.core.masonry.api"
    2. deployment/deploy.py: استبدِل عملية نشر تطبيق ADK بعميل A2A وبطاقة.

      apps-script/chat/a2a-ai-agent/llm-auditor/deployment/deploy.py
      # Copyright 2025 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.
      
      """Deployment script for LLM Auditor."""
      
      import os
      
      from absl import app
      from absl import flags
      from dotenv import load_dotenv
      from llm_auditor.agent import root_agent
      import vertexai
      from vertexai import agent_engines
      
      # A2A wrapping
      from a2a.types import AgentSkill
      from google.adk.a2a.executor.a2a_agent_executor import A2aAgentExecutor
      from google.adk.runners import InMemoryRunner
      from vertexai.preview.reasoning_engines.templates.a2a import create_agent_card
      from vertexai.preview.reasoning_engines import A2aAgent
      
      FLAGS = flags.FLAGS
      flags.DEFINE_string("project_id", None, "GCP project ID.")
      flags.DEFINE_string("location", None, "GCP location.")
      flags.DEFINE_string("bucket", None, "GCP bucket.")
      flags.DEFINE_string("resource_id", None, "ReasoningEngine resource ID.")
      
      flags.DEFINE_bool("list", False, "List all agents.")
      flags.DEFINE_bool("create", False, "Creates a new agent.")
      flags.DEFINE_bool("delete", False, "Deletes an existing agent.")
      flags.mark_bool_flags_as_mutual_exclusive(["create", "delete"])
      
      
      def create() -> None:
          """Creates an agent engine for LLM Auditor."""
          agent_card = create_agent_card(
              agent_name=root_agent.name,
              description=root_agent.description,
              skills=[AgentSkill(
                  id='audit_llm_output',
                  name='Audit LLM Output',
                  description='Critiques and revises outputs from large language models.',
                  tags=['LLM', 'Audit', 'Revision'],
                  examples=[
                      'The earth is flat.',
                      'The capital of France is Berlin.',
                      'The last winner of the Super Bowl was the New England Patriots in 2020.',
                  ],
              )]
          )
          a2a_agent = A2aAgent(
              agent_card=agent_card,
              agent_executor_builder=lambda: A2aAgentExecutor(
                  runner=InMemoryRunner(
                      app_name=root_agent.name,
                      agent=root_agent,
                  )
              )
          )
          a2a_agent.set_up()
      
          remote_agent = agent_engines.create(
              a2a_agent,
              display_name=root_agent.name,
              requirements=[
                      "google-adk (>=0.0.2)",
                      "google-cloud-aiplatform[agent_engines] (>=1.88.0,<2.0.0)",
                      "google-genai (>=1.5.0,<2.0.0)",
                      "pydantic (>=2.10.6,<3.0.0)",
                      "absl-py (>=2.2.1,<3.0.0)",
                      "a2a-sdk>=0.3.22",
                      "uvicorn",
              ],
              # In-memory runner
              max_instances=1,
              env_vars ={
                  "NUM_WORKERS": "1"
              },
              extra_packages=["./llm_auditor"],
          )
          print(f"Created remote agent: {remote_agent.resource_name}")
      
      
      def delete(resource_id: str) -> None:
          remote_agent = agent_engines.get(resource_id)
          remote_agent.delete(force=True)
          print(f"Deleted remote agent: {resource_id}")
      
      
      def list_agents() -> None:
          remote_agents = agent_engines.list()
          TEMPLATE = '''
      {agent.name} ("{agent.display_name}")
      - Create time: {agent.create_time}
      - Update time: {agent.update_time}
      '''
          remote_agents_string = '\n'.join(TEMPLATE.format(agent=agent) for agent in remote_agents)
          print(f"All remote agents:\n{remote_agents_string}")
      
      def main(argv: list[str]) -> None:
          del argv  # unused
          load_dotenv()
      
          project_id = (
              FLAGS.project_id
              if FLAGS.project_id
              else os.getenv("GOOGLE_CLOUD_PROJECT")
          )
          location = (
              FLAGS.location if FLAGS.location else os.getenv("GOOGLE_CLOUD_LOCATION")
          )
          bucket = (
              FLAGS.bucket if FLAGS.bucket
              else os.getenv("GOOGLE_CLOUD_STORAGE_BUCKET")
          )
      
          print(f"PROJECT: {project_id}")
          print(f"LOCATION: {location}")
          print(f"BUCKET: {bucket}")
      
          if not project_id:
              print("Missing required environment variable: GOOGLE_CLOUD_PROJECT")
              return
          elif not location:
              print("Missing required environment variable: GOOGLE_CLOUD_LOCATION")
              return
          elif not bucket:
              print(
                  "Missing required environment variable: GOOGLE_CLOUD_STORAGE_BUCKET"
              )
              return
      
          vertexai.init(
              project=project_id,
              location=location,
              staging_bucket=f"gs://{bucket}",
          )
      
          if FLAGS.list:
              list_agents()
          elif FLAGS.create:
              create()
          elif FLAGS.delete:
              if not FLAGS.resource_id:
                  print("resource_id is required for delete")
                  return
              delete(FLAGS.resource_id)
          else:
              print("Unknown command")
      
      
      if __name__ == "__main__":
          app.run(main)
  5. أنشِئ حزمة جديدة في 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 بموقع مشروعك على السحابة الإلكترونية.
  6. اضبط متغيرات البيئة التالية:

    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 مع الموقع الجغرافي لمشروعك على السحابة الإلكترونية.
  7. تثبيت وكيل ADK ونشره من بيئة افتراضية

    python3 -m venv myenv
    source myenv/bin/activate
    poetry install --with deployment
    python3 deployment/deploy.py --create
  8. استرداد معرّف الوكيل ستحتاج إليه لاحقًا عند إعداد تطبيق Chat.

    python3 deployment/deploy.py --list

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

  1. انقر على الزر التالي لفتح مشروع A2A 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. في مشروع "برمجة التطبيقات"، انقر على رمز إعدادات المشروع إعدادات المشروع.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  5. في الرسالة المباشرة الجديدة مع التطبيق، اكتب The Eiffel Tower was completed in 1900 واضغط علىenter.

    يردّ تطبيق Chat باستخدام ردود الوكيلَين الفرعيَين الناقد والمراجع.

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

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

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

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

تَنظيم

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

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

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

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