این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

ادغام Vertex AI Agents با Google Workspace

۱. قبل از شروع

هوش مصنوعی ورتکس چیست؟

ورتکس ای‌آی (Vertex AI) پلتفرم توسعه یکپارچه گوگل کلود (Google Cloud) برای ساخت، استقرار و مقیاس‌بندی عامل‌ها و برنامه‌های هوش مصنوعی در سطح سازمانی است. این پلتفرم، ابزارهای پیشرفته مورد نیاز برای معماری گردش‌های کاری عامل‌محور سفارشی را که عمیقاً با زیرساخت‌های در مقیاس جهانی ادغام شده‌اند، در اختیار توسعه‌دهندگان و دانشمندان داده قرار می‌دهد.

دسترسی به باغ مدل: از بین بیش از ۱۵۰ مدل پایه، از جمله خانواده کامل Gemini، مدل‌های شخص ثالث و مدل‌های متن‌باز تخصصی، مدل مناسب برای وظایف خاص عامل را انتخاب کنید.
معماری هماهنگ‌سازی پیچیده: هوش مصنوعی ورتکس چارچوبی را برای طراحی عامل‌های خودمختاری فراهم می‌کند که از استدلال برای برنامه‌ریزی، اجرای وظایف چند مرحله‌ای و فراخوانی APIهای خارجی استفاده می‌کنند.
اتصال به زمین در سطح سازمانی: اتصال اپراتورها به داده‌های زنده کسب‌وکار، شامل RAG (تولید افزوده بازیابی) با کارایی بالا، برای از بین بردن توهمات و اطمینان از صحت اطلاعات.
DevOps: توسعه عامل را به طور یکپارچه در خطوط لوله CI/CD موجود با SDK های قوی، API ها و ابزارهای ارزیابی ادغام کنید تا عملکرد و ایمنی عامل را در مقیاس بزرگ اندازه گیری کنید.
امنیت در سطح صنعتی: Vertex AI تضمین می‌کند که داده‌های مشتری که برای آموزش یا اتصال به زمین استفاده می‌شوند، خصوصی، رمزگذاری شده و مطابق با الزامات اقامت جهانی باقی می‌مانند.
زیرساخت بهینه‌شده: بارهای کاری عاملی را به راحتی در خوشه‌های TPU و GPU در سطح جهانی گوگل مقیاس‌بندی کنید و عملکرد با تأخیر کم را حتی برای پرمصرف‌ترین برنامه‌های جهانی تضمین کنید.

گوگل ورک اسپیس چیست؟

Google Workspace مجموعه‌ای از راهکارهای بهره‌وری و همکاری مبتنی بر ابر است که برای افراد، مدارس و کسب‌وکارها طراحی شده است:

ارتباطات: سرویس‌های ایمیل حرفه‌ای (Gmail)، کنفرانس ویدیویی (Meet) و پیام‌رسانی تیمی (Chat).
تولید محتوا: ابزارهایی برای نوشتن اسناد (Docs)، ساخت صفحات گسترده (Sheets) و طراحی ارائه‌ها (Slides).
سازماندهی: تقویم‌های مشترک (Calendars) و یادداشت‌برداری دیجیتال (Keep).
فضای ذخیره‌سازی: فضای ابری متمرکز برای ذخیره و اشتراک‌گذاری ایمن فایل‌ها (Drive).
مدیریت: کنترل‌های مدیریتی برای مدیریت کاربران و تنظیمات امنیتی (کنسول مدیریت فضای کاری).

چه نوع ادغام‌های سفارشی؟

Google Workspace و Vertex AI یک حلقه بازخورد قدرتمند ایجاد می‌کنند که در آن Workspace داده‌های بلادرنگ و زمینه همکاری را فراهم می‌کند، در حالی که Vertex AI مدل‌ها، استدلال عاملی و هماهنگی لازم برای خودکارسازی گردش‌های کاری هوشمند را ارائه می‌دهد.

اتصال هوشمند: انبارهای داده تحت مدیریت گوگل، APIها و سرورهای MCP (تحت مدیریت گوگل و سفارشی) به نمایندگان اجازه می‌دهد تا به طور ایمن و یکپارچه به داده‌های Workspace دسترسی داشته باشند و از طرف کاربران اقداماتی را انجام دهند.
عامل‌های سفارشی: با استفاده از طراحان بدون کد یا چارچوب‌های حرفه‌ای، تیم‌ها می‌توانند عامل‌های تخصصی مبتنی بر داده‌ها و اقدامات فضای کاری تحت مدیریت ادمین بسازند.
ادغام بومی: افزونه‌های فضای کاری، چه از طریق اجزای رابط کاربری اختصاصی و چه از طریق فرآیندهای پس‌زمینه، شکاف بین سیستم‌های هوش مصنوعی و برنامه‌هایی مانند چت و جیمیل را پر می‌کنند. این امر به کارشناسان اجازه می‌دهد تا دقیقاً در همان جایی که کاربران هستند، با آنها ملاقات کنند و از کمک‌های فوری و آگاهانه بهره‌مند شوند.

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

پیش‌نیازها

اگر می‌خواهید تمام مراحل را در محیط خودتان دنبال کنید، به موارد زیر نیاز خواهید داشت:

آشنایی اولیه با فضای ابری گوگل و پایتون .
یک پروژه Google Cloud که شما مالک آن هستید و دارای صورتحساب است. برای بررسی اینکه آیا صورتحساب یک پروژه موجود فعال است یا خیر، به تأیید وضعیت صورتحساب پروژه‌های خود مراجعه کنید. برای ایجاد یک پروژه و تنظیم صورتحساب، به ایجاد یک پروژه Google Cloud مراجعه کنید. برای تغییر مالکیت پروژه، به مدیریت اعضای پروژه یا تغییر مالکیت پروژه مراجعه کنید.
یک حساب کاربری تجاری یا سازمانی Google Workspace با دسترسی به Google Chat و ویژگی‌های هوشمند فعال .
رابط خط فرمان گوگل کلود (Google Cloud CLI) برای پروژه گوگل کلود شما نصب و راه‌اندازی شد .
پایتون ۳.۱۱+ نصب شده باشد، به دستورالعمل‌های موجود در وب‌سایت رسمی پایتون مراجعه کنید.

آنچه خواهید ساخت

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

اپلیکیشن جستجوی هوش مصنوعی ورتکس

این عامل به کاربران اجازه می‌دهد تا داده‌ها را جستجو کرده و اقداماتی را برای Workspace به زبان طبیعی خود انجام دهند. این عامل به عناصر زیر متکی است:

مدل: جمینی.
داده‌ها و اقدامات: داده‌های Vertex AI برای Google Workspace (تقویم، جیمیل، درایو) ذخیره می‌شوند.
میزبان عامل: جستجوی هوش مصنوعی ورتکس.
رابط کاربری: ویجت وب جستجوی هوش مصنوعی ورتکس.

نماینده سفارشی

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

مدل: جمینی.
داده‌ها و اقدامات: فروشگاه‌های داده هوش مصنوعی ورتکس برای Google Workspace (تقویم، جیمیل، درایو)، سرور پروتکل زمینه مدل جستجوی هوش مصنوعی ورتکس (MCP) تحت مدیریت گوگل، عملکرد ابزار سفارشی برای ارسال پیام‌های Google Chat (از طریق API Google Chat).
ابزارهای ساخت عامل: کیت توسعه عامل (ADK).
میزبان عامل: موتور عامل هوش مصنوعی ورتکس.
رابط کاربری: وب ADK

۱۴۵f۴۷f۴۵۳۳۲e۶be.png

افزونه‌ای کاربردی به عنوان افزونه‌ی Google Workspace

