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

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

۱. قبل از شروع

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

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

شما می‌توانید این آزمایشگاه کد را در محیط محلی خود یا در Google Cloud تکمیل کنید. برای داشتن بهترین تجربه، توصیه می‌کنیم از Cloud Shell از محیط Google Cloud استفاده کنید. Cloud Shell همچنین 5 گیگابایت فضای ذخیره‌سازی پایدار در دایرکتوری $HOME ارائه می‌دهد. این برای ذخیره اسکریپت‌ها، فایل‌های پیکربندی یا مخازن کلون شده مفید است.

همچنین می‌توانید از طریق این آدرس کوتاه‌شده‌ی goo.gle/adk-foundation به این آزمایشگاه کد دسترسی پیدا کنید.

پیش‌نیازها

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

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

آنچه نیاز دارید

یک کامپیوتر سالم و وای فای قابل اعتماد
یک مرورگر، مانند کروم ، برای دسترسی به کنسول ابری گوگل
ذهن کنجکاو و اشتیاق به یادگیری

۲. مقدمه

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

در هسته خود، یک عامل هوش مصنوعی از یک مدل زبان بزرگ (LLM) به عنوان "مغز" خود برای درک و استدلال استفاده می‌کند. این امر به آن اجازه می‌دهد تا اطلاعات را از منابع مختلف مانند متن، تصاویر و صداها پردازش کند. سپس عامل از این درک برای ایجاد یک برنامه و اجرای مجموعه‌ای از وظایف برای رسیدن به یک هدف از پیش تعریف شده استفاده می‌کند.

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

۳. پیکربندی سرویس‌های ابری گوگل

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

با ایجاد یک پروژه جدید Google Cloud شروع کنید تا فعالیت‌های این codelab فقط در این پروژه جدید ایزوله شوند.

به console.cloud.google.com/projectcreate بروید
اطلاعات مورد نیاز را وارد کنید:

نام پروژه - می‌توانید هر نامی که می‌خواهید وارد کنید (مثلاً genai-workshop)
مکان - آن را بدون سازمان رها کنید
حساب پرداخت - اگر این گزینه را می‌بینید، حساب پرداخت آزمایشی پلتفرم ابری گوگل را انتخاب کنید. اگر این گزینه را نمی‌بینید نگران نباشید. فقط به مرحله بعدی بروید.

شناسه پروژه تولید شده را کپی کنید، بعداً به آن نیاز خواهید داشت.

اگر همه چیز درست است، روی دکمه ایجاد کلیک کنید

پیکربندی Cloud Shell

پس از ایجاد موفقیت‌آمیز پروژه، مراحل زیر را برای راه‌اندازی Cloud Shell انجام دهید.

۱. راه‌اندازی Cloud Shell

به shell.cloud.google.com بروید و اگر پنجره‌ای را مشاهده کردید که از شما درخواست مجوز می‌کند، روی Authorize کلیک کنید.

۲. تنظیم شناسه پروژه

دستور زیر را در ترمینال Cloud Shell اجرا کنید تا شناسه پروژه صحیح تنظیم شود. <your-project-id> را با شناسه پروژه واقعی خود که از مرحله ایجاد پروژه در بالا کپی کرده‌اید، جایگزین کنید.

gcloud config set project <your-project-id>

اکنون باید ببینید که پروژه صحیح در ترمینال Cloud Shell انتخاب شده است. شناسه پروژه انتخاب شده با رنگ زرد برجسته شده است.

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

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

gcloud services enable aiplatform.googleapis.com

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

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

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

۱. دایرکتوری پروژه را ایجاد کنید و به داخل آن بروید:

mkdir ai-agents-adk
cd ai-agents-adk

۲. ایجاد و فعال‌سازی یک محیط مجازی:

uv venv --python 3.12
source .venv/bin/activate

خواهید دید که ( ai-agents-adk ) به عنوان پیشوند اعلان ترمینال شما ظاهر می‌شود که نشان می‌دهد محیط مجازی فعال است.

۳. صفحه adk را نصب کنید

uv pip install google-adk

۵. یک نماینده ایجاد کنید

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

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

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

adk create personal_assistant

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

برای اولین قدم، گزینه ۱ را انتخاب کنید تا از مدل 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 (گزینه ۲) ، پلتفرم قدرتمند و مدیریت‌شده هوش مصنوعی گوگل کلود، را به عنوان ارائه‌دهنده خدمات بک‌اند انتخاب کنید.

1. Google AI
2. Vertex AI
Choose a backend (1, 2): 2

پس از آن، باید تأیید کنید که شناسه پروژه نشان داده شده در براکت‌ها [...] به درستی تنظیم شده است. اگر چنین است، Enter را فشار دهید . در غیر این صورت، شناسه پروژه صحیح را در اعلان زیر وارد کنید:

Enter Google Cloud project ID [your-project-id]:

در نهایت، در سوال بعدی Enter را فشار دهید تا us-central1 به عنوان ناحیه برای این codelab استفاده شود.

