ADK: از مبانی تا عامل‌های چندابزاری

۱. مقدمه

این codelab با شروع از اصول اولیه و پیشرفت به سمت توسعه عامل‌های چند ابزاری، مقدمه‌ای جامع برای ساخت عامل‌ها با ADK ارائه می‌دهد.

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

اگر یک LLM یک مشاور بسیار توانمند است که می‌تواند به شما مشاوره بدهد، یک AI Agent یک مهندس فعال است که می‌تواند از ابزارها برای اجرای آن مشاوره استفاده کند.

LLM در مقابل نمایندگان

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

دست‌ها (ابزارها): اینها APIها، SDKها و توابع سفارشی هستند که به عامل اجازه می‌دهند با دنیای واقعی تعامل داشته باشد. این ابزار، طرح را اجرا می‌کند.

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

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

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

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

در این آزمایشگاه کد، شما یک عامل «نکات سالم» خواهید ساخت، یک مشاور تغذیه هوشمند که از استدلال متنی ساده به یک ابزار قدرتمند چندمنظوره تبدیل می‌شود. شما با ایجاد یک عامل مکالمه‌ای پایه که مفاهیم تغذیه‌ای را درک می‌کند، شروع خواهید کرد، سپس به تدریج آن را به یک ابزار SDK ذخیره‌سازی برای بایگانی تصاویر مواد تشکیل‌دهنده و یک ابزار بینایی برای «خواندن» و تجزیه و تحلیل آن تصاویر مجهز خواهید کرد. در پایان این آزمایشگاه، شما یک هماهنگ‌کننده کاملاً کاربردی خواهید داشت که می‌تواند یک عکس آپلود شده از یک برچسب غذایی بگیرد، آن را در یک سطل ابری برای ثبت سوابق ذخیره کند و بلافاصله «نکات سالم» را برای هر ماده ارائه دهد.

۲. پیش‌نیازها

• یک پروژه گوگل کلود با قابلیت پرداخت صورتحساب
• یک مرورگر وب

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

• در کنسول گوگل کلود ، در صفحه انتخاب پروژه، یک پروژه گوگل کلود را انتخاب یا ایجاد کنید.
• مطمئن شوید که صورتحساب در پروژه ابری شما فعال است. یاد بگیرید که چگونه بررسی کنید که آیا صورتحساب در یک پروژه فعال است یا خیر .

فعال کردن پوسته ابری

• شما از Cloud Shell استفاده خواهید کرد، یک محیط خط فرمان که در Google Cloud Console اجرا می‌شود و زبان‌های مورد نیاز از قبل نصب شده‌اند. از Cloud Console، روی Activate Cloud Shell در گوشه بالا سمت راست کلیک کنید:

• پس از اتصال به Cloud Shell، باید ببینید که از قبل احراز هویت شده‌اید و پروژه روی شناسه پروژه شما تنظیم شده است. برای تأیید احراز هویت، دستور زیر را در Cloud Shell اجرا کنید:

gcloud auth list

• دستور زیر را در Cloud Shell اجرا کنید تا تأیید کنید که دستور gcloud از پروژه شما اطلاع دارد:

gcloud config list project

• اگر پروژه شما تنظیم نشده است، از دستور زیر برای تنظیم آن استفاده کنید:

gcloud config set project <YOUR_PROJECT_ID>

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

ویرایشگر را باز کنید

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

۳. راه‌اندازی ADK

بیایید به ترمینال Cloud Shell که در بخش قبلی فعال کردیم، برویم:

• ایجاد و فعال‌سازی محیط مجازی (توصیه شده)

از ترمینال Cloud Shell خود، یک محیط مجازی ایجاد کنید:

python -m venv .venv

فعال کردن محیط مجازی:

source .venv/bin/activate

• نصب ADK

pip install google-adk

۴. کلید API گوگل

ایجاد کلید API گوگل با استفاده از AI Studio:

• به آدرس https://aistudio.google.com/ مراجعه کنید و از منوی پایین سمت چپ، روی Get API Key کلیک کنید.

