ساختن برنامه Google Chat با عامل Agent2UI

این صفحه توضیح می‌دهد که چگونه برنامه Google Chat بسازید که با عامل هوشواره‌ای که از پروتکل Agent2UI (A2UI) استفاده می‌کند میانای کاربر داشته باشد. عامل را بااستفاده از کیت توسعه عامل (ADK) توسعه می‌دهید و آن را در موتور عامل Vertex AI میزبانی می‌کنید.

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

‫A2UI به نمایندگان هوش مصنوعی امکان می‌دهد واسط‌های کاربر تعاملی، غنی، و تطبیقی تولید کنند که به‌صورت بومی ارائه می‌شوند. سپس می‌توانید روی منطق کارگزاران هوش مصنوعی تمرکز کنید، نه واسط‌های کاربر.

  • عامل A2UI با پیامی حاوی نوشتار و کارتی که شامل نام نمایه، تصویر، و دکمه LinkedIn است به کاربر پاسخ می‌دهد.
    شکل ۱. عامل A2UI با نوشتار و کارتی حاوی نام، تصویر، و دکمه LinkedIn به کاربر پاسخ می‌دهد.
  • عامل A2UI به‌روزرسانی شده است تا عنوان نمایه را نیز برگرداند.
    شکل ۲. عامل A2UI به‌روزرسانی شده است تا عنوان نمایه را نیز برگرداند.
  • عامل A2UI با پیامی که نام نمایه را در کارت نمایش می‌دهد به کاربر پاسخ می‌دهد.
    شکل ۳. عامل A2UI با پیامی که نام نمایه‌ای را در کارت نمایش می‌دهد به کاربر پاسخ می‌دهد.

نمودار زیر معماری و الگوی پیام‌رسانی را نشان می‌دهد:

معماری برنامه Chat که با عامل هوش مصنوعی A2UI پیاده‌سازی شده است.

در این نمودار، کاربر با برنامه گپی که با عامل A2UI پیاده‌سازی شده است تعامل می‌کند و جریان اطلاعات به این صورت است:

  1. کاربری پیامی را به برنامه Chat ارسال می‌کند، چه در پیام مستقیم و چه در فضای Chat.
  2. منطق برنامه Chat که در Apps Script یا به‌عنوان سرور وب با نقاط پایانی HTTP پیاده‌سازی شده است، پیام را دریافت و پردازش می‌کند.
  3. عامل A2UI میزبانی‌شده با Vertex AI Agent Engine تعامل را دریافت و پردازش می‌کند.
  4. به‌صورت اختیاری، برنامه Chat یا عامل هوش مصنوعی می‌تواند با سرویس‌های Google Workspace، مثل «تقویم» یا «کاربرگ‌نگار»، یا سرویس‌های دیگر Google، مثل Google Maps یا YouTube، ادغام شود.
  5. برنامه Chat بااستفاده از Google Chat API برای انتقال پیشرفت عامل هوش مصنوعی، پاسخ‌های تطبیقی را به‌صورت ناهمزمان تولید و ارسال می‌کند.
  6. پاسخ‌ها به کاربر ارائه می‌شود.

اهداف

  • محیط خود را راه‌اندازی کنید.
  • عامل A2UI را مستقر کنید.
  • برنامه Chat را مستقر کنید.
  • برنامه Chat را پیکربندی کنید.
  • برنامه Chat را آزمایش کنید.

پیش‌نیازها

راه‌اندازی محیط

فعال کردن Google Cloud APIs

قبل‌از استفاده از «میاناهای برنامه‌سازی کاربردی Google»، باید آن‌ها را در پروژه Google Cloud روشن کنید. می‌توانید یک یا چند API را در یک پروژه Google Cloud روشن کنید.

پیکربندی صفحه کسب رضایت OAuth

