سفرها را با یک عامل هوش مصنوعی که در سراسر Google Workspace قابل دسترسی است، برنامه‌ریزی کنید

سطح کدنویسی : پیشرفته
مدت زمان : ۴۵ دقیقه
نوع پروژه : افزونه‌ی Google Workspace که چت ، جیمیل ، تقویم ، درایو ، اسناد، برگه‌ها و اسلایدها را گسترش می‌دهد.

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

نمای کلی

در این آموزش، شما نمونه Travel Concierge را از کیت توسعه عامل (ADK) مستقر می‌کنید. Travel Concierge یک هوش مصنوعی چندعامله محاوره‌ای است که از ابزارهایی مانند API مکان‌های پلتفرم نقشه‌های گوگل، Google Search Grounding و یک سرور Model Context Protocol (MCP) استفاده می‌کند.

ADK به طور پیش‌فرض رابط‌های چت و متن را برای توسعه‌دهندگان فراهم می‌کند. در این آموزش، شما یک رابط کاربری گرافیکی (GUI) به برنامه‌های Google Workspace اضافه می‌کنید که کاربران شما می‌توانند مستقیماً در Chat، Gmail، Calendar، Drive، Docs، Sheets و Slides به آن دسترسی داشته باشند.

  • استفاده از عامل هوش مصنوعی از چت برای ایده پردازی در مورد سفر.
    شکل ۱. استفاده از عامل هوش مصنوعی از Chat برای ایده‌پردازی در مورد سفر.
  • استفاده از عامل هوش مصنوعی از Gmail برای برنامه‌ریزی سفر از متن ایمیل انتخاب شده.
    شکل ۲. استفاده از عامل هوش مصنوعی از جیمیل برای برنامه‌ریزی سفر از متن ایمیل انتخاب‌شده.

اهداف

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

درباره این راهکار

این راهکار بر فناوری‌های اصلی زیر متکی است: ADK، رابط‌های برنامه‌نویسی کاربردی Google Cloud و Google Workspace ، موتور عامل هوش مصنوعی Vertex و چارچوب Card .

رابط‌های کاربری گرافیکی برای برنامه‌های چت و غیر چت (Gmail، Calendar، Drive، Docs، Sheets، Slides) به طور متفاوتی طراحی شده‌اند تا ویژگی‌ها و محدودیت‌های خاص آنها در نظر گرفته شود.

ویژگی‌ها

ویژگی‌های زیر از برنامه‌ی Travel Concierge در تمام برنامه‌های Google Workspace مشترک است:

  • جلسات کاربری مداوم: جلسات توسط Vertex AI برای ماندگاری مدیریت می‌شوند. هر کاربر یک جلسه را در تمام برنامه‌های Workspace به اشتراک می‌گذارد. کاربران می‌توانند برای شروع یک مکالمه جدید، جلسه خود را به صورت دستی تنظیم مجدد کنند.

  • پیام‌رسانی غنی: کاربران پیام‌های متنی ارسال می‌کنند و با متن غنی و ابزارک‌های کارت پاسخ دریافت می‌کنند.

  • مدیریت خطا: خطاهای غیرمنتظره با استفاده از تلاش‌های مجدد و وضعیت‌های قابل تنظیم در پاسخ‌ها، به طرز ماهرانه‌ای مدیریت می‌شوند.

برنامه چت دارای ویژگی‌های اضافی زیر است:

  • پیام‌رسانی چندوجهی کاربر: کاربران می‌توانند پیام‌هایی با پیوست، از جمله صدا و تصویر ضبط‌شده مستقیماً از فضای چت، ارسال کنند.

  • پاسخ‌های بصری پیشرفته‌تر: پاسخ‌ها را می‌توان با ویجت‌های پیشرفته‌تر مانند چرخ‌وفلک‌های تصویری با تکیه بر ویژگی‌های چت فریم‌ورک Card و فضای رندر بیشتر تولید کرد.

برنامه‌های دیگر این ویژگی‌های اضافی را دارند:

  • زمینه پروفایل گوگل: کاربران می‌توانند پیام‌هایی با اطلاعات پروفایل خود ارسال کنند (در این نمونه، محدود به تاریخ تولد).

  • متن جیمیل: کاربران می‌توانند پیام‌ها را با ایمیل ارسال کنند (در این نمونه، محدود به یک موضوع و متن).

  • دسترسی به فضای چت نماینده: کاربران می‌توانند با یک کلیک، فضای پیام مستقیم (DM) برنامه چت را در یک تب جدید باز کنند.

معماری

برنامه‌ی Travel Concierge رویدادهای تعاملی افزونه‌ی Google Workspace را از برنامه‌های Google Workspace دریافت و پردازش می‌کند، از Vertex AI برای فراخوانی عامل هوش مصنوعی ADK و مدیریت جلسات کاربر استفاده می‌کند و برای جمع‌آوری اطلاعات و نمایش پاسخ‌ها به APIهای Google Cloud و Google Workspace متکی است.