• پنجره‌ای با عنوان «کلیدهای API» مشاهده خواهید کرد، در این پنجره روی «ایجاد کلید API» کلیک کنید:

• یک پنجره برای ایجاد یک کلید جدید مشاهده خواهید کرد. نام کلید را healthy-hints-key قرار دهید.

به منوی کشویی «انتخاب یک پروژه وارد شده» بروید

• روی Import Project کلیک کنید، یک پنجره کناری وجود دارد که تمام پروژه‌های Google Cloud شما را فهرست می‌کند، پروژه‌ای را که می‌خواهید با آن کار کنید انتخاب کنید.

روی وارد کردن کلیک کنید

• اکنون منوی کشویی با پروژه‌ای که تازه وارد کرده‌اید به‌روزرسانی می‌شود. پروژه را از منوی کشویی انتخاب کنید. روی «ایجاد کلید» کلیک کنید. اکنون لیست کلیدهای API ایجاد شده را مشاهده خواهید کرد. روی نماد کپی کلید API که تازه ایجاد کرده‌اید کلیک کنید.

۵. نماینده نمونه

• از طریق ترمینال Cloud Shell، یک دایرکتوری ریشه برای عامل خود در محل پروژه مورد نظر خود ایجاد کنید:

adk create healthy_hints

شما می‌توانید هر مدلی را انتخاب کنید، اما برای این آزمایشگاه کد، ما با gemini-2.5-flash پیش می‌رویم.

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

• بیایید پوشه‌ای را که تازه ایجاد کرده‌ایم باز کنیم. در سمت چپ منو، روی آیکون کلیک کنید ، روی File -> Open Folder کلیک کنید. پوشه healthy_hints که تازه ایجاد شده است را انتخاب کنید، این پوشه معمولاً در پوشه /home/<username> قرار دارد.
• ساختار پوشه healthy_hints معمولاً به این شکل خواهد بود:

• یک فایل .env خواهید دید که حاوی کلید API گوگل شماست. می‌توانید از این فایل برای تنظیم هر متغیر محیطی استفاده کنید.
• فایل دیگری به نام agent.py نیز ایجاد می‌شود که فایل عامل اصلی ما است. اینجا جایی است که یک عامل ریشه نمونه ایجاد می‌شود. بیایید نگاهی دقیق‌تر به محتوای این فایل بیندازیم، ابتدا llm_agent از ADK وارد می‌کنیم. سپس از ADK DSL برای ایجاد عامل ریشه استفاده می‌کنیم. نام مدل را Gemini-2.5-flash تعیین می‌کنیم، نام عامل را مشخص می‌کنیم و توضیح خوبی از آن ارائه می‌دهیم. دستورالعمل در اینجا مهمترین چیز است، اینجا جایی است که به عامل می‌گوییم چه کاری باید انجام دهد.
• این نمونه عامل کاملاً عمومی است، فقط به هر سوالی که کاربر دارد پاسخ می‌دهد.
• حالا بیایید این عامل را به صورت محلی اجرا کنیم. دو راه برای تعامل با این عامل وجود دارد: رابط خط فرمان (CLI) و وب.
• CLI : دستور زیر را خارج از دایرکتوری healthy_hints اجرا کنید

adk run healthy_hints

یا اگر داخل دایرکتوری healthy_hints هستید، دستور زیر را اجرا کنید:

adk run .

خروجی مشابهی خواهید دید:

بفرمایید و «سلام» یا هر سوالی که دارید بنویسید. جواب ممکن است برای هر کسی متفاوت باشد، این ماهیت GenAI است.

• وب : دستور زیر را از دایرکتوری والد healthy_hints اجرا کنید:

adk web

6. عامل چند ابزاره

یک ابزار، قطعه کد ماژولاری است - معمولاً یک تابع یا یک API - که به یک عامل اجازه می‌دهد تا با دنیایی فراتر از دانش درونی خود تعامل داشته باشد.

انواع ابزارها در ADK