همه برنامه‌هایی که از OAuth 2.0 استفاده می‌کنند به پیکربندی صفحه کسب رضایت نیاز دارند. پیکربندی صفحه موافقت OAuth برنامه‌تان مشخص می‌کند چه چیزی به کاربران و بازبینان برنامه نمایش داده شود و برنامه‌تان را ثبت می‌کند تا بتوانید آن را بعداً منتشر کنید.

  1. در «کنسول Google API»، به «منو» > پلاتفرم «احراز هویت Google» > نمانام‌سازی بروید.

    رفتن به نمانام‌سازی

  2. اگر قبلاً پلاتفرم «احراز هویت Google» را پیکربندی کرده‌اید، می‌توانید تنظیمات «صفحه موافقت OAuth» زیر را در نمانام‌سازی، مخاطب، و دسترسی به داده‌ها پیکربندی کنید. اگر پیامی با این مضمون دیدید: پلاتفرم «احراز هویت Google» هنوز پیکربندی نشده است، روی شروع به کار کلیک کنید:
    1. در بخش اطلاعات برنامه، در نام برنامه، نامی برای برنامه وارد کنید.
    2. در ایمیل پشتیبانی کاربر، نشانی ایمیل پشتیبانی را انتخاب کنید که کاربران بتوانند درصورت داشتن سؤال درباره رضایتشان با شما تماس بگیرند.
    3. روی بعدی کلیک کنید.
    4. در بخش مخاطبان، داخلی را انتخاب کنید.
    5. روی بعدی کلیک کنید.
    6. در بخش اطلاعات تماس، نشانی ایمیلی وارد کنید که ازطریق آن بتوانید از هرگونه تغییر در پروژه خود مطلع شوید.
    7. روی بعدی کلیک کنید.
    8. در بخش تکمیل، خط‌مشی داده‌های کاربر سرویس‌های Google API را مرور کنید و درصورت موافقت، با «خط‌مشی داده‌های کاربر سرویس‌های Google API» موافقم را انتخاب کنید.
    9. روی ادامه کلیک کنید.
    10. روی ایجاد کردن کلیک کنید.
  3. درحال‌حاضر می‌توانید از افزودن محدوده‌ها رد شوید. در آینده، وقتی برنامه‌ای برای استفاده در خارج از سازمان Google Workspace خودتان ایجاد می‌کنید، باید نوع کاربر را به خارجی تغییر دهید. سپس محدوده‌های مجوز موردنیاز برنامه‌تان را اضافه کنید. برای کسب اطلاعات بیشتر، راهنمای کامل پیکربندی موافقت OAuth را ببینید.

ایجاد حساب خدمات در کنسول Google Cloud

با دنبال کردن این مراحل، حساب سرویس جدیدی با نقش Vertex AI User ایجاد کنید:

Google Cloud Console

  1. در «کنسول Google Cloud»، به «منو» > IAM و سرپرست > حساب‌های سرویس بروید.

    رفتن به «حساب‌های سرویس»

    مراحل باقی‌مانده در «کنسول Google Cloud» نشان داده می‌شود.

  2. پروژه Google Cloud را انتخاب کنید.
  3. روی ایجاد حساب سرویس کلیک کنید.
  4. نام حساب سرویسی را که می‌خواهید در Google Cloud Console نمایش داده شود وارد کنید.
  5. اگر نمی‌خواهید اکنون کنترل‌های دسترسی را تنظیم کنید، برای تکمیل ایجاد حساب سرویس روی تمام کلیک کنید. برای تنظیم کنترل‌های دسترسی در این لحظه، روی ایجاد و ادامه کلیک کنید و به مرحله بعد بروید.
  6. اختیاری: نقش‌هایی را به حساب خدمات خود اختصاص دهید تا علاوه‌بر منابع Google Workspace، دسترسی به منابع پروژه Google Cloud خود را نیز اعطا کنید. برای جزئیات بیشتر، به مدیریت دسترسی به پروژه‌ها، پوشه‌ها، و سازمان‌ها مراجعه کنید.
  7. روی ادامه کلیک کنید.
  8. اختیاری: کاربرها یا گروه‌هایی را که می‌توانند این حساب سرویس را مدیریت کنند و با آن کنش انجام دهند وارد کنید. برای جزئیات بیشتر، به جعل هویت حساب سرویس مراجعه کنید.
  9. برای تکمیل ایجاد حساب خدمات، روی تمام کلیک کنید.

    نشانی ایمیل حساب سرویس را یادداشت کنید.

gcloud CLI

  1. حساب سرویس را ایجاد کنید: 
    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
  --display-name="SERVICE_ACCOUNT_NAME"
  2. اختیاری: نقش‌هایی را به حساب خدمات خود اختصاص دهید تا علاوه‌بر منابع Google Workspace، دسترسی به منابع پروژه Google Cloud خود را نیز اعطا کنید. برای جزئیات بیشتر، به مدیریت دسترسی به پروژه‌ها، پوشه‌ها، و سازمان‌ها مراجعه کنید.

حساب سرویس در صفحه حساب سرویس نشان داده می‌شود.

ایجاد کلید خصوصی

برای ایجاد و بارگیری کلید خصوصی برای حساب سرویس، این مراحل را دنبال کنید:

  1. در «کنسول Google Cloud»، به «منو» > IAM و سرپرست > حساب‌های سرویس بروید.

    رفتن به «حساب‌های سرویس»

    مراحل باقی‌مانده در «کنسول Google Cloud» نشان داده می‌شود.

  2. پروژه Google Cloud را انتخاب کنید.
  3. روی نشانی ایمیل حساب سرویسی که می‌خواهید کلید برای آن ایجاد کنید کلیک کنید.
  4. روی برگه کلیدها کلیک کنید.
  5. روی منوِ کرکره‌ای افزودن کلید کلیک کنید، سپس ایجاد کلید جدید را انتخاب کنید.
  6. JSON را به‌عنوان نوع کلید انتخاب کنید و روی ایجاد کلیک کنید.

    جفت کلید عمومی/خصوصی جدید شما تولید می‌شود و به‌عنوان فایل کلید حساب خدماتی در ماشین شما بارگیری می‌شود. فایل JSON بارگیری‌شده را به‌عنوان credentials.json در دایرکتوری کاری‌تان ذخیره کنید. این فایل تنها نسخه این کلید است. پس‌از بارگیری فایل کلید، نمی‌توانید آن را دوباره بارگیری کنید. برای کسب اطلاعات درباره نحوه ذخیره ایمن کلید، روال‌های مطلوب برای مدیریت کلیدهای حساب سرویس را ببینید.