نمودارهای زیر جریان اصلی کاربر را نشان می‌دهند: ارسال پیام به عامل هوش مصنوعی.

اچ‌تی‌پی

  • نمودار معماری برای برنامه چت.
    شکل ۳. برنامه چت، متن را با پیوست‌هایی از پیام کاربر تکمیل می‌کند و مجموعه‌ای از پیام‌ها را با سابقه تعاملات زیرعامل و پاسخ کلی نهایی به ترتیب زمانی ارسال می‌کند.
  • نمودار معماری برای برنامه‌های غیر چت.
    شکل ۴. برنامه‌های غیر چت، زمینه را با نمایه گوگل کاربر و انتخاب آیتم تکمیل می‌کنند و مجموعه‌ای از بخش‌ها را با تاریخچه تعاملات زیرعامل و پاسخ کلی نهایی به ترتیب زمانی معکوس نمایش می‌دهند.

اسکریپت برنامه‌ها

  • نمودار معماری برای برنامه چت.
    شکل ۳. برنامه چت، متن را با پیوست‌هایی از پیام کاربر تکمیل می‌کند و مجموعه‌ای از پیام‌ها را با سابقه تعاملات زیرعامل و پاسخ کلی نهایی به ترتیب زمانی ارسال می‌کند.
  • نمودار معماری برای برنامه‌های غیر چت.
    شکل ۴. برنامه‌های غیر چت، زمینه را با نمایه گوگل کاربر و انتخاب آیتم تکمیل می‌کنند و مجموعه‌ای از بخش‌ها را با تاریخچه تعاملات زیرعامل و پاسخ کلی نهایی به ترتیب زمانی معکوس نمایش می‌دهند.

پیش‌نیازها

محیط را آماده کنید

این بخش نحوه ایجاد و پیکربندی یک پروژه Google Cloud را نشان می‌دهد.

ایجاد یک پروژه گوگل کلود

کنسول گوگل کلود

  1. در کنسول گوگل کلود، به Menu > IAM & Admin > Create a Project بروید.

    به ایجاد پروژه بروید

  2. در قسمت نام پروژه ، یک نام توصیفی برای پروژه خود وارد کنید.

    اختیاری: برای ویرایش شناسه پروژه ، روی ویرایش کلیک کنید. شناسه پروژه پس از ایجاد پروژه قابل تغییر نیست، بنابراین شناسه‌ای را انتخاب کنید که نیازهای شما را در طول عمر پروژه برآورده کند.

  3. در فیلد «مکان» ، روی «مرور» کلیک کنید تا مکان‌های بالقوه برای پروژه شما نمایش داده شود. سپس، روی «انتخاب» کلیک کنید.
  4. روی ایجاد کلیک کنید. کنسول Google Cloud به صفحه داشبورد هدایت می‌شود و پروژه شما ظرف چند دقیقه ایجاد می‌شود.

رابط خط فرمان جی‌کلاود

در یکی از محیط‌های توسعه زیر، به رابط خط فرمان گوگل کلود ( gcloud ) دسترسی پیدا کنید:

  • Cloud Shell : برای استفاده از یک ترمینال آنلاین با رابط خط فرمان gcloud که از قبل تنظیم شده است، Cloud Shell را فعال کنید.
    فعال کردن پوسته ابری
  • پوسته محلی : برای استفاده از یک محیط توسعه محلی، رابط خط فرمان gcloud را نصب و راه‌اندازی کنید .
    برای ایجاد یک پروژه ابری، از دستور gcloud projects create استفاده کنید:
    gcloud projects create PROJECT_ID
     به جای PROJECT_ID شناسه پروژه‌ای که می‌خواهید ایجاد کنید را وارد کنید.

فعال کردن پرداخت برای پروژه ابری

کنسول گوگل کلود

  1. در کنسول گوگل کلود، به بخش صورتحساب (Billing) بروید. (Menu) > صورتحساب (Billing) > پروژه‌های من (My Projects) کلیک کنید.

    به بخش پرداخت هزینه‌های پروژه‌های من بروید

  2. در بخش «انتخاب سازمان» ، سازمانی را که با پروژه Google Cloud شما مرتبط است، انتخاب کنید.
  3. در ردیف پروژه، منوی اقدامات ( ) را باز کنید، روی تغییر صورتحساب کلیک کنید و حساب صورتحساب ابری را انتخاب کنید.
  4. روی تنظیم حساب کلیک کنید.