این عامل به کاربران اجازه می‌دهد تا داده‌ها را برای Workspace به زبان طبیعی خود در چارچوب رابط‌های کاربری برنامه Workspace جستجو کنند. این عامل به عناصر زیر متکی است:

مدل: جمینی.
داده‌ها و اقدامات: فروشگاه‌های داده هوش مصنوعی ورتکس برای Google Workspace (تقویم، جیمیل، درایو)، سرور پروتکل زمینه مدل جستجوی هوش مصنوعی ورتکس (MCP) تحت مدیریت گوگل، عملکرد ابزار سفارشی برای ارسال پیام‌های Google Chat (از طریق API Google Chat).
ابزارهای ساخت عامل: کیت توسعه عامل (ADK).
میزبان عامل: موتور عامل هوش مصنوعی ورتکس.
رابط کاربری: افزونه‌ی Google Workspace برای چت و جیمیل (به راحتی قابل گسترش به تقویم، درایو، اسناد، برگه‌ها و اسلایدها).
افزونه‌ی Google Workspace: اسکریپت برنامه‌ها، APIهای موتور عامل هوش مصنوعی Vertex، متنی (پیام انتخاب‌شده‌ی جیمیل).

آنچه یاد خواهید گرفت

نقاط ادغام بین Vertex AI Search و Google Workspace که داده‌ها و اقدامات را فعال می‌کنند.
گزینه‌های ساخت عامل‌های سفارشی میزبانی‌شده در Vertex AI.
روش‌هایی که کاربران می‌توانند به عواملی مانند ویجت وب جستجوی هوش مصنوعی ورتکس و برنامه‌های Google Workspace دسترسی داشته باشند.

۲. راه‌اندازی

قبل از ساخت راه‌حل‌ها، باید تنظیمات Vertex AI Applications پروژه را مقداردهی اولیه کنیم، APIهای مورد نیاز را فعال کنیم و فضای ذخیره‌سازی داده Vertex AI Workspace را ایجاد کنیم.

مفاهیم را مرور کنید

اپلیکیشن هوش مصنوعی ورتکس

یک برنامه هوش مصنوعی Vertex یک راهکار جامع و مدیریت‌شده در Google Cloud است که مدل‌های یادگیری ماشین (مانند عوامل هوش مصنوعی مولد یا موتورهای جستجو) را با داده‌های سازمانی و ابزارهای تخصصی ادغام می‌کند تا وظایف پیچیده‌ای مانند جستجوی معنایی، تولید محتوا یا تعامل خودکار با مشتری را انجام دهد.

فروشگاه داده هوش مصنوعی ورتکس

یک مخزن داده Vertex AI موجودیتی است که شامل داده‌های دریافت شده از یک منبع داده شخص ثالث مانند Google Workspace یا برنامه‌های شخص ثالث مانند Jira یا Shopify است. مخازن داده‌ای که حاوی داده‌های برنامه‌های شخص ثالث هستند، رابط‌های داده نیز نامیده می‌شوند.

تنظیمات برنامه‌های هوش مصنوعی Vertex را آغاز کنید

تنظیمات Vertex AI Applications را برای فعال کردن ایجاد عامل، مقداردهی اولیه کنید.

کنسول گوگل کلود را در یک تب جدید باز کنید، سپس این مراحل را دنبال کنید:

پروژه خود را انتخاب کنید.
در قسمت جستجوی Google Cloud، به AI Applications بروید

روی ادامه کلیک کنید و پس از بررسی و موافقت با شرایط، API را فعال کنید .
به تنظیمات (Settings) بروید.
در برگه احراز هویت ، گزینه سراسری (global) را ویرایش کنید.

هویت گوگل (Google Identity) را انتخاب کنید، سپس روی ذخیره (Save) کلیک کنید.

فعال کردن APIها

انباره‌های داده‌ی فضای کاری Vertex AI نیاز به فعال‌سازی APIها دارند:

در کنسول گوگل کلود ، APIهای تقویم، جیمیل و People را فعال کنید:

روی منو ☰ > APIها و خدمات > APIها و خدمات فعال‌شده کلیک کنید و سپس تأیید کنید که API تقویم گوگل ، API جیمیل و API افراد در لیست هستند.

ایجاد انبارهای داده

ایجاد فروشگاه داده گوگل درایو:

در کنسول گوگل کلود، به بخش «برنامه‌های هوش مصنوعی» (AI Applications ) بروید، سپس به بخش «ذخیره‌های داده» (Data Stores) بروید.

روی + ایجاد فروشگاه داده کلیک کنید.
در بخش منبع (Source) ، در زیر Google Drive ، روی «انتخاب» (Select) کلیک کنید.

۶۹۳۹۳۶۳۳۶۸bde36d.png

در قسمت داده‌ها ، همه را انتخاب کنید و روی ادامه کلیک کنید.

۵۰۴۴۲۴۳۳۲۲acec9e.png

در بخش پیکربندی ، نام کانکتور داده را روی drive تنظیم کنید و پس از بررسی و موافقت با هزینه‌های احتمالی، روی ادامه کلیک کنید.

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

ایجاد مخزن داده‌های تقویم گوگل:

روی + ایجاد فروشگاه داده کلیک کنید.
در بخش منبع ، عبارت «تقویم گوگل» را جستجو کنید و روی «انتخاب» کلیک کنید.
در بخش «اقدامات» ، روی «رد شدن» کلیک کنید.
در بخش پیکربندی ، نام کانکتور داده را روی calendar تنظیم کنید.
روی ایجاد کلیک کنید.
شما به طور خودکار به قسمت فروشگاه‌های داده هدایت می‌شوید که در آنجا می‌توانید فروشگاه داده تازه اضافه شده را مشاهده کنید.

ایجاد مخزن داده گوگل جیمیل:

روی + فروشگاه داده جدید کلیک کنید.
در قسمت منبع ، عبارت Google Gmail را جستجو کنید و روی انتخاب (Select) کلیک کنید.
در بخش «اقدامات» ، روی «رد شدن» کلیک کنید.
در بخش پیکربندی ، نام رابط داده را روی gmail تنظیم کنید.
روی ایجاد کلیک کنید.
شما به طور خودکار به قسمت فروشگاه‌های داده هدایت می‌شوید که در آنجا می‌توانید فروشگاه داده تازه اضافه شده را مشاهده کنید.

۳. اپلیکیشن جستجوی هوش مصنوعی ورتکس

مدل: جمینی.
داده‌ها و اقدامات: داده‌های Vertex AI برای Google Workspace (تقویم، جیمیل، درایو) ذخیره می‌شوند.
میزبان عامل: جستجوی هوش مصنوعی ورتکس.
رابط کاربری: ویجت وب جستجوی هوش مصنوعی ورتکس.

مفاهیم را مرور کنید

اپلیکیشن جستجوی هوش مصنوعی ورتکس

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

ابزارک وب جستجوی هوش مصنوعی ورتکس (Vertex AI Search Web Widge t) یک کامپوننت رابط کاربری از پیش ساخته شده و قابل تنظیم است که به توسعه دهندگان اجازه می‌دهد یک نوار جستجو و نتایج مبتنی بر هوش مصنوعی را مستقیماً در یک وب‌سایت با حداقل کدنویسی جاسازی کنند.

پیش‌نمایش جستجوی هوش مصنوعی ورتکس

پیش‌نمایش جستجوی هوش مصنوعی ورتکس (Vertex AI Search Preview) یک محیط آزمایشی داخلی در کنسول گوگل کلود (Google Cloud Console) است که به توسعه‌دهندگان اجازه می‌دهد پیکربندی‌های جستجو و پاسخ‌های تولیدی را قبل از پیاده‌سازی یکپارچه همان تنظیمات در یک ویجت وب آماده تولید ورتکس هوش مصنوعی ورتکس (Vertex AI Search) اعتبارسنجی کنند.

