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

ساخت عوامل هوش مصنوعی با ADK: The Foundation

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 ایجاد کنید

این Codelab فرض می کند که شما قبلاً یک پروژه Google Cloud با فعال بودن صورتحساب ایجاد کرده اید. اگر هنوز پروژه ای ندارید، مراحل زیر را برای ایجاد آن دنبال کنید:

یک پروژه Google Cloud را انتخاب یا ایجاد کنید

به Google Cloud Console بروید.
در بالا، روی منوی کشویی انتخابگر پروژه (در کنار نشان‌واره Google Cloud) کلیک کنید.
یک پروژه موجود را انتخاب کنید یا یک پروژه جدید ایجاد کنید.

فعال کردن صورتحساب

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

Cloud Shell را پیکربندی کنید

اکنون بیایید مطمئن شویم که به درستی در Cloud Shell تنظیم شده‌اید، یک رابط خط فرمان مفید مستقیماً در Google Cloud Console.

Cloud Shell را راه اندازی کنید

در گوشه سمت راست بالای Google Cloud Console، نمادی را خواهید دید که شبیه ترمینال است ( >_ ). روی آن کلیک کنید تا Cloud Shell فعال شود.

مجوز دسترسی

اگر از شما خواسته شد، روی مجوز کلیک کنید تا به Cloud Shell مجوزهای لازم برای تعامل با پروژه Google Cloud شما اعطا شود.

حساب خود را تأیید کنید:

پس از بارگیری Cloud Shell، اجازه دهید تأیید کنیم که از حساب Google Cloud صحیح استفاده می کنید. دستور زیر را اجرا کنید:

gcloud auth list

شما باید یک خروجی دستور مشابه را در ترمینال ببینید:

Credentialed Accounts

ACTIVE: *
ACCOUNT: current_account@example.com

To set the active account, run:
    $ gcloud config set account `ACCOUNT`

تغییر حساب (در صورت لزوم):

اگر حساب فعال همان حسابی نیست که می‌خواهید برای این Codelab استفاده کنید، با استفاده از این دستور به حساب صحیح بروید و <your_desired_account@example.com> را با ایمیل واقعی خود که برای این آزمایشگاه استفاده می‌کنید جایگزین کنید:

gcloud config set account <your_desired_account@example.com

پروژه خود را تایید کنید

در مرحله بعد، اجازه دهید بررسی کنیم که Cloud Shell برای استفاده صحیح از Google Cloud Project پیکربندی شده است. اجرا کنید:

gcloud config list project

شما یک لیست پیکربندی را مشاهده خواهید کرد. به دنبال بخش [core] باشید و مطمئن شوید که مقدار پروژه با شناسه پروژه Google Cloud که می‌خواهید برای این Codelab استفاده کنید مطابقت دارد:

[core]
project = <current-project-id>

پروژه خود را تنظیم کنید (در صورت لزوم)

اگر مقدار project ID نادرست است، با استفاده از دستور زیر آن را به پروژه مورد نظر خود تنظیم کنید:

gcloud config set project <your-desired-project-id>

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

برای استفاده از سرویس‌های Google Cloud، ابتدا باید API مربوط به پروژه خود را فعال کنید. اجرای دستورات زیر در ترمینال Cloud Shell تمام خدماتی را که برای این Codelab نیاز دارید فعال می کند:

gcloud services enable aiplatform.googleapis.com

اگر عملیات موفقیت آمیز بود، می بینید که Operation/... finished successfully در ترمینال شما چاپ شده است.

4. یک محیط مجازی پایتون ایجاد کنید

قبل از شروع هر پروژه پایتون، تمرین خوبی است که یک محیط مجازی ایجاد کنید. این امر وابستگی های پروژه را جدا می کند و از درگیری با پروژه های دیگر یا بسته های جهانی پایتون سیستم جلوگیری می کند. از آنجایی که کیت توسعه عامل (ADK) به پایتون 3.9 یا بالاتر نیاز دارد، از ابزاری مانند uv برای مدیریت محیط مجازی و اطمینان از استفاده از نسخه صحیح پایتون استفاده خواهیم کرد.