رابط خط فرمان جی‌کلاود

  1. برای فهرست کردن حساب‌های صورتحساب موجود، دستور زیر را اجرا کنید: 
    gcloud billing accounts list
  2. یک حساب صورتحساب را با یک پروژه Google Cloud مرتبط کنید:
    gcloud billing projects link PROJECT_ID --billing-account=BILLING_ACCOUNT_ID

    موارد زیر را جایگزین کنید:

    • PROJECT_ID شناسه پروژه برای پروژه ابری است که می‌خواهید صورتحساب را برای آن فعال کنید.
    • BILLING_ACCOUNT_ID شناسه حساب پرداخت برای پیوند با پروژه Google Cloud است.

فعال کردن APIهای گوگل کلود

اچ‌تی‌پی

  1. در کنسول گوگل کلود، APIهای افزونه‌های Vertex AI، Places، People، Google Chat، Gmail، Cloud Build، Cloud Functions، Cloud Pub/Sub، Cloud Logging، Artifact Registry، Cloud Run و Google Workspace را فعال کنید.

    فعال کردن APIها

  2. تأیید کنید که APIها را در پروژه Cloud صحیح فعال می‌کنید، سپس روی Next کلیک کنید.

  3. تأیید کنید که API های صحیح را فعال می‌کنید، سپس روی فعال کردن کلیک کنید.

اسکریپت برنامه‌ها

  1. در کنسول گوگل کلود، APIهای Vertex AI، Places، People و Google Chat را فعال کنید.

    فعال کردن APIها

  2. تأیید کنید که APIها را در پروژه Cloud صحیح فعال می‌کنید، سپس روی Next کلیک کنید.

  3. تأیید کنید که API های صحیح را فعال می‌کنید، سپس روی فعال کردن کلیک کنید.

دریافت کلید API مکان‌های پلتفرم نقشه‌های گوگل

  1. در کنسول گوگل کلود، به صفحه Google Maps Platform > Keys & Credentials بروید.

    به کلیدها و اعتبارنامه‌ها بروید

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

یک حساب کاربری سرویس در کنسول گوگل کلود ایجاد کنید

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

کنسول گوگل کلود

  1. در کنسول گوگل کلود، به Menu > IAM & Admin > Service Accounts بروید.

    به حساب‌های سرویس بروید

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

رابط خط فرمان جی‌کلاود

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

حساب کاربری سرویس در صفحه حساب کاربری سرویس نمایش داده می‌شود. در مرحله بعد، یک کلید خصوصی برای حساب کاربری سرویس ایجاد کنید.

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

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

  1. در کنسول گوگل کلود، به Menu > IAM & Admin > Service Accounts بروید.

    به حساب‌های سرویس بروید

  2. حساب کاربری سرویس خود را انتخاب کنید.
  3. روی کلیدها > افزودن کلید > ایجاد کلید جدید کلیک کنید.
  4. JSON را انتخاب کنید، سپس روی ایجاد کلیک کنید.

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

  5. روی بستن کلیک کنید.

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

افزونه‌های Google Workspace نیاز به پیکربندی صفحه رضایت دارند. پیکربندی صفحه رضایت OAuth افزونه شما، آنچه گوگل به کاربران نمایش می‌دهد را تعریف می‌کند.

  1. در کنسول گوگل کلود، به Menu > برویدGoogle Auth platform > برندسازی .

    به بخش برندسازی بروید

  2. اگر قبلاً تنظیمات را انجام داده‌اید Google Auth platformمی‌توانید تنظیمات صفحه رضایت OAuth زیر را در Branding ، Audience و Data Access پیکربندی کنید. اگر پیامی با این مضمون مشاهده کردید Google Auth platform هنوز پیکربندی نشده است ، روی شروع کار کلیک کنید:
    1. در قسمت اطلاعات برنامه ، در قسمت نام برنامه ، نامی برای برنامه وارد کنید.
    2. در ایمیل پشتیبانی کاربر ، یک آدرس ایمیل پشتیبانی انتخاب کنید که کاربران در صورت داشتن هرگونه سوال در مورد رضایت خود بتوانند با شما تماس بگیرند.
    3. روی بعدی کلیک کنید.
    4. در قسمت مخاطبان ، داخلی (Internal) را انتخاب کنید.
    5. روی بعدی کلیک کنید.
    6. در قسمت اطلاعات تماس ، یک آدرس ایمیل وارد کنید که از طریق آن بتوانید از هرگونه تغییر در پروژه خود مطلع شوید.
    7. روی بعدی کلیک کنید.
    8. در قسمت Finish ، سیاست داده‌های کاربر سرویس‌های API گوگل را مرور کنید و در صورت موافقت، گزینه «من با سیاست‌های داده‌های کاربر سرویس‌های API گوگل موافقم» را انتخاب کنید.
    9. روی ادامه کلیک کنید.
    10. روی ایجاد کلیک کنید.
  3. فعلاً می‌توانید از اضافه کردن محدوده‌ها صرف نظر کنید. در آینده، وقتی برنامه‌ای برای استفاده در خارج از سازمان Google Workspace خود ایجاد می‌کنید، باید نوع کاربر (User type) را به خارجی (External) تغییر دهید. سپس محدوده‌های مجوز مورد نیاز برنامه خود را اضافه کنید. برای کسب اطلاعات بیشتر، به راهنمای کامل پیکربندی رضایت OAuth مراجعه کنید.