• ابزارهای تابع: منطق سفارشی که خودتان می‌نویسید. به عنوان مثال، تابعی که به پایگاه داده خاص شما متصل می‌شود یا یک "تجزیه‌کننده لاگ" سفارشی برای قالب منحصر به فرد شرکت شما.
• ابزارهای داخلی: قابلیت‌های آماده برای استفاده که توسط گوگل یا ADK ارائه می‌شوند، مانند جستجوی گوگل ، مفسر کد یا موتور RAG گوگل .
• عامل‌ها به عنوان ابزار: در سیستم‌های پیشرفته «چند ابزاری» یا «چند عاملی»، یک عامل تخصصی می‌تواند به عنوان ابزاری برای عامل دیگر عمل کند. برای مثال، یک «عامل جستجو» می‌تواند ابزاری باشد که توسط یک «عامل مدیر تحقیق» مورد استفاده قرار می‌گیرد.

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

بیایید یک متد جدید get_weather در agent.py اضافه کنیم.

def get_weather(city: str) -> dict:
  """Retrieves the current weather report for a specified city.

  Args:
    city (str): The name of the city for which to retrieve the weather report.

  Returns:
    dict: status and result or error msg.
  """
  if city.lower() == "new york":
    return {
      "status": "success",
      "report": (
          "The weather in New York is sunny with a temperature of 25 degrees"
          " Celsius (77 degrees Fahrenheit)."
      ),
    }
  else:
    return {
      "status": "error",
      "error_message": f"Weather information for '{city}' is not available.",
    }

بیایید فایل agent.py را تغییر دهیم و نام، توضیحات و دستورالعمل‌های مربوط به عامل را تغییر دهیم:

root_agent = Agent(
    model='gemini-2.5-flash',
    name='healthy_hints_agent',
    description='Agent to answer questions about the weather in a city.',
    instruction='You are a helpful agent who can answer user questions about the weather in a city.',
    tools=[get_weather],
)

تا اینجا فقط یک ابزار ایجاد کرده‌ایم. حالا بیایید چندین ابزار ایجاد کنیم:

بیایید یک متد دیگر به نام get_current_time ایجاد کنیم:

def get_current_time(city: str) -> dict:
  """Returns the current time in a specified city.

  Args:
    city (str): The name of the city for which to retrieve the current time.

  Returns:
    dict: status and result or error msg.
  """

  if city.lower() == "new york":
    tz_identifier = "America/New_York"
  else:
    return {
      "status": "error",
      "error_message": (
        f"Sorry, I don't have timezone information for {city}."
      ),
    }

  tz = ZoneInfo(tz_identifier)
  now = datetime.datetime.now(tz)
  report = (
    f'The current time in {city} is {now.strftime("%Y-%m-%d %H:%M:%S %Z%z")}'
  )
  return {"status": "success", "report": report}

و بیایید عامل خود را طوری تغییر دهیم که این ابزار را نیز فراخوانی کند:

root_agent = Agent(
  model='gemini-2.5-flash',
  name='healthy_hints_agent',
  description='Agent to answer questions about the time and weather in a city.',
  instruction='You are a helpful agent who can answer user questions about the time and weather in a city.',
  tools=[get_weather, get_current_time],
)

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

۷. یکپارچه‌سازی SDK

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

• بیایید ابتدا یک سطل برای آپلود تصویر در فضای ابری گوگل ایجاد کنیم. یک تب جدید باز کنید و به آدرس https://console.cloud.google.com/ بروید و در نوار جستجو، عبارت cloud storage را تایپ کنید. اکنون، در قسمت Products & pages، گزینه Cloud Storage را انتخاب کنید:

این شما را به صفحه نمای کلی فضای ذخیره‌سازی ابری گوگل (Google Cloud Storage) می‌برد. روی دکمه Create bucket ) کلیک کنید. در صفحه «ایجاد سطل»، نام سطل را وارد کنید. این نام می‌تواند هر چیزی باشد، اما برای این codelab، ما آن را healthy-hints-bucket-kolkata قرار می‌دهیم. سایر موارد را به همان صورت باقی بگذارید و روی دکمه Create ) کلیک کنید.