uv ابزاری مدرن، سریع و کارآمد برای مدیریت پروژه‌ها و محیط‌های پایتون است که عملکردهایی را که به‌طور سنتی در ابزارهایی مانند pip ، venv ، pip-tools و pipx یافت می‌شود، ترکیب می‌کند. برای سرعت در Rust نوشته شده است.

Cloud Shell در حال حاضر uv در دسترس دارد، بنابراین می‌توانیم فوراً شروع کنیم.

بررسی کنید که آیا uv به درستی نصب شده است

uv --version

یک پوشه پروژه جدید برای عامل هوش مصنوعی خود ایجاد کنید

uv init ai-agents-adk
cd ai-agents-adk

یک محیط مجازی با پایتون 3.12 ایجاد کنید

uv venv --python 3.12

کتابخانه Google ADK را در محیط مجازی خود نصب کنید

uv add google-adk

بررسی کنید که آیا بسته google-adk را با موفقیت نصب کرده اید

uv pip list | grep google-adk

اگر یک خط خروجی با google-adk و نسخه آن مشاهده کردید، خوب است که به مرحله بعدی بروید.

5. یک عامل ایجاد کنید

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

این سه فایل با هم کار می کنند تا عامل شما را قابل کشف، اجرا و تنظیم کنند:

agent.py : این قلب نماینده شماست. این شامل کد اولیه پایتون است که رفتار عامل شما را تعریف می کند، از جمله نام آن، مدل زبان بزرگ (LLM) که به عنوان "مغز" خود استفاده می کند، و دستورالعمل های اصلی که پاسخ های آن را هدایت می کند.
__init__.py : در پایتون، فایل __init__.py یک دایرکتوری را به عنوان بسته پایتون علامت گذاری می کند. برای ADK، بسیار مهم است زیرا به چارچوب کمک می‌کند تعریف عامل شما را از agent.py کشف و بارگیری کند. در پروژه‌های ساده ADK، اغلب شامل یک خط واحد برای وارد کردن ماژول agent شما می‌شود که عامل شما را برای اجراکننده ADK قابل دسترسی می‌کند.
.env : این فایل (مخفف "محیط") برای ذخیره اطلاعات حساس و متغیرهای پیکربندی مورد نیاز عامل شما، مانند کلیدهای API، شناسه پروژه و مکان های جغرافیایی استفاده می شود. نگه داشتن این جزئیات در یک فایل .env جداگانه بهترین روش برای امنیت و قابلیت حمل است، زیرا از کدگذاری هاردکد داده های حساس به طور مستقیم به کد شما جلوگیری می کند. همچنین به شما این امکان را می دهد که به راحتی تنظیمات را بدون تغییر منطق عامل اصلی خود تغییر دهید.

از دستورات زیر برای ایجاد این فایل ها در یک پوشه اختصاصی برای نماینده دستیار شخصی خود استفاده کنید:

uv run 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

در نهایت، از شما خواسته می شود که شناسه و منطقه پروژه Google Cloud خود را تأیید کنید. اگر مقادیر از پیش پر شده ( current-project-id و current-region ) همان چیزی است که قصد استفاده از آن را دارید، کافیست برای هر سوال Enter را فشار دهید.

Enter Google Cloud project ID [current-project-id]: 
Enter Google Cloud region [current-region]:

شما باید خروجی مشابهی را در ترمینال خود مشاهده کنید.

Agent created in /home/<your-username>/ai-agent-adk/personal_assistant:
- .env
- __init__.py
- agent.py

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

پس از بارگیری کامل پنجره ویرایشگر، به پوشه دستیار شخصی بروید. فایل های لازم را همانطور که در بالا ذکر شد مشاهده خواهید کرد ( agent.py ، __init__.py ، و .env ). بیایید محتوا را بررسی کنیم.