بررسی معماری راهکار

ایجاد برنامه

یک برنامه جستجوی جدید برای تثبیت ذخایر داده خود ایجاد کنید.

از کنسول ابری، به بخش برنامه‌های هوش مصنوعی > برنامه‌ها بروید و مراحل زیر را دنبال کنید:

روی + ایجاد برنامه کلیک کنید.
در قسمت Type ، زیر Custom search (general) ، روی Create کلیک کنید.

در بخش پیکربندی ، پس از بررسی و موافقت با قیمت‌ها، ویژگی‌های نسخه سازمانی و پاسخ‌های مولد (Generative Responses) را بررسی کنید.
نام برنامه را codelab قرار دهید.
یک شناسه بر اساس نام ایجاد می‌شود و در زیر فیلد نمایش داده می‌شود، آن را کپی کنید.
نام شرکت را روی Codelab تنظیم کنید.
گزینه چند-منطقه‌ای را روی global (Global) تنظیم کنید.
روی ادامه کلیک کنید.

۳۲۷۷۰۲cd۸۳۷cbb۱۸.png

در بخش داده‌ها ، محل ذخیره‌سازی داده‌ها (درایو ، جیمیل و تقویم) را انتخاب کنید، سپس روی ادامه کلیک کنید.

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

ظاهر بصری و رفتار ویجت جستجو را پیکربندی کنید.

به بخش پیکربندی‌ها (Configurations) بروید.
در تب رابط کاربری ، نوع جستجو را روی «جستجو با پیگیری‌ها» تنظیم کنید، سپس روی «ذخیره و انتشار» کلیک کنید.

برنامه را امتحان کنید

برنامه جستجو را مستقیماً در کنسول Google Cloud آزمایش کنید.

به پیش‌نمایش بروید، ویجت وب نمایش داده می‌شود.
در چت، عبارت Do I have any meetings today? را تایپ کنید و enter بزنید.
در چت، عبارت Did I receive an email on March 1st 2026? را تایپ کنید و enter را بزنید.
در چت، عبارت Give me the title of the latest Drive file I created تایپ کنید و enter بزنید.

۴. نماینده سفارشی

مدل: جمینی.
داده‌ها و اقدامات: فروشگاه‌های داده هوش مصنوعی ورتکس برای Google Workspace (تقویم، جیمیل، درایو)، سرور پروتکل زمینه مدل جستجوی هوش مصنوعی ورتکس (MCP) تحت مدیریت گوگل، عملکرد ابزار سفارشی برای ارسال پیام‌های Google Chat (از طریق API Google Chat).
ابزارهای ساخت عامل: کیت توسعه عامل (ADK).
میزبان عامل: موتور عامل هوش مصنوعی ورتکس.
رابط کاربری: وب ADK

مفاهیم را مرور کنید

کیت توسعه عامل (ADK)

کیت توسعه عامل (ADK) مجموعه‌ای تخصصی از ابزارها و چارچوب‌ها است که برای ساده‌سازی ایجاد عامل‌های هوش مصنوعی مستقل با ارائه ماژول‌های از پیش ساخته شده برای استدلال، مدیریت حافظه و ادغام ابزار طراحی شده است.

پروتکل زمینه مدل (MCP)

پروتکل زمینه مدل (MCP) یک استاندارد باز است که برای ایجاد یکپارچه‌سازی یکپارچه و ایمن بین برنامه‌های هوش مصنوعی و منابع داده یا ابزارهای مختلف از طریق یک رابط جهانی "plug-and-play" طراحی شده است.

ابزار عملکرد

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

وب ADK

ADK web رابط کاربری توسعه داخلی است که همراه با SDK ADK برای توسعه و اشکال‌زدایی آسان‌تر ارائه می‌شود.

بررسی معماری راهکار

بررسی کد منبع

عامل.py

کد زیر با Vertex AI احراز هویت می‌کند، ابزارهای Vertex AI Search MCP و Chat API را مقداردهی اولیه می‌کند و رفتار عامل را تعریف می‌کند.

احراز هویت : ACCESS_TOKEN را از متغیرهای محیطی بازیابی می‌کند تا فراخوانی‌های MCP و API را احراز هویت کند.
راه‌اندازی ابزارها : این مرحله vertexai_mcp ، مجموعه‌ای از ابزارها که به سرور Vertex AI Search Model Context Protocol (MCP) متصل می‌شود، و ابزار send_direct_message را مقداردهی اولیه می‌کند. این به عامل این امکان را می‌دهد که در میان فروشگاه‌های داده متصل شما جستجو کند و پیام‌های Google Chat ارسال کند.
تعریف عامل : این root_agent با استفاده از مدل gemini-2.5-flash تعریف می‌کند. این دستورالعمل‌ها به عامل می‌گویند که استفاده از ابزار جستجو برای بازیابی اطلاعات و ابزار send_direct_message را برای اقدامات در اولویت قرار دهد و عملاً عامل را در داده‌های سازمانی شما مستقر کند.

...
MODEL = "gemini-2.5-flash"

# Access token for authentication
ACCESS_TOKEN = os.environ.get("ACCESS_TOKEN")
if not ACCESS_TOKEN:
    raise ValueError("ACCESS_TOKEN environment variable must be set")

VERTEXAI_SEARCH_TIMEOUT = 15.0

def get_project_id():
    """Fetches the consumer project ID from the environment natively."""
    _, project = google.auth.default()
    if project:
        return project
    raise Exception(f"Failed to resolve GCP Project ID from environment.")

def find_serving_config_path():
    """Dynamically finds the default serving config in the engine."""
    project_id = get_project_id()
    engines = discoveryengine_v1.EngineServiceClient().list_engines(
        parent=f"projects/{project_id}/locations/global/collections/default_collection"
    )
    for engine in engines:
        # engine.name natively contains the numeric Project Number
        return f"{engine.name}/servingConfigs/default_serving_config"
    raise Exception(f"No Discovery Engines found in project {project_id}")

def send_direct_message(email: str, message: str) -> dict:
    """Sends a Google Chat Direct Message (DM) to a specific user by email address."""
    chat_client = chat_v1.ChatServiceClient(
        credentials=Credentials(token=ACCESS_TOKEN)
    )

    # 1. Setup the DM space or find existing one
    person = chat_v1.User(
        name=f"users/{email}",
        type_=chat_v1.User.Type.HUMAN
    )
    membership = chat_v1.Membership(member=person)
    space_req = chat_v1.Space(space_type=chat_v1.Space.SpaceType.DIRECT_MESSAGE)
    setup_request = chat_v1.SetUpSpaceRequest(
        space=space_req,
        memberships=[membership]
    )
    space_response = chat_client.set_up_space(request=setup_request)
    space_name = space_response.name
    
    # 2. Send the message
    msg = chat_v1.Message(text=message)
    message_request = chat_v1.CreateMessageRequest(
        parent=space_name,
        message=msg
    )
    message_response = chat_client.create_message(request=message_request)
    
    return {"status": "success", "message_id": message_response.name, "space": space_name}

vertexai_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://discoveryengine.googleapis.com/mcp",
        timeout=VERTEXAI_SEARCH_TIMEOUT,
        sse_read_timeout=VERTEXAI_SEARCH_TIMEOUT,
        headers={"Authorization": f"Bearer {ACCESS_TOKEN}"}
    ),
    tool_filter=['search']
)