عامل هوش مصنوعی ADK دربان مسافرتی را مستقر کنید

  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. این مخزن گیت‌هاب را دانلود کنید

    دانلود

  3. در محیط توسعه محلی مورد نظر خود، فایل بایگانی دانلود شده را استخراج کرده و دایرکتوری adk-samples/python/agents/travel-concierge را باز کنید.

    unzip adk-samples-main.zip
cd adk-samples-main/python/agents/travel-concierge

  4. یک سطل ذخیره‌سازی ابری جدید مختص عامل هوش مصنوعی 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=1
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
export GOOGLE_CLOUD_LOCATION=PROJECT_LOCATION
export GOOGLE_PLACES_API_KEY=PLACES_API_KEY
export GOOGLE_CLOUD_STORAGE_BUCKET=CLOUD_STORAGE_BUCKET_NAME
export TRAVEL_CONCIERGE_SCENARIO=travel_concierge/profiles/itinerary_empty_default.json

    موارد زیر را جایگزین کنید:

    1. PROJECT_ID با شناسه پروژه ابری که ایجاد کرده‌اید.
    2. PROJECT_LOCATION با محل پروژه ابری که ایجاد کرده‌اید.
    3. PLACES_API_KEY با رشته کلید API که ایجاد کرده‌اید.
    4. CLOUD_STORAGE_BUCKET_NAME با نام باکتی که ایجاد کرده‌اید.

  6. نصب و استقرار عامل هوش مصنوعی ADK.

    uv sync --group deployment
uv run python deployment/deploy.py --create

  7. شماره پروژه و شناسه موتور را از آخرین گزارش چاپ شده به ترتیب با نام‌های PROJECT_NUMBER و ENGINE_ID بازیابی کنید، بعداً برای پیکربندی پروژه خود به هر دوی آنها نیاز خواهید داشت. 

    Created remote agent: projects/PROJECT_NUMBER/locations/us-central1/reasoningEngines/ENGINE_ID

کد نمونه را بررسی کنید

در صورت تمایل، قبل از راه‌اندازی پروژه، زمانی را برای بررسی و آشنایی با کد نمونه میزبانی شده در GitHub اختصاص دهید.

پایتون

مشاهده در گیت‌هاب

اسکریپت برنامه‌ها

مشاهده در گیت‌هاب

ایجاد و پیکربندی پروژه

پایتون

  1. این مخزن گیت‌هاب را دانلود کنید

    دانلود

  2. در محیط توسعه محلی مورد نظر خود، فایل بایگانی دانلود شده را استخراج کرده و پوشه add-ons-samples/python/travel-adk-ai-agent را باز کنید. 

    unzip add-ons-samples-main.zip
cd add-ons-samples-main/python/travel-adk-ai-agent

  3. فایل کلید JSON با نام credentials.json را از حساب سرویس دانلود شده در مراحل قبلی به دایرکتوری پروژه منتقل کنید.

  4. در کنسول گوگل کلود، به Cloud Run بروید:

    به Cloud Run بروید

  5. روی نوشتن یک تابع کلیک کنید.

  6. در صفحه ایجاد سرویس ، تابع خود را تنظیم کنید:

    1. در فیلد نام سرویس ، travel-concierge-app را وارد کنید.
    2. در لیست منطقه ، مکان پروژه ابری که ایجاد کرده‌اید، یعنی PROJECT_LOCATION ، را انتخاب کنید.
    3. در زیر Endpoint URL ، کلیک کنید آیکون مربوط به کپی کردن .
    4. در لیست Runtime ، جدیدترین نسخه پایتون را انتخاب کنید.
    5. در بخش احراز هویت ، گزینه «اجازه دسترسی عمومی» را انتخاب کنید.
    6. در بخش Containers, Volumes, Networking, Security ، در قسمت Resources :
      1. در قسمت حافظه ، ۱ گیگابایت را انتخاب کنید.
      2. در قسمت CPU ، عدد ۲ را انتخاب کنید.
    7. روی Create کلیک کنید و منتظر بمانید تا Cloud Run سرویس را ایجاد کند. کنسول شما را به تب Source هدایت می‌کند.

  7. در محیط توسعه محلی مورد نظر خود، منبع پروژه را مستقر کنید: 

    gcloud run deploy travel-concierge-app --quiet --source . \
    --region PROJECT_LOCATION  \
    --function adk_ai_agent  \
    --set-env-vars LOCATION=LOCATION,PROJECT_NUMBER=PROJECT_NUMBER,ENGINE_ID=ENGINE_ID,BASE_URL=BASE_URL

    موارد زیر را جایگزین کنید:

    1. PROJECT_LOCATION با موقعیت مکانی تابع Cloud Run که قبلاً ایجاد کرده‌اید.
    2. LOCATION با محل پروژه Google Cloud ایجاد شده در مراحل قبلی، PROJECT_LOCATION .
    3. PROJECT_NUMBER با شماره پروژه Travel Concierge ADK AI Agent که در مراحل قبلی مستقر شده است.
    4. ENGINE_ID با شناسه موتور عامل هوش مصنوعی Travel Concierge ADK که در مراحل قبلی مستقر شده است.
    5. BASE_URL با آدرس اینترنتی Endpoint که قبلاً کپی کرده‌اید.

