درباره این codelab
1. نمای کلی
Agent یک برنامه مستقل است که با یک مدل هوش مصنوعی صحبت می کند تا یک عملیات مبتنی بر هدف را با استفاده از ابزارها و زمینه ای که دارد انجام دهد و قادر به تصمیم گیری مستقل مبتنی بر حقیقت است!
هنگامی که برنامه شما دارای چندین عامل است که به طور مستقل و با هم کار می کنند تا هدف بزرگتر خود را برآورده کنند و هر یک از نمایندگان آن به طور مستقل دانش و مسئولیت یک منطقه متمرکز خاص را داشته باشند، برنامه شما به یک سیستم چند عاملی تبدیل می شود.
کیت توسعه عامل (ADK)
کیت توسعه عامل (ADK) یک چارچوب انعطاف‌پذیر و ماژولار برای توسعه و استقرار عوامل هوش مصنوعی است. ADK از ساخت برنامه های پیچیده با ترکیب چندین نمونه عامل متمایز در یک سیستم چند عاملی (MAS) پشتیبانی می کند.
در ADK، یک سیستم چند عامله برنامه‌ای است که در آن عوامل مختلف، که اغلب یک سلسله مراتب را تشکیل می‌دهند، برای دستیابی به یک هدف بزرگتر با یکدیگر همکاری یا هماهنگی می‌کنند. ساختار برنامه شما به این روش مزایای قابل توجهی را ارائه می دهد، از جمله ماژولار بودن، تخصصی شدن، قابلیت استفاده مجدد، قابلیت نگهداری، و توانایی تعریف جریان های کنترل ساخت یافته با استفاده از عوامل گردش کار اختصاصی.
مواردی که برای یک سیستم چند عاملی باید در نظر داشت
اول ، داشتن درک و استدلال مناسب از تخصص برای هر نماینده مهم است. - "آیا می دانید چرا برای چیزی به یک عامل فرعی خاص نیاز دارید"، ابتدا آن را حل کنید.
دوم ، نحوه گردآوری آنها با یک عامل ریشه برای مسیریابی و درک هر یک از پاسخ ها.
سوم ، انواع مختلفی از مسیریابی عامل وجود دارد که می توانید در اینجا در این مستندات پیدا کنید. مطمئن شوید که کدام یک با جریان برنامه شما مطابقت دارد. همچنین زمینه ها و حالت های مختلفی که برای کنترل جریان سیستم چند عامله خود نیاز دارید چیست.
چیزی که خواهی ساخت
بیایید یک سیستم چند عاملی برای رسیدگی به بازسازی آشپزخانه بسازیم. این کاری است که ما انجام خواهیم داد. ما یک سیستم با 3 عامل ایجاد خواهیم کرد.
- نماینده پیشنهاد نوسازی
- نماینده بررسی مجوزها و انطباق
- نمایندگی بررسی وضعیت سفارش
نماینده پیشنهاد بازسازی، برای ایجاد سند پیشنهاد بازسازی آشپزخانه.
مجوزها و نماینده انطباق، برای مراقبت از مجوزها و وظایف مربوط به انطباق.
مامور بررسی وضعیت سفارش، برای بررسی وضعیت سفارش مواد با کار بر روی پایگاه داده مدیریت سفارش که ما در AlloyDB راه اندازی کرده ایم.
ما یک عامل ریشه خواهیم داشت که این عوامل را بر اساس نیاز سازماندهی می کند.
الزامات
2. قبل از شروع
یک پروژه ایجاد کنید
- در Google Cloud Console ، در صفحه انتخاب پروژه، یک پروژه Google Cloud را انتخاب یا ایجاد کنید.
- مطمئن شوید که صورتحساب برای پروژه Cloud شما فعال است. با نحوه بررسی فعال بودن صورتحساب در پروژه آشنا شوید.
همچنین اگر در حال خواندن این مطلب هستید و می‌خواهید چند اعتبار برای شروع کار با Google Cloud و استفاده از ADK دریافت کنید، از این پیوند برای بازخرید اعتبار استفاده کنید. برای بازخرید آن می توانید دستورالعمل های اینجا را دنبال کنید. لطفا توجه داشته باشید که این لینک فقط تا پایان اردیبهشت برای بازخرید معتبر است.
- Cloud Shell را با کلیک بر روی این پیوند فعال کنید. می توانید با کلیک بر روی دکمه مربوطه از Cloud Shell بین Cloud Shell Terminal (برای اجرای دستورات ابری) و Editor (برای ساخت پروژه ها) جابه جا شوید.
- پس از اتصال به Cloud Shell، با استفاده از دستور زیر بررسی می‌کنید که قبلاً احراز هویت شده‌اید و پروژه به ID پروژه شما تنظیم شده است:
gcloud auth list
- دستور زیر را در Cloud Shell اجرا کنید تا تأیید کنید که دستور gcloud از پروژه شما اطلاع دارد.
gcloud config list project
- اگر پروژه شما تنظیم نشده است، از دستور زیر برای تنظیم آن استفاده کنید:
gcloud config set project <YOUR_PROJECT_ID>
- حتما پایتون 3.9+ را داشته باشید
- API های زیر را با اجرای دستورات زیر فعال کنید:
gcloud services enable artifactregistry.googleapis.com \cloudbuild.googleapis.com \run.googleapis.com \aiplatform.googleapis.com
- برای دستورات و استفاده از gcloud به اسناد مراجعه کنید.
3. نمونه اولیه
اگر تصمیم به استفاده از مدل Gemini 2.5 Pro برای پروژه دارید، می توانید این مرحله را نادیده بگیرید.
به Google AI Studio بروید. شروع به تایپ کردن در درخواست خود کنید. این درخواست من است:
I want to renovate my kitchen, basically just remodel it. I don't know where to start. So I want to use Gemini to generate a plan. For that I need a good prompt. Give me a short yet detailed prompt that I can use.
پارامترها را در سمت راست تنظیم و پیکربندی کنید تا پاسخ بهینه را دریافت کنید.
بر اساس این توصیف ساده، Gemini از من یک درخواست فوق‌العاده دقیق برای شروع بازسازی من ساخت! در واقع، ما از Gemini برای دریافت پاسخ‌های بهتر از AI Studio و مدل‌هایمان استفاده می‌کنیم. همچنین می‌توانید مدل‌های مختلفی را بر اساس موارد استفاده خود انتخاب کنید.
ما Gemini 2.5 Pro را انتخاب کرده ایم. این یک مدل تفکر است، به این معنی که ما توکن‌های خروجی بیشتری، در این مورد تا 65 هزار توکن، برای تحلیل‌های طولانی و اسناد دقیق دریافت می‌کنیم. جعبه تفکر Gemini زمانی می آید که Gemini 2.5 Pro را فعال کنید که دارای قابلیت استدلال بومی است و می تواند درخواست های متنی طولانی را انجام دهد.
متن پاسخ را در زیر ببینید:
استودیوی هوش مصنوعی داده‌های من را تجزیه و تحلیل کرد و همه این موارد مانند کابینت‌ها، رومیزی‌ها، پشتی، کف‌پوش، سینک، انسجام، پالت رنگ و انتخاب مواد را تولید کرد. جمینی حتی به منابع استناد می کند!
بشویید و با مدل های مختلف آن را تکرار کنید تا از نتیجه راضی شوید. اما من می گویم چرا وقتی Gemini 2.5 دارید، همه اینها را مرور کنید :)
به هر حال، اکنون سعی کنید این ایده را با یک اعلان متفاوت ببینید:
Add flat and circular light accessories above the island area for my current kitchen in the attached image.
پیوندی به تصویر آشپزخانه فعلی خود (یا هر نمونه تصویر آشپزخانه ) ضمیمه کنید. مدل را به "Gemini 2.0 Flash Preview Image Generation" تغییر دهید تا به تولید تصاویر دسترسی داشته باشید.
من این خروجی رو گرفتم:
این قدرت جمینی است!
از درک ویدیوها، تولید تصاویر بومی، تا پایه‌گذاری اطلاعات واقعی با جستجوی Google – چیزهایی وجود دارند که فقط با Gemini ساخته می‌شوند.
از استودیوی هوش مصنوعی، می‌توانید این نمونه اولیه را بگیرید، کلید API را بگیرید و با استفاده از قدرت Vertex AI ADK آن را به یک برنامه کاربردی کامل تبدیل کنید.
4. راه اندازی ADK
- ایجاد و فعال کردن محیط مجازی (توصیه می شود)
از ترمینال Cloud Shell خود، یک محیط مجازی ایجاد کنید:
python -m venv .venv
فعال کردن محیط مجازی:
source .venv/bin/activate
- ADK را نصب کنید
pip install google-adk
5. ساختار پروژه
- از Cloud Shell Terminal ، یک دایرکتوری در محل پروژه مورد نظر خود ایجاد کنید
mkdir agentic-apps
cd agentic-apps
mkdir renovation-agent
- به Cloud Shell Editor بروید و با ایجاد فایل‌ها (برای شروع خالی) ساختار پروژه زیر را ایجاد کنید:
renovation-agent/
__init__.py
agent.py
.env
requirements.txt
6. کد منبع
- به « init .py» بروید و با محتوای زیر به‌روزرسانی کنید:
from . import agent
- به agent.py بروید و فایل را با محتوای زیر از مسیر زیر به روز کنید:
https://github.com/AbiramiSukumaran/adk-renovation-agent/blob/main/agent.py
در agent.py، وابستگی‌های لازم را وارد می‌کنیم، پارامترهای پیکربندی را از فایل .env بازیابی می‌کنیم و root_agent را تعریف می‌کنیم که 3 عامل فرعی را که در این برنامه ایجاد کرده‌ایم هماهنگ می‌کند. چندین ابزار وجود دارد که به عملکردهای اصلی و پشتیبانی این عوامل فرعی کمک می کند.
- مطمئن شوید که Cloud Storage Bucket را دارید
این برای ذخیره سند پیشنهادی است که عامل ایجاد می کند. آن را ایجاد کنید و دسترسی را فراهم کنید تا سیستم چند عاملی ایجاد شده با Vertex AI بتواند به آن دسترسی داشته باشد. در اینجا نحوه انجام این کار آمده است:
https://cloud.google.com/storage/docs/creating-buckets#console
نام سطل خود را " next-demo-store " بگذارید. اگر نام آن را چیز دیگری می‌گذارید، به یاد داشته باشید که مقدار STORAGE_BUCKET را در فایل env. به‌روزرسانی کنید (در مرحله تنظیم متغیرهای ENV).
- برای تنظیم دسترسی به سطل، به کنسول Cloud Storage و به Storage Bucket بروید (در مورد ما نام سطل "next-demo-storage" است: https://console.cloud.google.com/storage/browser/next-demo-storage .
به Permissions -> View Principals -> Grant Access بروید. Principals را به عنوان "allUsers" و Role را به عنوان "Storage Object User" انتخاب کنید.
Make sure to not enable "prevent public access". Since this is a demo/study application we are going with a public bucket. Remember to configure permission settings appropriately when you are building your application.
- ایجاد لیست وابستگی ها
همه وابستگی ها را در requirement.txt فهرست کنید. می توانید این را از repo کپی کنید.
توضیح کد منبع سیستم چند عاملی
فایل agent.py ساختار و رفتار سیستم چند عامله بازسازی آشپزخانه ما را با استفاده از کیت توسعه عامل (ADK) تعریف می کند. بیایید اجزای اصلی را تجزیه کنیم:
تعاریف عامل
RenovationProposalAgent
این نماینده مسئولیت ایجاد سند پیشنهادی بازسازی آشپزخانه را بر عهده دارد. به صورت اختیاری پارامترهای ورودی مانند اندازه آشپزخانه، سبک مورد نظر، بودجه و ترجیحات مشتری را می گیرد. بر اساس این اطلاعات، از یک مدل زبان بزرگ (LLM) Gemini 2.5 برای ایجاد یک پیشنهاد دقیق استفاده می کند. سپس پیشنهاد تولید شده در یک سطل فضای ذخیره سازی ابری Google ذخیره می شود.
PermitsAndComplianceCheckAgent
این نماینده بر حصول اطمینان از اینکه پروژه نوسازی به قوانین و مقررات محلی ساختمان پایبند است تمرکز می کند. اطلاعات مربوط به نوسازی پیشنهادی (به عنوان مثال، تغییرات ساختاری، کارهای الکتریکی، اصلاحات لوله کشی) را دریافت می کند و از LLM برای بررسی الزامات مجوز و قوانین انطباق استفاده می کند. عامل از اطلاعات یک پایگاه دانش استفاده می کند (که می توانید برای دسترسی به API های خارجی برای جمع آوری مقررات مربوطه آن را سفارشی کنید).
OrderingAgent
این نماینده، (اگر نمی‌خواهید اکنون اجرا کنید، می‌توانید نظر بدهید)، وضعیت سفارش مواد و تجهیزات مورد نیاز برای بازسازی را بررسی می‌کند. برای فعال کردن آن، باید یک تابع Cloud Run همانطور که در مراحل راه اندازی توضیح داده شد ایجاد کنید. سپس عامل این تابع Cloud Run را فراخوانی می کند که با پایگاه داده AlloyDB حاوی اطلاعات سفارش تعامل دارد. این یکپارچگی با یک سیستم پایگاه داده برای ردیابی داده های بلادرنگ را نشان می دهد.
عامل ریشه (ارکستراتور)
root_agent به عنوان ارکستراتور مرکزی سیستم چند عاملی عمل می کند. درخواست نوسازی اولیه را دریافت می‌کند و تعیین می‌کند که بر اساس نیازهای درخواست، کدام عوامل فرعی را فراخوانی کند. برای مثال، اگر درخواست نیاز به بررسی الزامات مجوز داشته باشد، PermitsAndComplianceCheckAgent را فراخوانی می کند. اگر کاربر بخواهد وضعیت سفارش را بررسی کند، با OrderingAgent تماس می گیرد (در صورت فعال بودن).
سپس root_agent پاسخ ها را از عوامل فرعی جمع آوری می کند و آنها را ترکیب می کند تا پاسخی جامع به کاربر ارائه دهد. این می تواند شامل خلاصه کردن پیشنهاد، فهرست کردن مجوزهای مورد نیاز و ارائه به روز رسانی وضعیت سفارش باشد.
جریان داده و مفاهیم کلیدی
کاربر درخواستی را از طریق رابط ADK (چه ترمینال یا رابط وب) آغاز می کند.
- درخواست توسط root_agent دریافت می شود.
- root_agent درخواست را تجزیه و تحلیل می کند و آن را به عوامل فرعی مناسب هدایت می کند.
- عوامل فرعی از LLM ها، پایگاه های دانش، API ها و پایگاه های داده برای پردازش درخواست و تولید پاسخ استفاده می کنند.
- عوامل فرعی پاسخ های خود را به root_agent برمی گردانند.
- root_agent پاسخ ها را ترکیب می کند و خروجی نهایی را به کاربر ارائه می دهد.
LLM (مدل های زبان بزرگ)
عوامل برای تولید متن، پاسخ به سؤالات و انجام وظایف استدلالی، به شدت به LLMها متکی هستند. LLMها "مغز"هایی هستند که در پشت توانایی نمایندگان برای درک و پاسخگویی به درخواست‌های کاربر قرار دارند. ما در این برنامه از Gemini 2.5 استفاده می کنیم.
Google Cloud Storage
برای ذخیره اسناد پیشنهادی بازسازی ایجاد شده استفاده می شود. شما باید یک سطل ایجاد کنید و مجوزهای لازم را برای دسترسی عوامل به آن بدهید.
اجرای ابری (اختیاری)
OrderingAgent از یک تابع Cloud Run برای ارتباط با AlloyDB استفاده می کند. Cloud Run یک محیط بدون سرور برای اجرای کد در پاسخ به درخواست های HTTP فراهم می کند.
AlloyDB
اگر از OrderingAgent استفاده می کنید، باید یک پایگاه داده AlloyDB برای ذخیره اطلاعات سفارش راه اندازی کنید. در بخش بعدی که «تنظیم پایگاه داده» است، به جزئیات آن خواهیم پرداخت.
فایل env
فایل .env اطلاعات حساسی مانند کلیدهای API، اعتبار پایگاه داده و نام سطل را ذخیره می کند. بسیار مهم است که این فایل را ایمن نگه دارید و آن را به مخزن خود متعهد نکنید. همچنین تنظیمات پیکربندی را برای نمایندگان و پروژه Google Cloud شما ذخیره می کند. root_agent یا توابع پشتیبان معمولاً مقادیر این فایل را می خوانند. مطمئن شوید که تمام متغیرهای مورد نیاز به درستی در فایل env. تنظیم شده اند. این شامل نام سطل Cloud Storage نیز می شود
7. راه اندازی پایگاه داده
در یکی از ابزارهای استفاده شده توسط ordering_agent به نام "check_status"، برای دریافت وضعیت سفارش ها به پایگاه داده سفارشات AlloyDB دسترسی پیدا می کنیم. در این بخش، کلاستر و نمونه پایگاه داده AlloyDB را تنظیم می کنیم.
یک خوشه و نمونه ایجاد کنید
- صفحه AlloyDB را در Cloud Console پیمایش کنید. یک راه آسان برای یافتن بیشتر صفحات در Cloud Console این است که آنها را با استفاده از نوار جستجوی کنسول جستجو کنید.
- CREATE CLUSTER را از آن صفحه انتخاب کنید:
- صفحه ای مانند تصویر زیر خواهید دید. یک خوشه و نمونه با مقادیر زیر ایجاد کنید (مطمئن شوید که مقادیر مطابقت دارند در صورتی که کد برنامه را از مخزن شبیه سازی می کنید):
- cluster id : "
vector-cluster" - رمز عبور : "
alloydb" - PostgreSQL 15 / آخرین توصیه شده است
- منطقه : "
us-central1" - شبکه سازی : "
default"
- وقتی شبکه پیش‌فرض را انتخاب می‌کنید، صفحه‌ای مانند تصویر زیر خواهید دید.
SET UP CONECTION را انتخاب کنید. 
- از آنجا، « استفاده از محدوده IP خودکار اختصاص داده شده » را انتخاب کنید و ادامه دهید. پس از بررسی اطلاعات، CREATE CONNECTION را انتخاب کنید.
- هنگامی که شبکه شما راه اندازی شد، می توانید به ایجاد خوشه خود ادامه دهید. روی CREATE CLUSTER کلیک کنید تا راه اندازی خوشه مطابق شکل زیر کامل شود:
مطمئن شوید که شناسه نمونه (که می توانید در زمان پیکربندی خوشه / نمونه پیدا کنید) را به تغییر دهید
vector-instance اگر نمی توانید آن را تغییر دهید، به یاد داشته باشید که از شناسه نمونه خود در همه مراجع بعدی استفاده کنید .
توجه داشته باشید که ایجاد Cluster حدود 10 دقیقه طول خواهد کشید. پس از موفقیت آمیز بودن، باید صفحه ای را ببینید که نمای کلی خوشه شما را که به تازگی ایجاد کرده اید نشان می دهد.
بلع داده ها
اکنون زمان اضافه کردن یک جدول با داده های مربوط به فروشگاه است. به AlloyDB بروید، خوشه اصلی و سپس AlloyDB Studio را انتخاب کنید:
ممکن است لازم باشد منتظر بمانید تا ایجاد نمونه شما به پایان برسد. پس از آن، با استفاده از اعتبارنامه هایی که هنگام ایجاد کلاستر ایجاد کردید، وارد AlloyDB شوید. از داده های زیر برای احراز هویت در PostgreSQL استفاده کنید:
- نام کاربری: "
postgres" - پایگاه داده: "
postgres" - رمز عبور: "
alloydb"
هنگامی که با موفقیت در AlloyDB Studio احراز هویت شدید، دستورات SQL در ویرایشگر وارد می شوند. می‌توانید چندین پنجره ویرایشگر را با استفاده از علامت مثبت در سمت راست آخرین پنجره اضافه کنید.
در صورت لزوم با استفاده از گزینه‌های Run، Format و Clear، دستورات AlloyDB را در پنجره‌های ویرایشگر وارد می‌کنید.
یک جدول ایجاد کنید
می توانید با استفاده از دستور DDL زیر در استودیو AlloyDB یک جدول ایجاد کنید:
-- Table DDL for Procurement Material Order Status
CREATE TABLE material_order_status (
order_id VARCHAR(50) PRIMARY KEY,
material_name VARCHAR(100) NOT NULL,
supplier_name VARCHAR(100) NOT NULL,
order_date DATE NOT NULL,
estimated_delivery_date DATE,
actual_delivery_date DATE,
quantity_ordered INT NOT NULL,
quantity_received INT,
unit_price DECIMAL(10, 2) NOT NULL,
total_amount DECIMAL(12, 2),
order_status VARCHAR(50) NOT NULL, -- e.g., "Ordered", "Shipped", "Delivered", "Cancelled"
delivery_address VARCHAR(255),
contact_person VARCHAR(100),
contact_phone VARCHAR(20),
tracking_number VARCHAR(100),
notes TEXT,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
quality_check_passed BOOLEAN, -- Indicates if the material passed quality control
quality_check_notes TEXT, -- Notes from the quality control check
priority VARCHAR(20), -- e.g., "High", "Medium", "Low"
project_id VARCHAR(50), -- Link to a specific project
receiver_name VARCHAR(100), -- Name of the person who received the delivery
return_reason TEXT, -- Reason for returning material if applicable
po_number VARCHAR(50) -- Purchase order number
);
درج رکوردها
عبارت insert query را از اسکریپت database_script.sql که در بالا ذکر شد در ویرایشگر کپی کنید.
روی Run کلیک کنید.
اکنون که مجموعه داده آماده است، بیایید یک برنامه Java Cloud Run Functions برای استخراج وضعیت ایجاد کنیم.
برای استخراج اطلاعات وضعیت سفارش، یک تابع Cloud Run در جاوا ایجاد کنید
- عملکرد Cloud Run را از اینجا ایجاد کنید: https://console.cloud.google.com/run/create?deploymentType=function
- نام تابع را روی " check-status " تنظیم کنید و " Java 17 " را به عنوان زمان اجرا انتخاب کنید.
- شما می توانید احراز هویت را روی " Allow unauthenticated invocations " تنظیم کنید زیرا این یک برنامه آزمایشی است.
- جاوا 17 را به عنوان زمان اجرا و ویرایشگر داخلی را برای کد منبع انتخاب کنید.
- در این مرحله، کد مکان نگهدارنده در ویرایشگر بارگذاری می شود.
کد مکان نگهدار را جایگزین کنید
- نام فایل جاوا را به " ProposalOrdersTool.java " و نام کلاس را به " ProposalOrdersTool " تغییر دهید.
- کد مکان نگهدار در ProposalOrdersTool.java و pom.xml را با کد فایل های مربوطه در پوشه "Cloud Run Function" در این مخزن جایگزین کنید.
- در ProposalOrdersTool.java خط کد زیر را بیابید، مقادیر مکان‌دار را با مقادیر پیکربندی خود جایگزین کنید:
String ALLOYDB_INSTANCE_NAME = "projects/<<YOUR_PROJECT_ID>>/locations/us-central1/clusters/<<YOUR_CLUSTER>>/instances/<<YOUR_INSTANCE>>";
- روی ایجاد کلیک کنید.
- عملکرد Cloud Run ایجاد و مستقر خواهد شد.
گام مهم:
پس از استقرار، برای اینکه به تابع Cloud اجازه دهیم به نمونه پایگاه داده AlloyDB ما دسترسی پیدا کند، ما کانکتور VPC را ایجاد می کنیم.
هنگامی که برای استقرار راه افتادید، باید بتوانید عملکردها را در کنسول Google Cloud Run Functions مشاهده کنید. تابع تازه ایجاد شده را جستجو کنید ( وضعیت بررسی )، روی آن کلیک کنید، سپس روی EDIT AND DEPLOY NEW REVISIONS (که با نماد EDIT (قلم) در بالای کنسول Cloud Run Functions مشخص می شود) کلیک کنید و موارد زیر را تغییر دهید:
- به تب Networking بروید:
- " Connect to a VPC for Outbound Traffic " را انتخاب کنید و سپس " Use Serverless VPC Access Connectors " را انتخاب کنید.
- در قسمت کشویی Network، تنظیمات، روی منوی کشویی Network کلیک کنید و گزینه " Add New VPC Connector " را انتخاب کنید (اگر قبلاً اتصال پیش فرض را پیکربندی نکرده اید) و دستورالعمل هایی را که در کادر محاوره ای ظاهر می شود دنبال کنید:
- نامی برای اتصال VPC ارائه دهید و مطمئن شوید که منطقه با نمونه شما یکسان است. مقدار Network را به عنوان پیش فرض بگذارید و Subnet را به عنوان محدوده IP سفارشی با محدوده IP 10.8.0.0 یا چیزی مشابه که در دسترس است تنظیم کنید.
- SHOW SCALING SETTINGS را باز کنید و مطمئن شوید که پیکربندی دقیقاً روی موارد زیر تنظیم شده است:
- روی CREATE کلیک کنید و این رابط باید اکنون در تنظیمات خروج لیست شود.
- کانکتور تازه ایجاد شده را انتخاب کنید.
- انتخاب کنید که تمام ترافیک از طریق این رابط VPC هدایت شود.
- روی NEXT و سپس DEPLOY کلیک کنید.
- پس از به روز رسانی Cloud Function، باید نقطه پایانی تولید شده را ببینید.
- شما باید بتوانید آن را با کلیک بر روی دکمه TEST در بالای کنسول Cloud Run Functions و با اجرای دستور به دست آمده در Cloud Shell Terminal آزمایش کنید.
- نقطه پایانی مستقر شده نشانی اینترنتی است که باید در متغیر env.
CHECK_ORDER_STATUS_ENDPOINTبه‌روزرسانی کنید.
8. راه اندازی مدل
توانایی نماینده شما برای درک درخواست‌های کاربر و ایجاد پاسخ توسط یک مدل زبان بزرگ (LLM) ارائه می‌شود. نماینده شما باید با این سرویس خارجی LLM تماس های ایمن برقرار کند که به اعتبارنامه احراز هویت نیاز دارد. بدون احراز هویت معتبر، سرویس LLM درخواست های عامل را رد می کند و عامل قادر به کار نخواهد بود.
- یک کلید API از Google AI Studio دریافت کنید.
- در مرحله بعدی که فایل .env را راه اندازی کردید،
<<your API KEY>>را با مقدار واقعی کلید API خود جایگزین کنید.
9. تنظیم متغیرهای ENV
- مقادیر خود را برای پارامترهای موجود در فایل template.env در این مخزن تنظیم کنید. در مورد من، .env این متغیرها را دارد:
GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=<<your API KEY>>
GOOGLE_CLOUD_LOCATION=us-central1 <<or your region>>
GOOGLE_CLOUD_PROJECT=<<your project id>>
PROJECT_ID=<<your project id>>
GOOGLE_CLOUD_REGION=us-central1 <<or your region>>
STORAGE_BUCKET=next-demo-store <<or your storage bucket name>>
CHECK_ORDER_STATUS_ENDPOINT=<<YOUR_ENDPOINT_TO_CLOUD FUNCTION_TO_READ_ORDER_DATA_FROM_ALLOYDB>>
جانشین ها را با مقادیر خود جایگزین کنید.
10. نماینده خود را اجرا کنید
- با استفاده از ترمینال، به دایرکتوری والد پروژه نماینده خود بروید:
cd renovation-agent
- همه وابستگی ها را نصب کنید
pip install -r requirements.txt
- برای اجرای عامل می توانید دستور زیر را در ترمینال Cloud Shell خود اجرا کنید:
adk run .
- می توانید موارد زیر را برای اجرای آن در یک UI وب ارائه شده ADK اجرا کنید:
adk web
- با دستورات زیر تست کنید:
user>>
Hello. Generate Proposal Document for the kitchen remodel requirement. I have no other specification.
12. استقرار به Agent Engine
اکنون که سیستم چند عاملی را برای عملکرد خوب آزمایش کرده‌اید، بیایید آن را بدون سرور و در فضای ابری برای هر کسی/هر برنامه‌ای که بتواند آن را مصرف کند، در دسترس قرار دهیم. قطعه کد زیر را در agent.py از مخزن آنها حذف کنید و می‌توانید سیستم چند عامله خود را مستقر کنید:
# Agent Engine Deployment:
# Create a remote app for our multiagent with agent Engine.
# This may take 1-2 minutes to finish.
# Uncomment the below segment when you're ready to deploy.
app = AdkApp(
agent=root_agent,
enable_tracing=True,
)
vertexai.init(
project=PROJECT_ID,
location=GOOGLE_CLOUD_LOCATION,
staging_bucket=STAGING_BUCKET,
)
remote_app = agent_engines.create(
app,
requirements=[
"google-cloud-aiplatform[agent_engines,adk]>=1.88",
"google-adk",
"pysqlite3-binary",
"toolbox-langchain==0.1.0",
"pdfplumber",
"google-cloud-aiplatform",
"cloudpickle==3.1.1",
"pydantic==2.10.6",
"pytest",
"overrides",
"scikit-learn",
"reportlab",
"google-auth",
"google-cloud-storage",
],
)
# Deployment to Agent Engine related code ends
این agent.py را دوباره از داخل پوشه پروژه با دستور زیر اجرا کنید:
>> cd adk-renovation-agent
>> python agent.py
تکمیل این کد چند دقیقه طول می کشد. پس از انجام این کار، یک نقطه پایانی به شکل زیر دریافت خواهید کرد:
'projects/123456789/locations/us-central1/reasoningEngines/123456'
با افزودن یک فایل جدید " test.py " می توانید عامل مستقر خود را با کد زیر آزمایش کنید.
import vertexai
from vertexai.preview import reasoning_engines
from vertexai import agent_engines
import os
import warnings
from dotenv import load_dotenv
load_dotenv()
GOOGLE_CLOUD_PROJECT = os.environ["GOOGLE_CLOUD_PROJECT"]
GOOGLE_CLOUD_LOCATION = os.environ["GOOGLE_CLOUD_LOCATION"]
GOOGLE_API_KEY = os.environ["GOOGLE_API_KEY"]
GOOGLE_GENAI_USE_VERTEXAI=os.environ["GOOGLE_GENAI_USE_VERTEXAI"]
AGENT_NAME = "adk_renovation_agent"
MODEL_NAME = "gemini-2.5-pro-preview-03-25"
warnings.filterwarnings("ignore")
PROJECT_ID = GOOGLE_CLOUD_PROJECT
reasoning_engine_id = "<<YOUR_DEPLOYED_ENGINE_ID>>"
vertexai.init(project=PROJECT_ID, location="us-central1")
agent = agent_engines.get(reasoning_engine_id)
print("**********************")
print(agent)
print("**********************")
for event in agent.stream_query(
user_id="test_user",
message="I want you to check order status.",
):
print(event)
در کد بالا، مقدار مکان‌نمای " <<YOUR_DEPLOYED_ENGINE_ID>> " را جایگزین کنید و دستور " python test.py " را اجرا کنید و همه شما آماده هستید که این را اجرا کنید تا با یک سیستم چند عاملی تعامل داشته باشید که Agent Engine مستقر شده و همه چیز برای بازسازی آشپزخانه شما آماده شده است!!!
13. گزینه های استقرار یک خطی
اکنون که سیستم چند عامله مستقر شده را آزمایش کردید، بیایید روش‌های ساده‌تری را بیاموزیم که مرحله استقرار را که در مرحله قبل انجام دادیم انتزاعی می‌کند: گزینه‌های استقرار یک خطی:
- برای اجرای ابری:
نحو:
adk deploy cloud_run \
--project=<<YOUR_PROJECT_ID>> \
--region=us-central1 \
--service_name=<<YOUR_SERVICE_NAME>> \
--app_name=<<YOUR_APP_NAME>> \
--with_ui \
./<<YOUR_AGENT_PROJECT_NAME>>
در این مورد:
adk deploy cloud_run \
--project=<<YOUR_PROJECT_ID>> \
--region=us-central1 \
--service_name=renovation-agent \
--app_name=renovation-app \
--with_ui \
./renovation-agent
می توانید از نقطه پایانی مستقر برای ادغام های پایین دست استفاده کنید.
- به موتور عامل:
نحو:
adk deploy agent_engine \
--project <your-project-id> \
--region us-central1 \
--staging_bucket gs://<your-google-cloud-storage-bucket> \
--trace_to_cloud \
path/to/agent/folder
در این مورد:
adk deploy agent_engine --project <<YOUR_PROJECT_ID>> --region us-central1 --staging_bucket gs://<<YOUR_BUCKET_NAME>> --trace_to_cloud renovation-agent
باید یک عامل جدید را در رابط کاربری Agent Engine در Google Cloud Console ببینید. برای جزئیات بیشتر به این وبلاگ مراجعه کنید.
14. پاک کن
برای جلوگیری از تحمیل هزینه به حساب Google Cloud خود برای منابع استفاده شده در این پست، این مراحل را دنبال کنید:
- در کنسول Google Cloud، به صفحه مدیریت منابع بروید.
- در لیست پروژه، پروژه ای را که می خواهید حذف کنید انتخاب کنید و سپس روی Delete کلیک کنید.
- در محاوره، شناسه پروژه را تایپ کنید و سپس روی Shut down کلیک کنید تا پروژه حذف شود.
15. تبریک میگم
تبریک می گویم! شما با موفقیت اولین نماینده خود را با استفاده از ADK ایجاد کردید و با آن تعامل داشتید!