# Answer nicely the following user queries:
#  - Please find my meetings for today, I need their titles and links
#  - What is the latest Drive file I created?
#  - What is the latest Gmail message I received?
#  - Please send the following message to someone@example.com: Hello, this is a test message.

root_agent = LlmAgent(
    model=MODEL,
    name='enterprise_ai',
    instruction=f"""
        You are a helpful assistant that always uses the Vertex AI MCP search tool to answer the user's message, unless the user asks you to send a message to someone.
        If the user asks you to send a message to someone, use the send_direct_message tool to send the message.
        You MUST unconditionally use the Vertex AI MCP search tool to find answer, even if you believe you already know the answer or believe the Vertex AI MCP search tool does not contain the data.
        The Vertex AI MCP search tool accesses the user's data through datastores including Google Drive, Google Calendar, and Gmail.
        Only use the Vertex AI MCP search tool with servingConfig and query parameters, do not use any other parameters.
        Always use the servingConfig {find_serving_config_path()} while using the Vertex AI MCP search tool.
    """,
    tools=[vertexai_mcp, FunctionTool(send_direct_message)]
)

دانلود کد منبع

برای شروع، کد نمونه را در محیط محلی خود دانلود کنید.

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

در یک ترمینال، دایرکتوری solutions/enterprise-ai-agent-local را باز کنید.

فعال کردن APIها

این راهکار نیاز به فعال‌سازی APIهای اضافی دارد:

در کنسول Google Cloud ، رابط‌های برنامه‌نویسی Vertex AI، Cloud Resource Manager و Google Chat را فعال کنید:

روی منو ☰ > APIها و خدمات > APIها و خدمات فعال‌شده کلیک کنید و سپس تأیید کنید که Vertex AI API ، Cloud Resource Manager API و Google Chat API در لیست هستند.

این راهکار نیاز به پیکربندی صفحه رضایت دارد:

در کنسول گوگل کلود ، روی منو ☰ > پلتفرم گوگل آث > برندسازی کلیک کنید.

روی شروع به کار کلیک کنید.
در قسمت اطلاعات برنامه ، نام برنامه را روی Codelab تنظیم کنید.
در ایمیل پشتیبانی کاربر ، یک آدرس ایمیل پشتیبانی انتخاب کنید که کاربران در صورت داشتن هرگونه سوال در مورد رضایت خود بتوانند با شما تماس بگیرند.
روی بعدی کلیک کنید.
در قسمت مخاطبان ، داخلی (Internal) را انتخاب کنید.
روی بعدی کلیک کنید.
در قسمت اطلاعات تماس ، یک آدرس ایمیل وارد کنید که از طریق آن بتوانید از هرگونه تغییر در پروژه خود مطلع شوید.
روی بعدی کلیک کنید.
در قسمت Finish ، سیاست داده‌های کاربر سرویس‌های API گوگل را مرور کنید و در صورت موافقت، گزینه «من با سیاست‌های داده‌های کاربر سرویس‌های API گوگل موافقم» را انتخاب کنید.
روی ادامه و سپس ایجاد کلیک کنید.

پیکربندی ذخیره شده است و شما به طور خودکار به Google Auth Platform > Overview هدایت می‌شوید.

برای کسب اطلاعات بیشتر، به راهنمای کامل پیکربندی رضایت OAuth مراجعه کنید.

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

یک کلاینت OAuth برای برنامه دسکتاپ جدید ایجاد کنید تا کاربر را در یک محیط محلی احراز هویت کند:

در کنسول گوگل کلود ، روی منو ☰ > پلتفرم گوگل آث > کلاینت‌ها کلیک کنید.

روی + ایجاد کلاینت کلیک کنید.
برای نوع برنامه ، برنامه دسکتاپ را انتخاب کنید.
نام را روی codelab تنظیم کنید.
روی ایجاد کلیک کنید. اعتبارنامه تازه ایجاد شده ظاهر می‌شود.
روی دانلود JSON کلیک کنید و فایل را با نام client_secret.json در دایرکتوری solutions/enterprise-ai-agent-local ذخیره کنید.

فعال کردن جستجوی هوش مصنوعی Vertex در MCP

در یک ترمینال، اجرا کنید:

gcloud beta services mcp enable discoveryengine.googleapis.com \
     --project=$(gcloud config get-value project)

پیکربندی برنامه چت

برنامه Google Chat را با جزئیات اطلاعاتی اولیه آن پیکربندی کنید.

در کنسول گوگل کلود ، در قسمت جستجوی گوگل کلود، Google Chat API را جستجو کنید، روی Google Chat API کلیک کنید، روی Manage کلیک کنید و در نهایت روی Configuration کلیک کنید.

نام و توضیحات برنامه را روی Vertex AI تنظیم کنید.
آدرس اینترنتی آواتار را روی https://developers.google.com/workspace/add-ons/images/quickstart-app-avatar.png تنظیم کنید.
گزینه‌ی «فعال کردن ویژگی‌های تعاملی» را از حالت انتخاب خارج کنید و سپس در پنجره‌ی محاوره‌ای ظاهر شده، روی «غیرفعال کردن» کلیک کنید.
برای ثبت وقایع، گزینه ثبت خطاها را انتخاب کنید.
روی ذخیره کلیک کنید.

اجرای Agent در ADK Web

با استفاده از رابط وب ADK، عامل را به صورت محلی راه‌اندازی کنید.

در یک ترمینال، دایرکتوری solutions/enterprise-ai-agent-local را باز کنید و سپس دستور زیر را اجرا کنید:

# 1. Authenticate with all the required scopes
gcloud auth application-default login \
  --client-id-file=client_secret.json \
   --scopes=https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/chat.spaces,https://www.googleapis.com/auth/chat.messages

# 2. Configure environment
export ACCESS_TOKEN=$(gcloud auth application-default print-access-token)
export GOOGLE_GENAI_USE_VERTEXAI=1
export GOOGLE_CLOUD_PROJECT=$(gcloud config get-value project)
export GOOGLE_CLOUD_LOCATION=us-central1

# 3. Create and activate a new virtual environment
python3 -m venv .venv
source .venv/bin/activate

# 4. Install poetry and project dependencies
pip install poetry
poetry install

# 5. Start ADK Web
adk web

۹۵fc30883ce3d56f.png

عامل را امتحان کنید

با چت کردن با نماینده سفارشی خود، جریان را تأیید کنید.

در مرورگر اینترنت خود، وب‌سایت ADK را باز کنید.
در چت، عبارت Please find my meetings for today, I need their titles and links تایپ کنید و enter بزنید.
عامل با فهرستی از رویدادهای تقویم (بسته به حساب کاربر) پاسخ می‌دهد.
در چت، عبارت Please send a Chat message to someone@example.com with the following text: Hello! و کلید enter فشار دهید.
نماینده با یک پیام تأیید پاسخ می‌دهد.

۱۴۵f۴۷f۴۵۳۳۲e۶be.png

۵. افزونه Agent به عنوان افزونه Google Workspace

مدل: جمینی.
داده‌ها و اقدامات: فروشگاه‌های داده هوش مصنوعی ورتکس برای Google Workspace (تقویم، جیمیل، درایو)، سرور پروتکل زمینه مدل جستجوی هوش مصنوعی ورتکس (MCP) تحت مدیریت گوگل، عملکرد ابزار سفارشی برای ارسال پیام‌های Google Chat (از طریق API Google Chat).
ابزارهای ساخت عامل: کیت توسعه عامل (ADK).
میزبان عامل: موتور عامل هوش مصنوعی ورتکس.
رابط کاربری: افزونه‌ی Google Workspace برای چت و جیمیل (به راحتی قابل گسترش به تقویم، درایو، اسناد، برگه‌ها و اسلایدها).
افزونه‌ی Google Workspace: اسکریپت برنامه‌ها، APIهای موتور عامل هوش مصنوعی Vertex، متنی (پیام انتخاب‌شده‌ی جیمیل).