برای کسب اطلاعات بیشتر درباره حساب‌های خدمات، به حساب‌های خدمات در اسناد Google Cloud IAM مراجعه کنید.

عامل A2UI را مستقر کنید

  1. اگر این کار را انجام نداده‌اید، با حساب Google Cloud خود اصالت‌سنجی کنید و «رابط خط فرمان Google Cloud» را برای استفاده از پروژه 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 googleworkspace/add-ons-samples را بااستفاده از این دکمه بارگیری کنید:

    بارگیری مخزن

  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 با شناسه پروژه Cloud شما.
    3. PROJECT_LOCATION را با مکان پروژه Cloud خود جایگزین کنید.

  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 با شناسه پروژه Cloud شما.
    3. ‫PROJECT_LOCATION با مکان پروژه Cloud شما.

  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 API»، به «منو» > IAM و سرپرست > تنظیمات بروید.

    به «تنظیمات IAM و سرپرست» بروید

  6. در فیلد شماره پروژه، مقدار را کپی کنید.

  7. در پروژه Apps Script خود، روی نماد تنظیمات پروژه تنظیمات پروژه کلیک کنید.

  8. در بخش پروژه Google Cloud Platform (GCP)، روی تغییر پروژه کلیک کنید.

  9. در شماره پروژه GCP، شماره پروژه Google Cloud را که در مراحل قبلی کپی کرده‌اید جای‌گذاری کنید.

  10. روی تنظیم پروژه کلیک کنید. پروژه Cloud و پروژه Apps Script اکنون متصل هستند.

ایجاد استقرار آزمایشی

برای این پروژه «دستورگان برنامه‌ها» به شناسه استقرار نیاز دارید تا بتوانید از آن در مرحله بعد استفاده کنید.

برای دریافت شناسه استقرار سر، کارهای زیر را انجام دهید:

  1. در پروژه برنامه Chat در Apps Script، روی پیاده‌سازی > آزمایش پیاده‌سازی‌ها کلیک کنید.
  2. در بخش شناسه استقرار سر، روی نماد تهیه کپی کپی کردن کلیک کنید.
  3. روی تمام کلیک کنید.

پیکربندی برنامه Chat

بااستفاده از پیاده‌سازی Apps Script، این مراحل را برای پیاده‌سازی برنامه Google Chat برای آزمایش دنبال کنید:

  1. در API Console، Google Chat API را جستجو کنید، و روی Google Chat API کلیک کنید.
  2. روی مدیریت کلیک کنید.

  3. روی پیکربندی کلیک کنید و برنامه Chat را راه‌اندازی کنید:

    1. در فیلد نام برنامه، A2UI Quickstart را وارد کنید.
    2. در فیلد نشانی وب چهرک، https://developers.google.com/workspace/chat/images/quickstart-app-avatar.png را وارد کنید.
    3. در فیلد شرح، A2UI Quickstart را وارد کنید.
    4. در بخش عملکرد، گزینه پیوستن به فضاها و مکالمه‌های گروهی را انتخاب کنید.
    5. در بخش «تنظیمات اتصال»، پروژه Apps Script را انتخاب کنید.
    6. در فیلد شناسه استقرار، شناسه استقرار «سر» را که قبلاً کپی کرده‌اید جای‌گذاری کنید.
    7. در بخش «رؤیت‌پذیری»، افراد و گروه‌های خاص در دامنه‌تان را انتخاب کنید و ایمیلتان را وارد کنید.

  4. روی ذخیره کلیک کنید.

برنامه Chat آماده پاسخ دادن به پیام‌ها است.

آزمایش کردن برنامه Chat

برای آزمایش برنامه Chat، فضای پیام مستقیمی را با برنامه Chat باز کنید و پیامی ارسال کنید:

  1. بااستفاده از حساب Google Workspace که هنگام اضافه کردن خودتان به‌عنوان آزمایش‌کننده معتمد ارائه کردید، Google Chat را باز کنید.

    رفتن به 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. «کیت توسعه تبلیغات» را که قبلاً با نسخه جدید پیاده‌سازی مستقر شده است به‌روزرسانی کنید.

    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 API»، به صفحه مدیریت منابع بروید. روی منو > IAM و سرپرست > مدیریت منابع کلیک کنید.

    به «مدیر منابع» بروید

  2. در فهرست پروژه، پروژه‌ای را که می‌خواهید حذف کنید انتخاب کنید و سپس روی حذف کلیک کنید.
  3. در چارگوش گفتگو، شناسه پروژه را تایپ کنید و سپس روی خاموش کردن کلیک کنید تا پروژه حذف شود.