اسکریپت برنامه‌ها

برای ایجاد یک پروژه Apps Script و پیکربندی آن برای استفاده از عامل هوش مصنوعی Travel Concierge ADK مستقر شده خود:

  1. برای باز کردن پروژه اسکریپت Travel Concierge ADK AI Agent Apps روی دکمه زیر کلیک کنید.
    پروژه را باز کنید

  2. روی Overview کلیک کنید، سپس آیکون مربوط به کپی کردن یک کپی تهیه کنید .

  3. نام نسخه خود از پروژه Apps Script را بنویسید:

    1. روی کپی Travel Concierge ADK AI Agent کلیک کنید.
    2. در عنوان پروژه ، عبارت Travel Concierge ADK AI Agent تایپ کنید.
    3. روی تغییر نام کلیک کنید.

  4. در پروژه Apps Script خود، کلیک کنید آیکون مربوط به تنظیمات پروژه ویرایشگر را باز کنید و فایل VertexAi.gs را با استفاده از اکشن File Move file up به بالا منتقل کنید تا بالاتر از فایل AgentHandler.gs قرار گیرد.

  5. در پروژه Apps Script خود، کلیک کنید آیکون مربوط به تنظیمات پروژه تنظیمات پروژه ، روی ویرایش ویژگی‌های اسکریپت کلیک کنید، سپس برای افزودن ویژگی‌های اسکریپت زیر، روی افزودن ویژگی اسکریپت کلیک کنید:

  6. ENGINE_ID با شناسه موتور عامل هوش مصنوعی Travel Concierge ADK که در مراحل قبلی مستقر شده است، ENGINE_ID .

  7. LOCATION با محل پروژه Google Cloud ایجاد شده در مراحل قبلی، PROJECT_LOCATION .

  8. PROJECT_NUMBER با شماره پروژه عامل هوش مصنوعی Travel Concierge ADK که در مراحل قبلی مستقر شده است، PROJECT_NUMBER .

  9. SERVICE_ACCOUNT_KEY با کلید JSON از حساب سرویس دانلود شده در مراحل قبلی مانند { ... } .

  10. روی ذخیره ویژگی‌های اسکریپت کلیک کنید

  11. در پروژه Apps Script خود، کلیک کنید آیکون مربوط به تنظیمات پروژه تنظیمات پروژه .

  12. در زیر پروژه پلتفرم ابری گوگل (GCP) ، روی تغییر پروژه کلیک کنید.

  13. در شماره پروژه GCP ، شماره پروژه Travel Concierge ADK AI Agent که در مراحل قبلی مستقر شده است، PROJECT_NUMBER ، را جایگذاری کنید.

  14. روی تنظیم پروژه کلیک کنید. پروژه Cloud و پروژه Apps Script اکنون به هم متصل شده‌اند.

استقرار در جیمیل، تقویم، درایو، اسناد، برگه‌ها، اسلایدها

پایتون

برای فعال کردن قابلیت آزمایش، از یک افزونه‌ی Google Workspace برای نصب پروژه‌ی نمونه در تمام برنامه‌های Google Workspace (به جز Google Chat) استفاده کنید.

  1. در محیط توسعه محلی مورد نظر خود، فایل deployment.json را از منبع کد پروژه باز کنید و تمام موارد $BASE_URL را با مقدار BASE_URL ، آدرس اینترنتی نقطه پایانی که در مراحل قبلی کپی کرده‌اید، جایگزین کنید.

  2. یک افزونه‌ی Google Workspace با نام travel-concierge-addon ایجاد کنید: 

    gcloud workspace-add-ons deployments create travel-concierge-addon \
    --deployment-file=deployment.json

  3. افزونه‌ی Google Workspace را نصب کنید: 

    gcloud workspace-add-ons deployments install travel-concierge-addon

اسکریپت برنامه‌ها