مفاهیم را مرور کنید

افزونه‌ی گوگل ورک اسپیس

افزونه‌ی Google Workspace یک برنامه‌ی سفارشی است که یک یا چند برنامه‌ی Google Workspace (Gmail، Chat، Calendar، Docs، Drive، Meet، Sheets و Slides) را گسترش می‌دهد.

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

Apps Script یک پلتفرم جاوا اسکریپت مبتنی بر ابر است که توسط گوگل درایو پشتیبانی می‌شود و به شما امکان می‌دهد وظایف را در محصولات گوگل ادغام و خودکارسازی کنید.

چارچوب کارت فضای کاری گوگل

چارچوب کارت در Google Workspace به توسعه‌دهندگان امکان می‌دهد رابط‌های کاربری غنی و تعاملی ایجاد کنند. این چارچوب امکان ساخت کارت‌های سازمان‌یافته و بصری جذاب را فراهم می‌کند که می‌توانند شامل متن، تصاویر، دکمه‌ها و سایر ابزارک‌ها باشند. این کارت‌ها با ارائه اطلاعات ساختاریافته و فعال کردن اقدامات سریع مستقیماً در برنامه‌های Workspace، تجربه کاربری را بهبود می‌بخشند.

بررسی معماری راهکار

بررسی کد منبع

عامل

عامل.py

احراز هویت : از یک تابع کمکی _get_access_token_from_context برای بازیابی توکن احراز هویت ( CLIENT_AUTH_NAME ) که کلاینت تزریق می‌کند، استفاده می‌کند. این توکن برای فراخوانی ایمن سرویس‌های پایین‌دستی مانند Vertex AI Search MCP و ابزارهای Google Chat بسیار مهم است.
راه‌اندازی ابزارها : این مرحله vertexai_mcp ، مجموعه‌ای از ابزارها که به سرور Vertex AI Search Model Context Protocol (MCP) متصل می‌شود، و ابزار send_direct_message را مقداردهی اولیه می‌کند. این به عامل این امکان را می‌دهد که در میان فروشگاه‌های داده متصل شما جستجو کند و پیام‌های Google Chat ارسال کند.
تعریف عامل : این root_agent با استفاده از مدل gemini-2.5-flash تعریف می‌کند. این دستورالعمل‌ها به عامل می‌گویند که استفاده از ابزار جستجو برای بازیابی اطلاعات و ابزار send_direct_message را برای اقدامات در اولویت قرار دهد و عملاً عامل را در داده‌های سازمانی شما مستقر کند.

...
MODEL = "gemini-2.5-flash"

# Client injects a bearer token into the ToolContext state.
# The key pattern is "CLIENT_AUTH_NAME_<random_digits>".
# We dynamically parse this token to authenticate our MCP and API calls.
CLIENT_AUTH_NAME = "enterprise-ai"

VERTEXAI_SEARCH_TIMEOUT = 15.0

def get_project_id():
    """Fetches the consumer project ID from the environment natively."""
    _, project = google.auth.default()
    if project:
        return project
    raise Exception(f"Failed to resolve GCP Project ID from environment.")

def find_serving_config_path():
    """Dynamically finds the default serving config in the engine."""
    project_id = get_project_id()
    engines = discoveryengine_v1.EngineServiceClient().list_engines(
        parent=f"projects/{project_id}/locations/global/collections/default_collection"
    )
    for engine in engines:
        # engine.name natively contains the numeric Project Number
        return f"{engine.name}/servingConfigs/default_serving_config"
    raise Exception(f"No Discovery Engines found in project {project_id}")

def _get_access_token_from_context(tool_context: ToolContext) -> str:
    """Helper method to dynamically parse the intercepted bearer token from the context state."""
    escaped_name = re.escape(CLIENT_AUTH_NAME)
    pattern = re.compile(fr"^{escaped_name}_\d+$")
    # Handle ADK varying state object types (Raw Dict vs ADK State)
    state_dict = tool_context.state.to_dict() if hasattr(tool_context.state, 'to_dict') else tool_context.state
    matching_keys = [k for k in state_dict.keys() if pattern.match(k)]
    if matching_keys:
        return state_dict.get(matching_keys[0])
    raise Exception(f"No bearer token found in ToolContext state matching pattern {pattern.pattern}")

def auth_header_provider(tool_context: ToolContext) -> dict[str, str]:
    token = _get_access_token_from_context(tool_context)
    return {"Authorization": f"Bearer {token}"}

def send_direct_message(email: str, message: str, tool_context: ToolContext) -> dict:
    """Sends a Google Chat Direct Message (DM) to a specific user by email address."""
    chat_client = chat_v1.ChatServiceClient(
        credentials=Credentials(token=_get_access_token_from_context(tool_context))
    )

    # 1. Setup the DM space or find existing one
    person = chat_v1.User(
        name=f"users/{email}",
        type_=chat_v1.User.Type.HUMAN
    )
    membership = chat_v1.Membership(member=person)
    space_req = chat_v1.Space(space_type=chat_v1.Space.SpaceType.DIRECT_MESSAGE)
    setup_request = chat_v1.SetUpSpaceRequest(
        space=space_req,
        memberships=[membership]
    )
    space_response = chat_client.set_up_space(request=setup_request)
    space_name = space_response.name
    
    # 2. Send the message
    msg = chat_v1.Message(text=message)
    message_request = chat_v1.CreateMessageRequest(
        parent=space_name,
        message=msg
    )
    message_response = chat_client.create_message(request=message_request)
    
    return {"status": "success", "message_id": message_response.name, "space": space_name}

vertexai_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://discoveryengine.googleapis.com/mcp",
        timeout=VERTEXAI_SEARCH_TIMEOUT,
        sse_read_timeout=VERTEXAI_SEARCH_TIMEOUT
    ),
    tool_filter=['search'],
    # The auth_header_provider dynamically injects the bearer token from the ToolContext
    # into the MCP call for authentication.
    header_provider=auth_header_provider
)

# Answer nicely the following user queries:
#  - Please find my meetings for today, I need their titles and links
#  - What is the latest Drive file I created?
#  - What is the latest Gmail message I received?
#  - Please send the following message to someone@example.com: Hello, this is a test message.

root_agent = LlmAgent(
    model=MODEL,
    name='enterprise_ai',
    instruction=f"""
        You are a helpful assistant that always uses the Vertex AI MCP search tool to answer the user's message, unless the user asks you to send a message to someone.
        If the user asks you to send a message to someone, use the send_direct_message tool to send the message.
        You MUST unconditionally use the Vertex AI MCP search tool to find answer, even if you believe you already know the answer or believe the Vertex AI MCP search tool does not contain the data.
        The Vertex AI MCP search tool accesses the user's data through datastores including Google Drive, Google Calendar, and Gmail.
        Only use the Vertex AI MCP search tool with servingConfig and query parameters, do not use any other parameters.
        Always use the servingConfig {find_serving_config_path()} while using the Vertex AI MCP search tool.
    """,
    tools=[vertexai_mcp, FunctionTool(send_direct_message)]
)

مشتری

appsscript.json

پیکربندی زیر، محرک‌ها و مجوزهای افزونه را تعریف می‌کند.

