1. قبل از شروع
به قسمت اول مجموعه «ساخت عوامل هوش مصنوعی با ADK» خوش آمدید! در این سری نرم افزارهای کاربردی، شما سفری هیجان انگیز را آغاز خواهید کرد تا با استفاده از کیت توسعه عامل گوگل (ADK)، عامل هوش مصنوعی بسیار هوشمند خود را بسازید.
ما با موارد ضروری شروع خواهیم کرد و شما را در راه‌اندازی محیط توسعه و ایجاد یک عامل مکالمه اساسی راهنمایی می‌کنیم. در پایان این آزمایشگاه کد، شما اولین هوش مصنوعی تعاملی خود را خواهید ساخت که آماده است تا در بخش‌های بعدی این مجموعه توسعه یابد، زیرا ما آن را به یک سیستم چند عاملی پیچیده (MAS) تبدیل می‌کنیم.
می‌توانید این کد را در محیط محلی خود یا در Google Cloud تکمیل کنید. برای ثابت‌ترین تجربه، توصیه می‌کنیم از Cloud Shell از محیط Google Cloud استفاده کنید. Cloud Shell همچنین 5 گیگابایت فضای ذخیره‌سازی دائمی را در فهرست $HOME فراهم می‌کند. این برای ذخیره اسکریپت ها، فایل های پیکربندی یا مخازن کلون شده مفید است.
پیش نیازها
- درک مفاهیم هوش مصنوعی مولد
- مهارت اولیه در برنامه نویسی پایتون
- آشنایی با خط فرمان / ترمینال
چیزی که یاد خواهید گرفت
- نحوه راه اندازی محیط پایتون
- نحوه ایجاد یک نماینده دستیار شخصی ساده با استفاده از ADK
- نحوه اجرا، تست و اشکال زدایی عامل
آنچه شما نیاز دارید
- یک کامپیوتر کارآمد و وای فای قابل اعتماد
- مرورگری مانند Chrome برای دسترسی به Google Cloud Console
- ذهن کنجکاو و اشتیاق به یادگیری
بازخرید یک حساب صورتحساب آزمایشی
برای تکمیل این کد، به یک حساب صورتحساب Google Cloud فعال نیز نیاز دارید. اگر هنوز حسابی ندارید، این مراحل را برای استفاده از حساب صورتحساب آزمایشی دنبال کنید:
- یک پنجره ناشناس در مرورگر خود باز کنید
- به این پورتال رستگاری بروید
- با استفاده از اکانت جیمیل شخصی خود وارد شوید
- دستورالعمل های گام به گام پورتال را دنبال کنید
2. مقدمه
دنیای هوش مصنوعی (GenAI) به سرعت در حال تکامل است و عوامل هوش مصنوعی در حال حاضر موضوع داغی هستند. عامل هوش مصنوعی یک برنامه کامپیوتری هوشمند است که برای عمل از طرف شما طراحی شده است، دقیقاً مانند یک دستیار شخصی. می تواند محیط دیجیتال خود را درک کند، تصمیم بگیرد و بدون کنترل مستقیم انسان برای دستیابی به اهداف خاص اقداماتی انجام دهد. به آن به عنوان یک موجود فعال و مستقل فکر کنید که می تواند یاد بگیرد و برای انجام کارها سازگار شود.
در هسته خود، یک عامل هوش مصنوعی از یک مدل زبان بزرگ (LLM) به عنوان "مغز" خود برای درک و استدلال استفاده می کند. این به آن اجازه می دهد تا اطلاعات را از منابع مختلف مانند متن، تصاویر و صداها پردازش کند. سپس عامل از این درک برای ایجاد یک برنامه و اجرای یک سری وظایف برای رسیدن به یک هدف از پیش تعریف شده استفاده می کند.
به دلیل چارچوب‌های آماده مانند Agent Development Kit (ADK) اکنون می‌توانید به راحتی عوامل هوش مصنوعی خود را بسازید، حتی بدون تخصص عمیق. ما این سفر را با ایجاد یک نماینده دستیار شخصی برای کمک به شما در انجام وظایفتان آغاز خواهیم کرد. بیایید شروع کنیم!
3. Google Cloud Services را پیکربندی کنید
یک پروژه Google Cloud ایجاد کنید
با ایجاد یک پروژه Google Cloud جدید شروع کنید تا فعالیت‌های این کد لبه فقط در این پروژه جدید جدا شوند.
- به console.cloud.google.com/projectcreate بروید
- اطلاعات مورد نیاز را وارد کنید:
- نام پروژه - می توانید هر نامی را که می خواهید وارد کنید (به عنوان مثال genai-workshop)
- مکان - آن را به عنوان بدون سازمان رها کنید
- حساب صورتحساب - اگر این گزینه را می‌بینید، حساب صورتحساب آزمایشی Google Cloud Platform را انتخاب کنید. اگر این گزینه را نمی بینید نگران نباشید. فقط به مرحله بعدی بروید.
- شناسه پروژه تولید شده را کپی کنید، بعداً به آن نیاز خواهید داشت.
- اگر همه چیز خوب است، روی دکمه ایجاد کلیک کنید
Cloud Shell را پیکربندی کنید
هنگامی که پروژه شما با موفقیت ایجاد شد، مراحل زیر را برای راه اندازی Cloud Shell انجام دهید.
1. Cloud Shell را راه اندازی کنید
به shell.cloud.google.com بروید و اگر پنجره بازشوی را مشاهده کردید که از شما می‌خواهد مجوز بدهید، روی تأیید کلیک کنید.
2. شناسه پروژه را تنظیم کنید
برای تنظیم Project ID صحیح دستور زیر را در ترمینال Cloud Shell اجرا کنید. <your-project-id> با شناسه پروژه واقعی خود که از مرحله ایجاد پروژه در بالا کپی شده است، جایگزین کنید.
gcloud config set project <your-project-id>
اکنون باید ببینید که پروژه صحیح در ترمینال Cloud Shell انتخاب شده است. شناسه پروژه انتخاب شده با رنگ زرد برجسته شده است.
3. API های مورد نیاز را فعال کنید
برای استفاده از سرویس‌های Google Cloud، ابتدا باید API مربوط به پروژه خود را فعال کنید. برای فعال کردن خدمات این Codelab دستورات زیر را در ترمینال Cloud Shell اجرا کنید:
gcloud services enable aiplatform.googleapis.com
اگر عملیات موفقیت آمیز بود، می بینید که Operation/... finished successfully در ترمینال شما چاپ شده است.
4. یک محیط مجازی پایتون ایجاد کنید
قبل از شروع هر پروژه پایتون، تمرین خوبی است که یک محیط مجازی ایجاد کنید. این امر وابستگی های پروژه را جدا می کند و از درگیری با پروژه های دیگر یا بسته های جهانی پایتون سیستم جلوگیری می کند.
1. دایرکتوری پروژه را ایجاد کنید و به آن بروید:
mkdir ai-agents-adk
cd ai-agents-adk
2. ایجاد و فعال سازی یک محیط مجازی:
uv venv --python 3.12
source .venv/bin/activate
( ai-agents-adk ) را خواهید دید که پیشوند فرمان ترمینال شما را نشان می دهد که نشان می دهد محیط مجازی فعال است.
3. صفحه adk را نصب کنید
uv pip install google-adk
5. یک عامل ایجاد کنید
در حالی که محیط شما آماده است، وقت آن است که پایه و اساس عامل هوش مصنوعی خود را ایجاد کنید. ADK برای تعریف منطق و پیکربندی عامل شما به چند فایل نیاز دارد:
-
agent.py: حاوی کد اصلی پایتون عامل شما، نام آن، LLM مورد استفاده و دستورالعمل های اصلی است. -
__init__.py: دایرکتوری را به عنوان یک بسته پایتون علامت گذاری می کند و به ADK کمک می کند تعریف عامل شما را کشف و بارگیری کند. -
.env: اطلاعات حساس و متغیرهای پیکربندی مانند کلید API، شناسه پروژه و مکان را ذخیره می کند.
این دستور یک دایرکتوری جدید به نام personal_assistant ایجاد می کند که حاوی سه فایل ضروری است.
adk create personal_assistant
پس از اجرای دستور، از شما خواسته می شود که چند گزینه را برای پیکربندی عامل خود انتخاب کنید.
برای اولین مرحله، گزینه 1 را انتخاب کنید تا از مدل gemini-2.5-flash استفاده کنید، مدلی سریع و کارآمد که برای کارهای مکالمه عالی است.
Choose a model for the root agent: 1. gemini-2.5-flash 2. Other models (fill later) Choose model (1, 2): 1
برای مرحله دوم، Vertex AI (گزینه ۲) ، پلتفرم هوش مصنوعی قدرتمند و مدیریت شده Google Cloud را به عنوان ارائه‌دهنده خدمات باطنی انتخاب کنید.
1. Google AI 2. Vertex AI Choose a backend (1, 2): 2
پس از آن، باید بررسی کنید که شناسه پروژه نشان داده شده در براکت [...] به درستی تنظیم شده است. اگر اینطور است، Enter را فشار دهید . اگر نه، شناسه پروژه صحیح را در اعلان زیر وارد کنید:
Enter Google Cloud project ID [your-project-id]:
در نهایت، در سوال بعدی Enter را فشار دهید تا us-central1 به عنوان منطقه این کد لبه استفاده کنید.
Enter Google Cloud region [us-central1]:
شما باید خروجی مشابهی را در ترمینال خود مشاهده کنید.
Agent created in /home/<your-username>/ai-agent-adk/personal_assistant: - .env - __init__.py - agent.py
6. کدهای عامل را کاوش کنید
برای مشاهده فایل های ایجاد شده، پوشه ai-agents-adk در Cloud Shell Editor باز کنید.
- روی File > Open Folder... در منوی بالا کلیک کنید.
- پوشه
ai-agents-adkپیدا کرده و انتخاب کنید - روی OK کلیک کنید.
اگر نوار منوی بالایی برای شما ظاهر نشد، می توانید روی نماد پوشه ها نیز کلیک کرده و Open Folder را انتخاب کنید.
پس از بارگیری کامل پنجره ویرایشگر، به پوشه دستیار شخصی بروید. فایل های لازم را همانطور که در بالا ذکر شد مشاهده خواهید کرد ( agent.py ، __init__.py ، و .env ).
فایل .env اغلب به طور پیش فرض پنهان است. برای قابل مشاهده کردن آن در ویرایشگر پوسته ابری :
- به نوار منو در بالا بروید،
- روی View کلیک کنید و
- Toggle Hidden Files را انتخاب کنید.
محتوای هر فایل را بررسی کنید.
agent.py
این فایل عامل شما را با استفاده از کلاس Agent از کتابخانه google.adk.agents نمونه می کند.
from google.adk.agents import Agent
root_agent = Agent(
model='gemini-2.5-flash',
name='root_agent',
description='A helpful assistant for user questions.',
instruction='Answer user questions to the best of your knowledge',
)
from google.adk.agents import Agent: این خط کلاسAgentلازم را از کتابخانه ADK وارد می کند.-
root_agent = Agent(...): در اینجا، شما در حال ایجاد یک نمونه از عامل هوش مصنوعی خود هستید. -
name="root_agent": یک شناسه منحصر به فرد برای نماینده شما. به این ترتیب ADK نماینده شما را تشخیص می دهد و به آن ارجاع می دهد. -
model="gemini-2.5-flash": این پارامتر حیاتی مشخص می کند که نماینده شما از کدام مدل زبان بزرگ (LLM) به عنوان "مغز" زیربنایی خود برای درک، استدلال و ایجاد پاسخ استفاده کند.gemini-2.5-flashیک مدل سریع و کارآمد مناسب برای کارهای مکالمه است. -
description="...": خلاصه ای مختصر از هدف یا قابلیت های عامل ارائه می دهد. توصیف بیشتر برای درک انسان یا برای سایر عوامل در یک سیستم چند عاملی است تا بفهمند این عامل خاص چه می کند. اغلب برای ورود به سیستم، اشکال زدایی یا هنگام نمایش اطلاعات مربوط به عامل استفاده می شود. -
instruction="...": این اعلان سیستمی است که رفتار نماینده شما را هدایت می کند و شخصیت آن را تعریف می کند. به LLM می گوید که چگونه باید عمل کند و هدف اصلی آن چیست. در این مورد، عامل را به عنوان "دستیار مفید" معرفی می کند. این دستورالعمل برای شکل دادن به سبک مکالمه و قابلیت های عامل کلیدی است.
init .py
این فایل برای پایتون لازم است تا personal-assistant به عنوان یک بسته تشخیص دهد و به ADK اجازه می دهد فایل agent.py شما را به درستی وارد کند.
from . import agent
from . import agent: این خط یک import نسبی را انجام می دهد و به پایتون می گوید که به دنبال ماژولی به نامagent(که مربوط بهagent.pyاست) در بسته فعلی (personal-assistant) بگردد. این خط ساده تضمین می کند که وقتی ADK سعی می کند عاملpersonal-assistantشما را بارگیری کند، می تواندroot_agentتعریف شده درagent.pyرا پیدا کرده و مقداردهی اولیه کند. حتی اگر خالی باشد، وجود__init__.pyچیزی است که دایرکتوری را به یک بسته پایتون تبدیل می کند.
env
این فایل دارای تنظیمات محیطی خاص و اعتبارنامه های حساس است.
GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID
GOOGLE_CLOUD_LOCATION=YOUR_PROJECT_LOCATION
GOOGLE_GENAI_USE_VERTEXAI: این به ADK می گوید که شما قصد دارید از سرویس هوش مصنوعی Vertex Google برای عملیات هوش مصنوعی خود استفاده کنید. این برای استفاده از سرویس‌های مدیریت شده Google Cloud و مدل‌های پیشرفته مهم است.-
GOOGLE_CLOUD_PROJECT: این متغیر شناسه منحصربه‌فرد پروژه Google Cloud شما را نگه می‌دارد. ADK برای ارتباط صحیح نماینده شما با منابع ابری شما و فعال کردن صورتحساب به این نیاز دارد. -
GOOGLE_CLOUD_LOCATION: این منطقه Google Cloud را مشخص می کند که منابع Vertex AI شما در آن قرار دارند (به عنوان مثال،us-central1). استفاده از مکان صحیح تضمین می کند که نماینده شما می تواند به طور موثر با خدمات Vertex AI در آن منطقه ارتباط برقرار کند.
7. عامل را در ترمینال اجرا کنید
با هر سه فایل در محل، شما آماده هستید تا عامل را مستقیماً از ترمینال اجرا کنید. برای این کار دستور adk run زیر را در ترمینال اجرا کنید:
adk run personal_assistant
اگر همه چیز به درستی تنظیم شده باشد، خروجی مشابهی را در ترمینال خود خواهید دید. در حال حاضر نگران هشدارها نباشید، تا زمانی که [user]: شما خوب هستید که ادامه دهید.
... Running agent personal_assistant, type exit to exit. [user]: ...
برو جلو و با نماینده چت کن! چیزی مانند "سلام. چه کاری می توانید برای من انجام دهید؟" و شما باید یک پاسخ دریافت کنید.
... Running agent personal_assistant, type exit to exit. [user]: hello. What can you do for me? [personal_assistant]: Hello! I am a large language model, trained by Google. I can do many things to help you, such as: ...
متوجه خواهید شد که خروجی گاهی اوقات با Markdown فرمت می شود که خواندن آن در ترمینال ممکن است دشوار باشد. در مرحله بعدی، از رابط کاربری توسعه برای تجربه ای بسیار غنی تر و شبیه به برنامه چت استفاده می کنیم.
عیب یابی
این روش API نیاز به فعال کردن صورتحساب دارد
اگر پیامی با مضمون {'message': 'This API method requires billing to be enabled'} ، موارد زیر را انجام دهید:
- بررسی کنید که آیا از شناسه پروژه درست در فایل
.envاستفاده می کنید - به صفحه حساب صورتحساب پیوندی بروید و ببینید آیا حساب صورتحساب قبلاً مرتبط است یا خیر
- اگر نه، حساب صورتحساب آزمایشی Google Cloud Platform را از این گزینه انتخاب کنید
Vertex AI API در پروژه استفاده نشده است
اگر پیام خطایی حاوی {'message': 'Vertex AI API has not been used in project...'} ، Vertex AI API را با تایپ این در ترمینال فعال کنید:
gcloud services enable aiplatform.googleapis.com
اگر عملیات موفقیت آمیز بود، می بینید که Operation/... finished successfully در ترمینال شما چاپ شده است.
سایر خطاها
اگر خطاهای دیگری دریافت کردید که در بالا ذکر نشده است، برگه Cloud Shell را در مرورگر بارگیری مجدد کنید (و در صورت درخواست مجدداً مجوز دهید).
8. عامل را در توسعه وب UI اجرا کنید
Agent Development Kit همچنین یک راه راحت برای راه اندازی نماینده خود به عنوان یک برنامه چت با استفاده از رابط کاربری توسعه ارائه می دهد. به سادگی از دستور adk web به جای adk run.
اگر ترمینال شما هنوز adk run را اجرا می کند، قبل از تایپ این دستور exit را تایپ کنید تا آن را ببندید:
adk web
شما باید خروجی مشابهی را در ترمینال ببینید:
... INFO: Started server process [4978] INFO: Waiting for application startup. +------------------------------------------------------+ | ADK Web Server started | | | | For local testing, access at http://localhost:8000. | +------------------------------------------------------+ INFO: Application startup complete. INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
برای دسترسی به رابط کاربری توسعه دو گزینه دارید:
- از طریق ترمینال باز کنید
- همانطور که در ترمینال نشان داده شده است ، Ctrl + Click یا Cmd + روی پیوند (مثلا
http://localhost:8000) کلیک کنید.
- از طریق پیش نمایش وب باز کنید
- روی دکمه پیش نمایش وب کلیک کنید،
- Change Port را انتخاب کنید.
- شماره پورت را وارد کنید (مثلا 8000 )
- روی Change and Preview کلیک کنید
سپس خواهید دید که رابط کاربری برنامه چت مانند در مرورگر شما ظاهر می شود. ادامه دهید و از طریق این رابط با دستیار شخصی خود چت کنید!
متوجه خواهید شد که قالب بندی Markdown اکنون به درستی نمایش داده می شود و این رابط کاربری همچنین به شما امکان می دهد هر رویداد پیام رسانی، وضعیت عامل، درخواست های کاربر و بسیاری موارد دیگر را اشکال زدایی و بررسی کنید. چت مبارک!
9. پاکسازی (اختیاری)
از آنجایی که این کد لبه هیچ محصول طولانی مدتی را شامل نمی شود، صرفاً توقف جلسات عامل فعال خود (مثلاً نمونه adk web در ترمینال شما) با فشار دادن Ctrl + C یا Cmd + C در ترمینال کافی است.
پوشه ها و فایل های Agent Project را حذف کنید
اگر فقط می خواهید کد را از محیط Cloud Shell خود حذف کنید، از دستورات زیر استفاده کنید:
cd ~
rm -rf ai-agents-adk
Vertex AI API را غیرفعال کنید
برای غیرفعال کردن Vertex AI API که قبلاً فعال شده بود، این دستور را اجرا کنید:
gcloud services disable aiplatform.googleapis.com
کل پروژه Google Cloud را خاموش کنید
اگر می خواهید پروژه Google Cloud خود را به طور کامل تعطیل کنید، برای دستورالعمل های دقیق به راهنمای رسمی مراجعه کنید.
10. نتیجه گیری
تبریک می گویم! شما با موفقیت یک نماینده دستیار شخصی ساده با استفاده از کیت توسعه عامل (ADK) ساخته اید. شما اکنون یک پایه محکم و درک از اجزای اصلی یک عامل ADK دارید.
به عنوان گام بعدی، می‌توانید با دادن ابزارهایی برای دسترسی به اطلاعات لحظه‌ای و تعامل با سرویس‌های خارجی، قابلیت‌های عامل خود را به طور قابل توجهی گسترش دهید. اگر می‌خواهید به سفر خود ادامه دهید، آزمایشگاه کد بعدی این مجموعه، ساخت عوامل هوش مصنوعی با ADK: توانمندسازی با ابزارها ، شما را در این فرآیند راهنمایی می‌کند.