برای فعال کردن قابلیت تست، پروژه Apps Script را روی همه برنامه‌های Google Workspace (به جز Google Chat) نصب کنید.

  1. در پروژه Apps Script خود، روی Deploy > Test deployments و سپس Install کلیک کنید.

این افزونه اکنون از نوارهای کناری برنامه Google Workspace قابل دسترسی است.

استقرار در چت

پایتون

برای فعال کردن تست، پروژه نمونه را با استفاده از Endpoint URL روی Chat نصب کنید.

  1. در کنسول ، Google Chat API را جستجو کنید، روی Google Chat API کلیک کنید، سپس روی Manage و Configuration کلیک کنید.

    به صفحه پیکربندی API چت گوگل بروید

  2. برنامه چت را تنظیم کنید:

    1. در فیلد نام برنامه ، Travel ADK AI Agent را وارد کنید.
    2. در فیلد آدرس اینترنتی آواتار ، https://goo.gle/3SfMkjb را وارد کنید.
    3. در فیلد توضیحات ، Travel ADK AI Agent را وارد کنید.
    4. در قسمت تنظیمات اتصال ، آدرس اینترنتی نقطه پایانی HTTP را انتخاب کنید.
    5. در زیر Triggers ، گزینه Use a common HTTP endpoint URL for all triggers را انتخاب کنید.
    6. در فیلد HTTP endpoint URL ، آدرس اینترنتی Endpoint که قبلاً کپی کرده‌اید، یعنی BASE_URL جایگذاری کنید.
    7. یک دستور سریع ثبت کنید که برنامه چت کاملاً پیاده‌سازی شده از آن استفاده کند:
      1. در قسمت دستورات ، روی افزودن یک دستور کلیک کنید.
      2. در قسمت شناسه فرمان ، عدد 1 را تایپ کنید.
      3. در قسمت توضیحات ، عبارت Reset session تایپ کنید.
      4. در قسمت نوع فرمان ، دستور سریع (Quick command) را انتخاب کنید.
      5. در قسمت Name ، عبارت Reset session تایپ کنید.
      6. روی «انجام شد» کلیک کنید. دستور سریع ثبت و فهرست می‌شود.
    8. در قسمت «قابلیت مشاهده» ، گزینه «این برنامه چت را برای افراد و گروه‌های خاص در دامنه فضای کاری خود در دسترس قرار دهید» را انتخاب کنید و آدرس ایمیل خود را وارد کنید.
    9. در قسمت گزارش‌ها ، گزینه ثبت خطاها را برای ثبت گزارش‌ها انتخاب کنید.
    10. روی ذخیره کلیک کنید.

اسکریپت برنامه‌ها

پروژه Apps Script را با استفاده از Head Deployment ID روی Chat نصب کنید تا امکان تست فراهم شود.

  1. در پروژه Apps Script خود، روی Deploy > Test deployments کلیک کنید، سپس آیکون کپی شناسه استقرار سر زیر شناسه استقرار سرپرست کپی کنید .

  2. در کنسول ، Google Chat API را جستجو کنید، روی Google Chat API کلیک کنید، سپس روی Manage و Configuration کلیک کنید.

    به صفحه پیکربندی API چت گوگل بروید

  3. برنامه چت را تنظیم کنید:

    1. در فیلد نام برنامه ، Travel ADK AI Agent را وارد کنید.
    2. در فیلد آدرس اینترنتی آواتار ، https://goo.gle/3SfMkjb را وارد کنید.
    3. در فیلد توضیحات ، Travel ADK AI Agent را وارد کنید.
    4. در بخش تنظیمات اتصال ، گزینه Apps Script را انتخاب کنید.
    5. در فیلد Deployment ID ، شناسه استقرار Head را که قبلاً کپی کرده‌اید، جایگذاری کنید.
    6. یک دستور سریع ثبت کنید که برنامه چت کاملاً پیاده‌سازی شده از آن استفاده کند:
      1. در قسمت دستورات ، روی افزودن یک دستور کلیک کنید.
      2. در قسمت شناسه فرمان ، عدد 1 را تایپ کنید.
      3. در قسمت توضیحات ، عبارت Reset session تایپ کنید.
      4. در قسمت نوع فرمان ، دستور سریع (Quick command) را انتخاب کنید.
      5. در قسمت Name ، عبارت Reset session تایپ کنید.
      6. روی «انجام شد» کلیک کنید. دستور سریع ثبت و فهرست می‌شود.
    7. در قسمت «قابلیت مشاهده» ، گزینه «این برنامه چت را برای افراد و گروه‌های خاص در دامنه فضای کاری خود در دسترس قرار دهید» را انتخاب کنید و آدرس ایمیل خود را وارد کنید.
    8. در قسمت گزارش‌ها ، گزینه ثبت خطاها را برای ثبت گزارش‌ها انتخاب کنید.
    9. روی ذخیره کلیک کنید.