افزونه را تعریف می‌کند : به Workspace می‌گوید که این پروژه یک افزونه برای Chat و Gmail است.
محرک‌های زمینه‌ای : برای جیمیل، یک contextualTrigger تنظیم می‌کند که هر زمان کاربر یک پیام ایمیل را باز می‌کند، onAddonEvent را فعال می‌کند. این به افزونه اجازه می‌دهد محتوای ایمیل را "ببیند".
مجوزها : این فهرست، oauthScopes های مورد نیاز برای اجرای افزونه را نشان می‌دهد، مانند مجوزهای خواندن ایمیل فعلی، اجرای اسکریپت و اتصال به سرویس‌های خارجی (مانند APIهای Vertex AI).

...
"addOns": {
    "common": {
      "name": "Vertex AI",
      "logoUrl": "https://developers.google.com/workspace/add-ons/images/quickstart-app-avatar.png"
    },
    "chat": {},
    "gmail": {
      "contextualTriggers": [
        {
          "unconditional": {},
          "onTriggerFunction": "onAddonEvent"
        }
      ]
    }
  },
  "oauthScopes": [
   "https://www.googleapis.com/auth/script.external_request",
   "https://www.googleapis.com/auth/cloud-platform",
   "https://www.googleapis.com/auth/gmail.addons.execute",
   "https://www.googleapis.com/auth/gmail.addons.current.message.readonly"
 ]
...

چت.gs

کد زیر پیام‌های ورودی گوگل چت را مدیریت می‌کند.

دریافت پیام‌ها : تابع onMessage نقطه ورود برای تعاملات پیام است.
Manages Context : این تابع space.name (شناسه فضای چت) را در ویژگی‌های کاربر ذخیره می‌کند. این تضمین می‌کند که وقتی عامل آماده پاسخ دادن است، دقیقاً می‌داند که پیام را به کدام مکالمه ارسال کند.
Delegates to Agent : این تابع requestAgent را فراخوانی می‌کند و پیام کاربر را به منطق اصلی که ارتباطات API را مدیریت می‌کند، ارسال می‌کند.

...
// Service that handles Google Chat operations.

// Handle incoming Google Chat message events, actions will be taken via Google Chat API calls
function onMessage(event) {
  if (isInDebugMode()) {
    console.log(`MESSAGE event received (Chat): ${JSON.stringify(event)}`);
  }
  // Extract data from the event.
  const chatEvent = event.chat;
  setChatConfig(chatEvent.messagePayload.space.name);

  // Request AI agent to answer the message
  requestAgent(chatEvent.messagePayload.message);
  // Respond with an empty response to the Google Chat platform to acknowledge execution
  return null; 
}

// --- Utility functions ---

// The Chat direct message (DM) space associated with the user
const SPACE_NAME_PROPERTY = "DM_SPACE_NAME"

// Sets the Chat DM space name for subsequent operations.
function setChatConfig(spaceName) {
  const userProperties = PropertiesService.getUserProperties();
  userProperties.setProperty(SPACE_NAME_PROPERTY, spaceName);
  console.log(`Space is set to ${spaceName}`);
}

// Retrieved the Chat DM space name to sent messages to.
function getConfiguredChat() {
  const userProperties = PropertiesService.getUserProperties();
  return userProperties.getProperty(SPACE_NAME_PROPERTY);
}

// Finds the Chat DM space name between the Chat app and the given user.
function findChatAppDm(userName) {
  return Chat.Spaces.findDirectMessage(
    { 'name': userName },
    {'Authorization': `Bearer ${getAddonCredentials().getAccessToken()}`}
  ).name;
}

// Creates a Chat message in the configured space.
function createMessage(message) {
  const spaceName = getConfiguredChat();
  console.log(`Creating message in space ${spaceName}...`);
  return Chat.Spaces.Messages.create(
    message,
    spaceName,
    {},
    {'Authorization': `Bearer ${getAddonCredentials().getAccessToken()}`}
  ).name;
}

کد زیر نوار کناری Gmail را ایجاد می‌کند و زمینه ایمیل را ثبت می‌کند.

رابط کاربری را می‌سازد : createSidebarCard با استفاده از سرویس Workspace Card رابط بصری را می‌سازد. این سرویس یک طرح‌بندی ساده با یک ناحیه ورودی متن و یک دکمه "ارسال پیام" ایجاد می‌کند.
ضبط متن ایمیل : در handleSendMessage ، کد بررسی می‌کند که آیا کاربر در حال حاضر در حال مشاهده یک ایمیل ( event.gmail.messageId ) است یا خیر. اگر چنین باشد، موضوع و متن ایمیل را به طور ایمن دریافت کرده و آن را به اعلان کاربر اضافه می‌کند.
نمایش نتیجه : به محض اینکه اپراتور پاسخ می‌دهد، کد، کارت نوار کناری را به‌روزرسانی می‌کند تا پاسخ را نشان دهد.

...
// Service that handles Gmail operations.

// Triggered when the user opens the Gmail Add-on or selects an email.
function onAddonEvent(event) {
  // If this was triggered by a button click, handle it
  if (event.parameters && event.parameters.action === 'send') {
    return handleSendMessage(event);
  }

  // Otherwise, just render the default initial sidebar
  return createSidebarCard();
}

// Creates the standard Gmail sidebar card consisting of a text input and send button.
// Optionally includes an answer section if a response was generated.
function createSidebarCard(optionalAnswerSection) {
  const card = CardService.newCardBuilder();
  const actionSection = CardService.newCardSection();

  // Create text input for the user's message
  const messageInput = CardService.newTextInput()
    .setFieldName("message")
    .setTitle("Message")
    .setMultiline(true);

  // Create action for sending the message
  const sendAction = CardService.newAction()
    .setFunctionName('onAddonEvent')
    .setParameters({ 'action': 'send' });

  const sendButton = CardService.newTextButton()
    .setText("Send message")
    .setTextButtonStyle(CardService.TextButtonStyle.FILLED)
    .setOnClickAction(sendAction);

  actionSection.addWidget(messageInput);
  actionSection.addWidget(CardService.newButtonSet().addButton(sendButton));

  card.addSection(actionSection);

  // Attach the response at the bottom if we have one
  if (optionalAnswerSection) {
    card.addSection(optionalAnswerSection);
  }

  return card.build();
}

// Handles clicks from the Send message button.
function handleSendMessage(event) {
  const commonEventObject = event.commonEventObject || {};
  const formInputs = commonEventObject.formInputs || {};
  const messageInput = formInputs.message;

  let userMessage = "";
  if (messageInput && messageInput.stringInputs && messageInput.stringInputs.value.length > 0) {
    userMessage = messageInput.stringInputs.value[0];
  }

  if (!userMessage || userMessage.trim().length === 0) {
    return CardService.newActionResponseBuilder()
      .setNotification(CardService.newNotification().setText("Please enter a message."))
      .build();
  }

  let finalQueryText = `USER MESSAGE TO ANSWER: ${userMessage}`;

  // If we have an email selected in Gmail, append its content as context
  if (event.gmail && event.gmail.messageId) {
    try {
      GmailApp.setCurrentMessageAccessToken(event.gmail.accessToken);
      const message = GmailApp.getMessageById(event.gmail.messageId);

      const subject = message.getSubject();
      const bodyText = message.getPlainBody() || message.getBody();

      finalQueryText += `\n\nEMAIL THE USER HAS OPENED ON SCREEN:\nSubject: ${subject}\nBody:\n---\n${bodyText}\n---`;
    } catch (e) {
      console.error("Could not fetch Gmail context: " + e);
      // Invalidate the token explicitly so the next prompt requests the missing scopes
      ScriptApp.invalidateAuth();

      CardService.newAuthorizationException()
        .setResourceDisplayName("Enterprise AI")
        .setAuthorizationUrl(ScriptApp.getAuthorizationUrl())
        .throwException();
    }
  }

  try {
    const response = queryAgent({ text: finalQueryText });

    // We leverage the 'showdown' library to parse the LLM's Markdown output into HTML
    // We also substitute markdown listings with arrows and adjust newlines for clearer rendering in the sidebar
    let displayedText = substituteListingsFromMarkdown(response.text);
    displayedText = new showdown.Converter().makeHtml(displayedText).replace(/\n/g, '\n\n');

    const textParagraph = CardService.newTextParagraph();
    textParagraph.setText(displayedText);

    const answerSection = CardService.newCardSection()
      .addWidget(textParagraph);

    const updatedCard = createSidebarCard(answerSection);

    return CardService.newActionResponseBuilder()
      .setNavigation(CardService.newNavigation().updateCard(updatedCard))
      .build();

  } catch (err) {
    return CardService.newActionResponseBuilder()
      .setNotification(CardService.newNotification().setText("Error fetching response: " + err.message))
      .build();
  }
}
...