Enter Google Cloud region [us-central1]:

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

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

۶. کدهای عامل را بررسی کنید

برای مشاهده فایل‌های ایجاد شده، پوشه ai-agents-adk را در ویرایشگر Cloud Shell باز کنید.

در منوی بالا روی File > Open Folder... کلیک کنید.
پوشه‌ی ai-agents-adk را پیدا و انتخاب کنید.
روی تأیید کلیک کنید.

اگر نوار منوی بالا برای شما نمایش داده نمی‌شود، می‌توانید روی آیکون پوشه‌ها کلیک کرده و گزینه Open Folder را انتخاب کنید.

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

فایل .env اغلب به طور پیش‌فرض پنهان است. برای اینکه در ویرایشگر Cloud Shell قابل مشاهده باشد:

به نوار منو در بالا بروید،
روی مشاهده کلیک کنید، و
گزینه‌ی «فایل‌های مخفی را تغییر وضعیت دهید» را انتخاب کنید.

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

عامل.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 می‌گوید که چگونه باید عمل کند و هدف اصلی آن چیست. در این مورد، نماینده را به عنوان یک "دستیار مفید" معرفی می‌کند. این دستورالعمل کلید شکل‌دهی به سبک مکالمه و قابلیت‌های نماینده است.

فایل .py برای شروع

این فایل برای پایتون ضروری است تا personal-assistant به عنوان یک بسته تشخیص دهد و به ADK اجازه دهد فایل agent.py شما را به درستی وارد کند.

from . import agent

from . import agent : این خط یک ایمپورت نسبی انجام می‌دهد و به پایتون می‌گوید که در بسته فعلی ( personal-assistant ) به دنبال ماژولی به نام agent (که معادل agent.py است) بگردد. این خط ساده تضمین می‌کند که وقتی ADK سعی می‌کند agent 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 Cloud مهم است.
GOOGLE_CLOUD_PROJECT : این متغیر شناسه منحصر به فرد پروژه ابری گوگل شما را در خود نگه می‌دارد. ADK برای مرتبط کردن صحیح نماینده شما با منابع ابری و فعال کردن پرداخت، به این شناسه نیاز دارد.
GOOGLE_CLOUD_LOCATION : این ناحیه‌ی Google Cloud را که منابع Vertex AI شما در آن قرار دارند (مثلاً us-central1 ) مشخص می‌کند. استفاده از موقعیت مکانی صحیح تضمین می‌کند که عامل شما می‌تواند به طور مؤثر با سرویس‌های Vertex AI در آن ناحیه ارتباط برقرار کند.

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

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

از API هوش مصنوعی Vertex در پروژه استفاده نشده است.

اگر پیام خطایی حاوی {'message': 'Vertex AI API has not been used in project...'} دریافت کردید، با تایپ کردن این دستور در ترمینال، Vertex AI API را فعال کنید:

gcloud services enable aiplatform.googleapis.com

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

خطاهای دیگر

اگر خطاهای دیگری دریافت کردید که در بالا ذکر نشده است، سعی کنید برگه Cloud Shell را در مرورگر مجدداً بارگذاری کنید (و در صورت درخواست، دوباره مجوز دهید).

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

کیت توسعه‌ی عامل (Agent Development Kit) همچنین با استفاده از رابط کاربری توسعه‌ی خود، روشی آسان برای راه‌اندازی عامل شما به عنوان یک برنامه‌ی چت ارائه می‌دهد. کافیست به جای دستور adk run، از دستور adk web استفاده کنید 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 + Click روی لینک (مثلاً http://localhost:8000 ) همانطور که در ترمینال نشان داده شده است.

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

روی دکمه پیش‌نمایش وب کلیک کنید،
تغییر پورت را انتخاب کنید.
شماره پورت را وارد کنید (مثلاً ۸۰۰۰ )
روی تغییر و پیش‌نمایش کلیک کنید

سپس رابط کاربری شبیه به یک برنامه چت را در مرورگر خود مشاهده خواهید کرد. از طریق این رابط کاربری با دستیار شخصی خود چت کنید!

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

۹. تمیز کردن (اختیاری)

از آنجایی که این آزمایشگاه کد شامل هیچ محصول طولانی‌مدتی نمی‌شود، متوقف کردن ساده‌ی جلسات عامل فعال شما (مثلاً نمونه‌ی adk web در ترمینال شما) با فشار دادن Ctrl + C یا Cmd + C در ترمینال کافی است.

حذف پوشه‌ها و فایل‌های پروژه Agent

اگر فقط می‌خواهید کد را از محیط Cloud Shell خود حذف کنید، از دستورات زیر استفاده کنید:

cd ~
rm -rf ai-agents-adk

غیرفعال کردن API هوش مصنوعی ورتکس

برای غیرفعال کردن Vertex AI API که قبلاً فعال شده بود، این دستور را اجرا کنید:

gcloud services disable aiplatform.googleapis.com

کل پروژه ابری گوگل را تعطیل کنید

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

۱۰. نتیجه‌گیری

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

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