این برنامه اکنون از طریق گوگل چت قابل دسترسی است.

  1. گوگل چت را باز کنید.

    به گوگل چت بروید

  2. فضای چت دایرکت را ایجاد کنید:

    1. روی گپ جدید کلیک کنید.
    2. در قسمت جستجو، عبارت Travel ADK AI Agent را تایپ و انتخاب کنید.
    3. در پنجره‌ی Install app ، روی نصب برنامه کلیک کنید.
    4. پنجره Install app بسته می‌شود و فضای چت دایرکت تازه ایجاد شده انتخاب می‌شود.

برنامه چت آماده پاسخگویی به پیام‌ها است.

عامل را آزمایش کنید

  1. جیمیل را باز کنید.

    به جیمیل بروید

  2. ایمیل زیر را برای خودتان ارسال کنید:

    • موضوع: You need to travel to Paris
    • متن پیام: Please be there between 11/25/2025 and 11/30/2025!

  3. افزونه Travel ADK AI Agent را از نوار کناری باز کنید.

  4. برای تکمیل راه‌اندازی افزونه، روی اعطای مجوزها کلیک کنید.

  5. پس از پیکربندی درخواست زیر برای اپراتور، روی ارسال کلیک کنید:

    • پیام: Please help me plan this travel!
    • متن: ایمیل فعلی را انتخاب کنید

    نوار کناری با پاسخ نماینده به‌روزرسانی می‌شود.

    برنامه‌ریزی سفر از طریق جیمیل

  6. برای هدایت به فضای چت دایرکت ، روی باز کردن چت کلیک کنید.

  7. روی + > بازنشانی جلسه کلیک کنید.

    شما یک پیام جدید دریافت می‌کنید که تأیید می‌کند کار تمام شده است: OK, let's start from the beginning, what can I help you with?

  8. پیام را ارسال کن Give me ideas .

    شما پیام‌های جدیدی حاوی پاسخ اپراتور دریافت می‌کنید.

    طوفان فکری از چت

  9. بعد از آپلود عکس هر مکانی مانند برج ایفل ، پیام I want to go there! را ارسال کنید.

    شما پیام‌های جدیدی حاوی پاسخ اپراتور دریافت می‌کنید.

    جزئیات موقعیت مکانی را از پیوست چت دریافت کنید

محدودیت‌ها

اچ‌تی‌پی

در برنامه‌های Google Workspace غیر از Chat، عامل هوش مصنوعی محدودیت‌های زیر را دارد:

  • همگام است: نوارهای کناری فقط می‌توانند در پاسخ به تعاملات کاربر به‌روزرسانی شوند، بنابراین پاسخ‌های عامل هوش مصنوعی فقط پس از تکمیل کامل نمایش داده می‌شوند (بدون پخش جریانی).

  • می‌تواند منقضی شود: به‌روزرسانی‌های نوار کناری وقتی بیش از چند دقیقه طول بکشند، منقضی می‌شوند.

این محدودیت‌ها در چت وجود ندارند.

اسکریپت برنامه‌ها

در تمام برنامه‌های Google Workspace، عامل هوش مصنوعی، APIهای Vertex AI REST را با استفاده از UrlFetchApp فراخوانی می‌کند که باعث محدودیت‌های زیر می‌شود:

  • همزمان است: پاسخ‌های عامل هوش مصنوعی فقط پس از تکمیل کامل (بدون پخش جریانی) بازگردانده می‌شوند.

  • می‌تواند زمان از دست رفته را نشان دهد: عامل هوش مصنوعی وقتی تقریباً بیش از یک دقیقه طول می‌کشد تا کار را انجام دهد، درخواست زمان از دست رفته می‌کند.

سفارشی‌سازی

این راهکار از عامل‌های هوش مصنوعی ADK که در Vertex AI Agent Engine، زیرمجموعه‌ای از رابط‌های کاربری برنامه Google Workspace، میزبانی می‌شوند و رندرهای پاسخ مختص به پاسخ‌های نمونه Travel Concierge، پشتیبانی می‌کند. این راهکار از یک چارچوب توسعه‌پذیر استفاده می‌کند، بنابراین می‌توانید با تغییر فایل‌های زیر، آن را سفارشی‌سازی کنید:

پایتون

  • main.py: رابط‌های کاربری اصلی و منطق تعاملات کاربر (کنترل‌کننده‌های رویداد Google Workspace) را تعریف می‌کند. یک افزونه‌ی معمول می‌تواند اسناد Drive را به عنوان ویژگی زمینه برای برنامه‌ی Drive فعال کند، مشابه کاری که با پیام‌های Gmail برای برنامه‌ی Gmail انجام می‌شود.

  • vertex_ai.py: جلسات، پاسخ‌ها و خطاهای عامل هوش مصنوعی را مدیریت می‌کند و رابط‌های مخصوص هوش مصنوعی Vertex را برای پشتیبانی از تعاملات عامل و رندرهای پاسخ تعریف می‌کند. افزونه‌های معمول شامل افزودن پشتیبانی از چند جلسه برای مکالمات جداگانه کاربر و سایر پلتفرم‌های مدیریت عامل هوش مصنوعی است.

  • agent_handler.py: رابط‌های مختص هوش مصنوعی Vertex که در vertex_ai.py تعریف شده‌اند را در موارد خاص برنامه‌های چت و غیر چت پیاده‌سازی می‌کند. یک افزونه‌ی معمول، اضافه کردن دکمه‌هایی برای کاربران جهت ارسال بازخورد در مورد پاسخ‌های عامل هوش مصنوعی است.

  • google_workspace.py: تعاملات غیر هوش مصنوعی با پلتفرم مدیریت عامل را با استفاده از فراخوانی‌های API پیاده‌سازی می‌کند. در این نمونه، فقط از APIهای Google Workspace برای جمع‌آوری جزئیات زمینه و انجام اقدامات استفاده می‌شود. یک افزونه‌ی معمول می‌تواند توابعی را برای بازیابی داده‌های تجاری از تقویم گوگل یا مدیریت ارتباط با مشتری (CRM) اضافه کند.

  • travel_agent_ui_render.gs: رندرهای پاسخ مخصوص Travel Concierge را برای زیر-عامل‌ها و برنامه‌های Workspace پیاده‌سازی می‌کند. افزونه‌های معمول شامل افزودن پشتیبانی برای رندرهای پاسخ جدید برای نمایش گرافیکی گزینه‌های پرواز و سایر عامل‌های هوش مصنوعی است.

اسکریپت برنامه‌ها

  • Code.gs: رابط‌های کاربری اصلی و منطق تعاملات کاربر (کنترل‌کننده‌های رویداد Google Workspace) را تعریف می‌کند. یک افزونه‌ی معمول می‌تواند اسناد Drive را به عنوان ویژگی زمینه برای برنامه‌ی Drive فعال کند، مشابه کاری که با پیام‌های Gmail برای برنامه‌ی Gmail انجام می‌شود.

  • VertexAi.gs: جلسات، پاسخ‌ها و خطاهای عامل هوش مصنوعی را مدیریت می‌کند و رابط‌های کاربری مخصوص Vertex AI را برای پشتیبانی از تعاملات عامل و رندر پاسخ‌ها تعریف می‌کند. افزونه‌های معمول شامل پشتیبانی از چند جلسه‌ای بودن مکالمات جداگانه کاربران و سایر پلتفرم‌های مدیریت عامل هوش مصنوعی است.

  • AgentHandler.gs: رابط‌های مختص هوش مصنوعی Vertex که در VertexAi.gs تعریف شده‌اند را در موارد خاص برنامه‌های چت و غیر چت پیاده‌سازی می‌کند. یک افزونه‌ی معمول، افزودن دکمه‌هایی برای کاربران جهت ارسال بازخورد در مورد پاسخ‌های عامل هوش مصنوعی است.

  • GoogleWorkspace.gs: تعاملات مدیریت عامل-پلتفرم غیر هوش مصنوعی را با استفاده از فراخوانی‌های API پیاده‌سازی می‌کند. در این نمونه، فقط از APIهای Google Workspace برای جمع‌آوری جزئیات زمینه و انجام اقدامات استفاده می‌شود. یک افزونه‌ی معمول، افزودن توابعی برای بازیابی داده‌های تجاری از تقویم گوگل یا مدیریت ارتباط با مشتری (CRM) است.

  • TravelAgentUiRender.gs: رندرهای پاسخ مخصوص Travel Concierge را برای زیر-عامل‌ها و برنامه‌های Workspace پیاده‌سازی می‌کند. افزونه‌های معمول شامل افزودن پشتیبانی برای رندرهای پاسخ جدید برای نمایش گرافیکی گزینه‌های پرواز و سایر عامل‌های هوش مصنوعی است.

تمیز کردن

برای جلوگیری از تحمیل هزینه به حساب Google Cloud خود برای منابع استفاده شده در این آموزش، توصیه می‌کنیم پروژه Cloud را حذف کنید.

  1. در کنسول گوگل کلود، به صفحه مدیریت منابع بروید. منو > مدیریت و دسترسی به منابع (IAM & Admin) > مدیریت منابع (Manage Resources) کلیک کنید.

    به مدیریت منابع بروید

  2. در لیست پروژه‌ها، پروژه‌ای را که می‌خواهید حذف کنید انتخاب کنید و سپس روی «حذف کلیک کنید.
  3. در کادر محاوره‌ای، شناسه پروژه را تایپ کنید و سپس برای حذف پروژه، روی خاموش کردن (Shut down) کلیک کنید.