AgentHandler.gs

کد زیر فراخوانی API به Vertex AI را هماهنگ می‌کند.

هماهنگ‌سازی فراخوانی API : queryAgent پلی بین افزونه شما و Vertex AI Agent Engine است. این ابزار درخواستی را ایجاد می‌کند که شامل درخواست کاربر و توکن احراز هویت در حالت (state) است.
پاسخ را پخش می‌کند : از آنجا که پاسخ‌های عامل ممکن است کمی طول بکشد، از API streamQuery با رویدادهای ارسالی از سرور (SSE) استفاده می‌کند. کد، پاسخ را به صورت تکه تکه جمع‌آوری کرده و پاسخ کامل را بازسازی می‌کند.

...
// Service that handles Vertex AI Agent operations.

// Submits a query to the AI agent and returns the response string synchronously
function queryAgent(input) {
 let systemPrompt = "SYSTEM PROMPT START Do not respond with tables but use bullet points instead." +
   " Do not ask the user follow-up questions or converse with them as history is not kept in this interface." +
   " SYSTEM PROMPT END\n\n";

 const requestPayload = {
   "class_method": "async_stream_query",
   "input": {
     "user_id": "vertex_ai_add_on",
     "message": { "role": "user", "parts": [{ "text": systemPrompt + input.text }] },
     "state_delta": {
       "enterprise-ai_999": `${ScriptApp.getOAuthToken()}`
     }
   }
 };

 const responseContentText = UrlFetchApp.fetch(
   `https://${getLocation()}-aiplatform.googleapis.com/v1/${getReasoningEngine()}:streamQuery?alt=sse`,
   {
     method: 'post',
     headers: { 'Authorization': `Bearer ${ScriptApp.getOAuthToken()}` },
     contentType: 'application/json',
     payload: JSON.stringify(requestPayload),
     muteHttpExceptions: true
   }
 ).getContentText();
  if (isInDebugMode()) {
   console.log(`Response: ${responseContentText}`);
 }

 const events = responseContentText.split('\n').map(s => s.replace(/^data:\s*/, '')).filter(s => s.trim().length > 0);
 console.log(`Received ${events.length} agent events.`);

 let author = "default";
 let answerText = "";
 for (const eventJson of events) {
   if (isInDebugMode()) {
     console.log("Event: " + eventJson);
   }
   const event = JSON.parse(eventJson);

   // Retrieve the agent responsible for generating the content
   author = event.author;
  
   // Ignore events that are not useful for the end-user
   if (!event.content) {
     console.log(`${author}: internal event`);
     continue;
   }

   // Handle text answers
   const parts = event.content.parts || [];
   const textPart = parts.find(p => p.text);
   if (textPart) {
     answerText += textPart.text;
   }
 }
 return { author: author, text: answerText };
}
...

استقرار عامل در موتور عامل هوش مصنوعی Vertex

در یک ترمینال، دایرکتوری solutions/enterprise-ai-agent را از منابع دانلود شده در مراحل قبلی باز کنید و سپس دستور زیر را اجرا کنید:

# 1. Create and activate a new virtual environment
deactivate
python3 -m venv .venv
source .venv/bin/activate

# 2. Install poetry and project dependencies
pip install poetry
poetry install

# 3. Deploy the agent
adk deploy agent_engine \
  --project=$(gcloud config get-value project) \
  --region=us-central1 \
  --display_name="Enterprise AI" \
  enterprise_ai

وقتی خط Deploying to agent engine... را در لاگ‌ها مشاهده کردید، یک ترمینال جدید باز کنید و دستور زیر را برای اضافه کردن مجوزهای لازم به Vertex AI Reasoning Engine Service Agent اجرا کنید:

# 1. Get the current Project ID
PROJECT_ID=$(gcloud config get-value project)

# 2. Extract the Project Number for that ID
PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projectNumber)')

# 3. Construct the Service Account name
SERVICE_ACCOUNT="service-${PROJECT_NUMBER}@gcp-sa-aiplatform-re.iam.gserviceaccount.com"

# 4. Apply the IAM policy binding
gcloud projects add-iam-policy-binding $PROJECT_ID \
     --member="serviceAccount:$SERVICE_ACCOUNT" \
     --role="roles/discoveryengine.viewer"

منتظر بمانید تا دستور adk deploy تکمیل شود، سپس نام منبع عامل تازه مستقر شده را از خروجی دستور به رنگ سبز کپی کنید.

شروع حساب کاربری سرویس

یک حساب کاربری سرویس اختصاصی برای تأیید عملیات سمت سرور افزونه ایجاد کنید.

در کنسول گوگل کلود ، مراحل زیر را دنبال کنید:

روی منو ☰ > مدیریت و دسترسی > حساب‌های سرویس > + ایجاد حساب سرویس کلیک کنید.

نام حساب سرویس را روی vertexai-add-on تنظیم کنید.

روی «انجام شد» کلیک کنید. شما به صفحه حساب‌های سرویس هدایت می‌شوید و می‌توانید حساب سرویسی را که ایجاد کرده‌اید مشاهده کنید.

حساب کاربری سرویس تازه ایجاد شده و سپس تب Keys را انتخاب کنید.
روی افزودن کلید و سپس ایجاد کلید جدید کلیک کنید.
JSON را انتخاب کنید و سپس روی ایجاد کلیک کنید.

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

ایجاد و پیکربندی پروژه اسکریپت برنامه‌ها

یک پروژه جدید Apps Script ایجاد کنید تا کد افزونه را میزبانی کرده و ویژگی‌های اتصال آن را پیکربندی کنید.

برای باز کردن پروژه‌ی افزونه‌ی Enterprise AI در Apps Script، روی دکمه‌ی زیر کلیک کنید:

روی نمای کلی > ایجاد یک کپی کلیک کنید.
در پروژه Apps Script خود، برای افزودن ویژگی‌های اسکریپت، روی تنظیمات پروژه > ویرایش ویژگی‌های اسکریپت > افزودن ویژگی اسکریپت کلیک کنید.
مقدار REASONING_ENGINE_RESOURCE_NAME را برابر با نام منبع عامل Vertex AI که در مراحل قبلی کپی شده است، قرار دهید. این نام دارای فرمت زیر است:

projects/<PROJECT_NUMBER>/locations/us-central1/reasoningEngines/<AGENT_ID>

مقدار APP_SERVICE_ACCOUNT_KEY را روی کلید JSON از فایل حساب سرویس دانلود شده در مراحل قبلی تنظیم کنید.
روی ذخیره ویژگی‌های اسکریپت کلیک کنید

به Gmail و Chat منتقل شوید

افزونه را مستقر کنید تا مستقیماً در Gmail و Google Chat آن را آزمایش کنید.

در پروژه Apps Script خود، این مراحل را دنبال کنید:

روی Deploy > Test deployments و سپس Install کلیک کنید. اکنون در Gmail در دسترس است.
روی کپی در زیر شناسه استقرار سر (Head Deployment ID) کلیک کنید.

در کنسول گوگل کلود ، مراحل زیر را دنبال کنید:

در فیلد جستجوی Google Cloud، Google Chat API را جستجو کنید، روی Google Chat API کلیک کنید، روی Manage و در نهایت روی Configuration کلیک کنید.

فعال کردن ویژگی‌های تعاملی را انتخاب کنید.
گزینه «پیوستن به فضاها و مکالمات گروهی» را از حالت انتخاب خارج کنید.
در بخش تنظیمات اتصال ، گزینه Apps Script را انتخاب کنید.
شناسه استقرار (Deployment ID) را روی شناسه استقرار اصلی (Head Deployment ID) که در مراحل قبلی کپی شده بود، تنظیم کنید.
در قسمت «قابلیت مشاهده» ، گزینه «این برنامه چت را برای افراد و گروه‌های خاص در دامنه فضای کاری خود در دسترس قرار دهید» را انتخاب کنید و آدرس ایمیل خود را وارد کنید.
روی ذخیره کلیک کنید.

افزونه را امتحان کنید

با افزونه‌ی زنده‌ی خود تعامل داشته باشید تا مطمئن شوید که می‌تواند داده‌ها را دریافت کند و به سوالات در زمینه پاسخ دهد.

گوگل چت را در یک تب جدید باز کنید، سپس این مراحل را دنبال کنید:

با برنامه چت Vertex AI یک فضای پیام مستقیم باز کنید.

۴۹۵۶۳۲۳۱۴dec5a5d.png

روی پیکربندی کلیک کنید و مراحل احراز هویت را طی کنید.
عبارت What are my meetings for today? را تایپ کنید و enter بزنید. برنامه‌ی Vertex AI Chat باید نتایج را نمایش دهد.

جیمیل را در یک تب جدید باز کنید، سپس این مراحل را دنبال کنید:

برای خودتان ایمیلی بفرستید که موضوع آن « We need to talk و متن آن Are you available today between 8 and 9 AM?
پیام ایمیل تازه دریافت شده را باز کنید.
افزونه Vertex AI را در نوار کناری باز کنید.
پیام را روی Do I have any meeting conflicts? تنظیم کنید.
روی ارسال پیام کلیک کنید.
پاسخ بعد از دکمه نمایش داده می‌شود.

۶. تمیز کردن

حذف پروژه گوگل کلود

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

احتیاط: حذف یک پروژه Google Cloud منجر به موارد زیر می‌شود:

همه چیز در پروژه حذف می‌شود. اگر از یک پروژه موجود برای این آزمایشگاه کد استفاده کرده‌اید، هر کار دیگری را که در پروژه انجام داده‌اید حذف می‌کنید.
شناسه‌های پروژه سفارشی از بین می‌روند. هنگام ایجاد این پروژه، ممکن است یک شناسه پروژه سفارشی ایجاد کرده باشید که می‌خواهید در آینده از آن استفاده کنید. برای حفظ URLهایی که از شناسه پروژه استفاده می‌کنند، مانند URL در appspot.com، منابع انتخاب شده درون پروژه را به جای کل پروژه حذف کنید.

در کنسول گوگل کلود ، مراحل زیر را دنبال کنید:

روی منو ☰ > مدیریت و شناسه کاربری > تنظیمات کلیک کنید.

روی خاموش کردن کلیک کنید.
شناسه پروژه را وارد کنید.
روی «در هر صورت خاموش شو» کلیک کنید.

۷. تبریک

تبریک! شما راهکارهایی ساخته‌اید که قدرت نزدیک‌تر کردن Vertex AI و Google Workspace را برای کارمندان به کار می‌گیرد!

بعدش چی؟

ما فقط رایج‌ترین موارد استفاده را در این آزمایشگاه کد به نمایش می‌گذاریم، اما حوزه‌های توسعه زیادی وجود دارد که ممکن است بخواهید در راه‌حل‌های خود در نظر بگیرید، مانند موارد زیر:

از ابزارهای توسعه‌دهنده مبتنی بر هوش مصنوعی مانند Gemini CLI و Antigravity استفاده کنید.
با سایر چارچوب‌ها و ابزارهای عامل مانند MCPهای سفارشی، فراخوانی‌های تابع سفارشی و رابط‌های کاربری مولد ادغام شود.
با سایر مدل‌های هوش مصنوعی، از جمله گمرک، که در پلتفرم‌های اختصاصی مانند Vertex AI میزبانی می‌شوند، ادغام شوید.
با سایر نمایندگان، که در پلتفرم‌های اختصاصی مانند Dialogflow یا توسط اشخاص ثالث از طریق Cloud Marketplace میزبانی می‌شوند، ادغام شوید.
برای توانمندسازی تیم‌ها، سازمان‌ها یا کاربران عمومی، عامل‌ها را در بازار ابری منتشر کنید.

بیشتر بدانید

منابع زیادی برای توسعه‌دهندگان وجود دارد، مانند ویدیوهای یوتیوب، وب‌سایت‌های مستندات، نمونه کدها و آموزش‌ها:

ادغام Vertex AI Agents با Google Workspace

۱. قبل از شروع

هوش مصنوعی ورتکس چیست؟

گوگل ورک اسپیس چیست؟

چه نوع ادغام‌های سفارشی؟

پیش‌نیازها

آنچه خواهید ساخت

اپلیکیشن جستجوی هوش مصنوعی ورتکس

نماینده سفارشی

افزونه‌ای کاربردی به عنوان افزونه‌ی Google Workspace

آنچه یاد خواهید گرفت

۲. راه‌اندازی

مفاهیم را مرور کنید

اپلیکیشن هوش مصنوعی ورتکس

فروشگاه داده هوش مصنوعی ورتکس

تنظیمات برنامه‌های هوش مصنوعی Vertex را آغاز کنید

فعال کردن APIها

ایجاد انبارهای داده

۳. اپلیکیشن جستجوی هوش مصنوعی ورتکس

مفاهیم را مرور کنید

اپلیکیشن جستجوی هوش مصنوعی ورتکس

ویجت وب جستجوی هوش مصنوعی ورتکس

پیش‌نمایش جستجوی هوش مصنوعی ورتکس

بررسی معماری راهکار

ایجاد برنامه

پیکربندی ابزارک وب

برنامه را امتحان کنید

۴. نماینده سفارشی

مفاهیم را مرور کنید

کیت توسعه عامل (ADK)

پروتکل زمینه مدل (MCP)

ابزار عملکرد

وب ADK

بررسی معماری راهکار

بررسی کد منبع

عامل.py

دانلود کد منبع

فعال کردن APIها

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

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

فعال کردن جستجوی هوش مصنوعی Vertex در MCP

پیکربندی برنامه چت

اجرای Agent در ADK Web

عامل را امتحان کنید

۵. افزونه Agent به عنوان افزونه Google Workspace

مفاهیم را مرور کنید

افزونه‌ی گوگل ورک اسپیس

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

چارچوب کارت فضای کاری گوگل

بررسی معماری راهکار

بررسی کد منبع

عامل

عامل.py

مشتری

appsscript.json

چت.gs

نوار کناری.gs

AgentHandler.gs

استقرار عامل در موتور عامل هوش مصنوعی Vertex

شروع حساب کاربری سرویس

ایجاد و پیکربندی پروژه اسکریپت برنامه‌ها

به Gmail و Chat منتقل شوید

افزونه را امتحان کنید

۶. تمیز کردن

حذف پروژه گوگل کلود

۷. تبریک

بعدش چی؟

بیشتر بدانید