• بیایید یک فایل جدید به نام requirements.txt ایجاد کنیم و google-cloud-storage به آن اضافه کنیم. ما قصد داریم از Python Storage SDK برای آپلود تصویر در Storage استفاده کنیم.

ابتدا وابستگی‌ها را نصب می‌کنیم:

pip install -r requirements.txt

ممکن است لازم باشد ابتدا API ذخیره‌سازی را فعال کنید. برای انجام این کار، دستور زیر را در ترمینال خود اجرا کنید:

gcloud services enable storage.googleapis.com 

حالا بیایید یک ابزار جدید برای آپلود تصویر اضافه کنیم.

def upload_image() -> str:
  storage_client = storage.Client()
  bucket_name = "healthy-hints-bucket-kolkata"
  bucket = storage_client.bucket(bucket_name)
  blob = bucket.blob("ingredirents")
  blob.upload_from_filename(<image-file-path>)

• حالا، بیایید عامل خود را به‌روزرسانی کنیم تا از ابزار جدید استفاده کند:

root_agent = Agent(
  model='gemini-2.5-flash',
  name='healthy_hints_agent',
  description='Agent to upload image to Google Cloud Storage',
  instruction='You are a helpful agent who will upload the image to Google Cloud Storage using `upload_image` tool.',
  tools=[upload_image],
)

• اکنون ابزار دیگری برای خواندن اجزای تصویر اضافه خواهیم کرد. بیایید google-cloud-vision در requirements.txt اضافه کنیم و وابستگی جدید را نصب کنیم.

pip install -r requirements.txt

باز هم، ممکن است لازم باشد ابتدا Vision API را فعال کنید. برای انجام این کار، دستور زیر را در ترمینال خود اجرا کنید:

gcloud services enable vision.googleapis.com

حالا بیایید یک ابزار جدید read_ingredients اضافه کنیم:

def read_ingredients() -> str:
  vision_client = vision.ImageAnnotatorClient()

  with io.open("/home/bajajnehaa/healthy_hints/images/Ingredients-list.jpg", 'rb') as image_file:
    content = image_file.read()

  image = vision.Image(content=content)
  response = vision_client.text_detection(image=image)
  texts = response.text_annotations
  return texts[0].description

و حالا بیایید ایجنت خود را برای استفاده از این ابزار به‌روزرسانی کنیم

root_agent = Agent(
  model='gemini-2.5-flash',
  name='healthy_hints_agent',
  description='Agent to upload image to Google Cloud Storage, read the list of ingredients from the image and explain if the ingredient is healthy or not',
  instruction='You are a helpful agent who will upload the image to Google Cloud Storage using `upload_image` tool, read the ingredients of the image using `read_ingredients` tool and explain if the ingredient is healthy or not in one line.',
  tools=[upload_image, read_ingredients],
)

۸. نتیجه‌گیری

تبریک بابت تکمیل آزمایشگاه کد Healthy Hints! شما با موفقیت یک هوش مصنوعی استاندارد را از یک مولد متن به یک عامل چند ابزاره فعال تبدیل کرده‌اید. با استفاده از ADK برای ادغام Vision API و Cloud Storage SDK، به عامل خود «چشم» برای خواندن برچسب‌ها و «حافظه» برای بایگانی آنها داده‌اید. شما دیده‌اید که چگونه عامل به طور مستقل تصمیم می‌گیرد چه زمانی یک فایل را ذخیره کند و چگونه داده‌های خام را برای ارائه توصیه‌های بهداشتی در دنیای واقعی تفسیر کند.

در ادامه، این اصول به عنوان طرح اولیه برای هر سیستم خودکار عمل می‌کنند. چه در حال مدیریت زیرساخت ابری باشید و چه در حال ساخت دستیارهای شخصی، هسته اصلی یکسان باقی می‌ماند: ابزارهای تخصصی را تعریف کنید و اجازه دهید نماینده منطق را تنظیم کند. به عنوان گام بعدی، سعی کنید ابزارهای بیشتری مانند "پایگاه داده تغذیه‌ای" یا "ابزار ایمیل" را برای گسترش تأثیر نماینده خود اضافه کنید.