اگر فایل .env را در پوشه نمی بینید، به نوار منو در بالا بروید، روی View کلیک کنید و سپس Toggle Hidden Files را انتخاب کنید. این یک تنظیم رایج است زیرا فایل‌های .env اغلب به‌طور پیش‌فرض پنهان می‌شوند تا از قرار گرفتن در معرض تصادفی جلوگیری شود.

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

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="personal_assistant" : یک شناسه منحصر به فرد برای نماینده شما. به این ترتیب 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 در آن منطقه ارتباط برقرار کند.

6. عامل را در ترمینال اجرا کنید

با هر سه فایل در محل، شما آماده هستید تا عامل را مستقیماً از ترمینال اجرا کنید. برای این کار باید پنجره ترمینال را باز کنید. با کلیک بر روی Terminal در نوار منو، سپس انتخاب New Terminal کار را انجام می دهد!

هنگامی که ترمینال در دسترس است، می توانید با استفاده از دستور adk run عامل را راه اندازی کنید. از آنجایی که این یک پنجره ترمینال جدید است و ما از uv استفاده می کنیم، ابتدا باید به پوشه ai-agent-adk بروید و سپس دستور adk run را با uv run پیشوند کنید.

این دستورات را در ترمینال تایپ کنید:

cd ai-agents-adk
uv run adk run personal_assistant

اگر همه چیز به درستی تنظیم شده باشد، خروجی مشابهی را در ترمینال خود خواهید دید.

...
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 فرمت می شود که خواندن آن در ترمینال ممکن است دشوار باشد. در مرحله بعدی، از رابط کاربری توسعه برای تجربه ای بسیار غنی تر و شبیه به برنامه چت استفاده می کنیم.

7. عامل را روی رابط کاربری توسعه اجرا کنید

Agent Development Kit همچنین یک راه راحت برای راه اندازی نماینده خود به عنوان یک برنامه چت با استفاده از رابط کاربری توسعه ارائه می دهد. به سادگی از دستور adk web به جای adk run.

اگر هنوز در جلسه قبلی هستید، فقط exit در ترمینال تایپ کنید تا آن را ببندید. پس از بسته شدن جلسه قبلی، دستور زیر را در ترمینال تایپ کنید:

uv run 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 + کلیک یا Cmd + روی URL ها (به عنوان مثال، http://localhost:8000 ) از ترمینال کلیک کنید.

از طریق پیش نمایش وب باز کنید

روی دکمه پیش نمایش وب کلیک کنید،
Change Port را انتخاب کنید.
شماره پورت را وارد کنید (مثلا 8000 )
روی Change and Preview کلیک کنید

سپس خواهید دید که رابط کاربری برنامه چت مانند در مرورگر شما ظاهر می شود. ادامه دهید و از طریق این رابط با دستیار شخصی خود چت کنید! متوجه خواهید شد که قالب بندی Markdown اکنون به درستی نمایش داده می شود و این رابط کاربری همچنین به شما امکان می دهد هر رویداد پیام رسانی، وضعیت عامل، درخواست های کاربر و بسیاری موارد دیگر را اشکال زدایی و بررسی کنید. چت مبارک!

8. پاکسازی کنید

از آنجایی که این کد لبه هیچ محصول طولانی مدتی را شامل نمی شود، صرفاً توقف جلسات عامل فعال شما (مثلاً نمونه adk web در ترمینال شما) با فشار دادن Ctrl + 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 خود را به طور کامل تعطیل کنید، برای دستورالعمل های دقیق به راهنمای رسمی مراجعه کنید.

9. نتیجه گیری

تبریک می گویم! شما با موفقیت یک نماینده دستیار شخصی ساده با استفاده از کیت توسعه عامل (ADK) ساخته اید.

همانطور که ممکن است متوجه شده باشید، این نماینده دستیار شخصی هنوز توانایی زیادی ندارد (به عنوان مثال، نمی تواند برای آخرین اطلاعات به اینترنت دسترسی داشته باشد). در کد بعدی این مجموعه «ساخت عوامل هوش مصنوعی با ADK»، یاد خواهید گرفت که چگونه نماینده دستیار شخصی خود را با عملکردها و ابزارها توانمند کنید. آنجا می بینمت!