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

از نمونه های اولیه تا عوامل با ADK

۱. مرور کلی

ساختن با هوش مصنوعی امروزه از کجا شروع می‌شود؟ خب، برای اکثر ما، اغلب با یک سوال ساده شروع می‌شود: "آیا این مدل واقعاً می‌تواند به حل این مشکلی که به آن فکر کرده‌ام کمک کند؟". این دقیقاً همان جایی است که Google AI Studio وارد عمل می‌شود. جایی است که می‌توانید به سرعت هر چیزی را نمونه‌سازی کنید. من می‌خواستم آشپزخانه‌ام را بازسازی کنم و شرط می‌بندم Gemini می‌تواند کمک کند - اما من یک مهندس هستم، نه یک پیمانکار عمومی. من حتی مطمئن نیستم که چه چیزی درخواست کنم - چیزهای زیادی برای بررسی وجود دارد: مقررات، وسایل و غیره. بنابراین بیایید این را تجزیه و تحلیل کنیم و از Gemini بخواهیم یک دستورالعمل فوق‌العاده دقیق برای ما ایجاد کند، سپس یک طرح نوسازی کامل ایجاد کنیم و همچنین بازسازی را تجسم کنیم! اما صبر کنید. چگونه می‌توانم از اینجا به مقیاس‌پذیری کسب‌وکارها کمک کنم؟ وارد AGENTS شوید!!!

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

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

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

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

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

آماده‌اید تا از نمونه اولیه PROMPT به ساخت یک عامل (Agent) برویم؟؟؟ ما یک عامل (Agent) ایجاد خواهیم کرد تا به تولید سند پیشنهادی برای پروژه نوسازی آشپزخانه کمک کند. به عنوان بخشی از این آزمایش، شما:

ساخت یک عامل ساده برای تولید سند پیشنهاد نوسازی با ADK
سند پیشنهاد نوسازی تولید شده را در یک فضای ذخیره‌سازی ابری ذخیره کنید
عامل را در Cloud Shell و در خروجی وب عامل آزمایش کنید

الزامات

یک مرورگر، مانند کروم یا فایرفاکس
یک پروژه گوگل کلود با قابلیت پرداخت.

۲. قبل از شروع

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

در کنسول گوگل کلود ، در صفحه انتخاب پروژه، یک پروژه گوگل کلود را انتخاب یا ایجاد کنید.
مطمئن شوید که صورتحساب برای پروژه ابری شما فعال است. یاد بگیرید که چگونه بررسی کنید که آیا صورتحساب در یک پروژه فعال است یا خیر .
همچنین اگر در حال خواندن این مطلب هستید و مایلید برای شروع کار با Google Cloud و استفاده از ADK اعتبار دریافت کنید، از این لینک برای بازخرید اعتبار استفاده کنید.
می‌توانید دستورالعمل‌های اینجا را برای استفاده از آن دنبال کنید. لطفاً توجه داشته باشید که این لینک فقط تا ۱۵ ژوئیه ۲۰۲۵ برای استفاده معتبر است.
با کلیک روی این لینک، Cloud Shell را فعال کنید. می‌توانید با کلیک روی دکمه مربوطه از Cloud Shell، بین Cloud Shell Terminal (برای اجرای دستورات ابری) و Editor (برای ساخت پروژه‌ها) جابجا شوید.
پس از اتصال به Cloud Shell، با استفاده از دستور زیر بررسی می‌کنید که آیا از قبل احراز هویت شده‌اید و پروژه روی شناسه پروژه شما تنظیم شده است یا خیر:

gcloud auth list

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

gcloud config list project

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

gcloud config set project <YOUR_PROJECT_ID>

حتماً پایتون ۳.۹+ داشته باشید

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

۳. نمونه اولیه

به 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 را انتخاب کرده‌ایم. این یک مدل Thinking است، به این معنی که ما توکن‌های خروجی بیشتری، در این مورد تا 65 هزار توکن، برای تحلیل‌های طولانی و اسناد دقیق دریافت می‌کنیم. جعبه تفکر Gemini زمانی فعال می‌شود که Gemini 2.5 Pro را فعال کنید که دارای قابلیت‌های استدلال بومی است و می‌تواند درخواست‌های متنی طولانی را بپذیرد.

گزیده‌ای از پاسخ را در زیر ببینید:

AI Studio داده‌های من را تجزیه و تحلیل کرد و همه این موارد مانند کابینت، کانترها، دیوارپوش، کفپوش، سینک، انسجام، پالت رنگ و انتخاب مواد را تولید کرد. Gemini حتی منابع را ذکر می‌کند!

حالا سعی کنید با یک مثال متفاوت، شاهد تحقق این ایده باشید.

این دستور را کپی کرده و در ویرایشگر دستور پیست کنید:

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» تغییر دهید تا بتوانید به تولید تصاویر دسترسی داشته باشید.

من این خروجی را گرفتم:

این قدرت جوزا است!

از درک ویدیوها گرفته تا تولید تصویر بومی و استخراج اطلاعات واقعی با جستجوی گوگل - چیزهایی وجود دارد که فقط با Gemini می‌توان ساخت.

از استودیوی هوش مصنوعی، می‌توانید این نمونه اولیه را بردارید، کلید API را دریافت کنید و با استفاده از قدرت Vertex AI ADK، آن را به یک برنامه عامل کامل تبدیل کنید.

۴. تنظیمات ADK

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

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

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

python -m venv .venv

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

source .venv/bin/activate

نصب ADK

pip install google-adk

۵. ساختار پروژه

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

mkdir agentic-apps

در داخل دایرکتوری اصلی، یک پوشه مختص پروژه فعلی خود ایجاد کنید:

mkdir renovation-agent

به ویرایشگر Cloud Shell بروید و با ایجاد فایل‌ها (ابتدا خالی) ساختار پروژه زیر را ایجاد کنید:

renovation-agent/
        __init__.py
        agent.py
        requirements.txt
        .env

۶. کد منبع

به " init .py " بروید و با محتوای زیر به‌روزرسانی کنید:

from . import agent

به فایل agent.py بروید و فایل را با محتوای زیر از مسیر زیر به‌روزرسانی کنید:

در agent.py، وابستگی‌های لازم را وارد می‌کنیم، پارامترهای پیکربندی را از فایل .env بازیابی می‌کنیم و root_agent را تعریف می‌کنیم که یک سند پیشنهادی تولید می‌کند و آن را در یک مخزن ذخیره‌سازی ابری ذخیره می‌کند. برای انجام مرحله ذخیره‌سازی ابری، از ابزاری به نام store_pdf استفاده می‌کنیم.

نکته: در حال حاضر فایل PDF بدون فرمت است! بر اساس نظر توسعه‌دهندگان انجمن ، قطعه کد زیر در اینجا گنجانده شده است [تست نشده است]، می‌توانید آن را در داخل متد store_pdf قرار دهید:

doc = SimpleDocTemplate(
        pdf_buffer,
        pagesize=letter,
        rightMargin=0.75 * inch,
        leftMargin=0.75 * inch,
        topMargin=0.75 * inch,
        bottomMargin=0.75 * inch
    )

    styles = getSampleStyleSheet()
    story = []

    # --- CUSTOM STYLES FOR HEADERS ---
    # Define a new style for section headers
    styles.add(ParagraphStyle(name='SectionHeader',
                              parent=styles['Normal'],
                              fontName='Helvetica-Bold', # Make it bolder
                              fontSize=14,               # Make it slightly larger
                              leading=16,                # Line spacing
                              spaceAfter=0.15 * inch,    # Space after the header
                              spaceBefore=0.25 * inch,   # Space before the header
                              textColor=black            # Ensure color is bright/black (default is usually black, but explicit is good)
                             ))

    # Define a style for the main document title
    styles.add(ParagraphStyle(name='DocumentTitle',
                              parent=styles['Normal'],
                              fontName='Helvetica-Bold',
                              fontSize=20,
                              leading=24,
                              spaceAfter=0.25 * inch,
                              alignment=TA_CENTER, # Center align the title
                              textColor=black
                             ))
    # ---------------------------------

    paragraphs_raw = pdf_text.split('\n\n')

    # Heuristic for the garbled line issue (as before, temporary)
    if paragraphs_raw and len(paragraphs_raw[-1]) < 50 and any(char in paragraphs_raw[-1] for char in ['io', 'og', 'al', 'op']):
         logger.warning("Detected potentially garbled last paragraph. Attempting to trim/omit.")
         paragraphs_raw[-1] = "11. Entire Agreement:\nThis proposal constitutes the entire agreement between the parties and supersedes all prior discussions and agreements."


    for i, para_text in enumerate(paragraphs_raw):
        para_text = para_text.strip()
        if not para_text:
            continue

        # Special handling for the main document title (PROPOSAL DOCUMENT)
        if i == 0 and "PROPOSAL DOCUMENT" in para_text.upper():
            p = Paragraph("PROPOSAL DOCUMENT", styles['DocumentTitle'])
            story.append(p)
            story.append(Spacer(1, 0.15 * inch)) # Add space after the title
            # Skip the rest of this initial block if it's just the title
            remaining_text_lines = para_text.splitlines()[1:]
            if remaining_text_lines:
                formatted_text = "<br/>".join(remaining_text_lines)
                p = Paragraph(formatted_text, styles['Normal'])
                story.append(p)
                story.append(Spacer(1, 0.1 * inch))
            continue # Move to the next paragraph

        # Check if the paragraph looks like a section header (e.g., starts with a number and dot or just bold text)
        # This is a heuristic and might need fine-tuning based on actual proposal content variability.
        is_section_header = False
        # Check for numbered sections (e.g., "1. Scope of Work:")
        if para_text.startswith(('1.', '2.', '3.', '4.', '5.', '6.', '7.', '8.', '9.', '10.', '11.')):
            is_section_header = True
        # Check for Exhibit headers (e.g., "Exhibit A: Cabinet Design") or Roman numeral headings
        elif para_text.startswith(('Exhibit ', 'I.', 'II.', 'III.', 'IV.', 'V.', 'VI.', 'VII.')):
            is_section_header = True
        # Check for specific known headers
        elif para_text.strip().upper() in ["IN WITNESS WHEREOF,", "EXHIBITS:"]:
            is_section_header = True


        if is_section_header:
            p = Paragraph(para_text, styles['SectionHeader'])
            story.append(p)
            # No additional Spacer here, as SectionHeader style has spaceAfter
        else:
            formatted_text = para_text.replace('\n', '<br/>')
            p = Paragraph(formatted_text, styles['Normal'])
            story.append(p)
            story.append(Spacer(1, 0.1 * inch)) # Standard space after body paragraphs

    doc.build(story)

    pdf_buffer.seek(0)

    # Upload the PDF to GCS
    storage_client = storage.Client()
    bucket = storage_client.bucket(STORAGE_BUCKET)
    blob = bucket.blob(PROPOSAL_DOCUMENT_FILE_NAME)

    blob.upload_from_file(pdf_buffer, content_type="application/pdf")

    logger.info(f"Successfully uploaded PDF to gs://{STORAGE_BUCKET}/{PROPOSAL_DOCUMENT_FILE_NAME}")

except Exception as e:
    logger.error(f"Error writing text to PDF and uploading: {e}")
    raise
finally:
    if 'pdf_buffer' in locals():
        pdf_buffer.close()
return "Successfully uploaded PDF to GCS!!"

مطمئن شوید که فضای ذخیره‌سازی ابری (Cloud Storage Bucket) را دارید

این برای ذخیره سند پیشنهادی است که عامل تولید می‌کند. آن را ایجاد کنید و دسترسی را فراهم کنید تا سیستم عامل ایجاد شده با Vertex AI بتواند به آن دسترسی داشته باشد. در اینجا نحوه انجام این کار آمده است:

https://cloud.google.com/storage/docs/creating-buckets#console

نام سطل خود را « next-demo-store » بگذارید. اگر نام دیگری برای آن انتخاب می‌کنید، فراموش نکنید که مقدار STORAGE_BUCKET را در فایل .env (در مرحله تنظیم متغیرهای ENV) به‌روزرسانی کنید.

برای تنظیم دسترسی به سطل، به کنسول ذخیره‌سازی ابری و به سطل ذخیره‌سازی خود بروید (در مورد ما نام سطل "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.

ایجاد لیست وابستگی‌ها

تمام وابستگی‌ها را در requirements.txt فهرست کنید. می‌توانید این را از مخزن کپی کنید.

توضیح کد منبع سیستم تک عاملی

فایل agent.py ساختار و رفتار سیستم چندعاملی نوسازی آشپزخانه ما را با استفاده از کیت توسعه عامل (ADK) تعریف می‌کند. بیایید اجزای کلیدی را تجزیه کنیم:

تعریف عامل

عامل ریشه (هماهنگ‌کننده): proposal_agent

root_agent به عنوان هماهنگ‌کننده‌ی این سیستم تک‌عاملی عمل می‌کند. این عامل درخواست اولیه‌ی نوسازی را دریافت می‌کند و بر اساس نیازهای درخواست، تعیین می‌کند که کدام ابزارها را فراخوانی کند.

سپس root_agent پاسخ‌ها را از ابزارها جمع‌آوری کرده و آنها را ترکیب می‌کند تا یک پاسخ جامع به کاربر ارائه دهد. در این حالت ما فقط یک ابزار به نام "store_pdf" داریم.

۷. جریان داده‌ها و مفاهیم کلیدی

کاربر از طریق رابط ADK (ترمینال یا رابط کاربری وب) درخواستی را آغاز می‌کند.

درخواست توسط root_agent دریافت می‌شود.
root_agent درخواست را تجزیه و تحلیل می‌کند و در صورت نیاز، آن را به ابزار مربوطه هدایت می‌کند.
ابزار "store_pdf" برای نوشتن محتوای متنی بازسازی‌شده در یک فایل PDF و سپس آپلود آن در فضای ذخیره‌سازی ابری گوگل طراحی شده است.
سپس این پاسخ را به root_agent برمی‌گرداند.
تابع root_agent پاسخ‌ها را ترکیب کرده و خروجی نهایی را به کاربر ارائه می‌دهد.

LLM (مدل‌های زبان بزرگ)

عامل‌ها برای تولید متن، پاسخ به سوالات و انجام وظایف استدلالی به شدت به LLMها متکی هستند. LLMها "مغز" پشت توانایی عامل‌ها برای درک و پاسخ به درخواست‌های کاربر هستند. ما در این برنامه از Gemini 2.5 استفاده می‌کنیم.

فضای ذخیره‌سازی ابری گوگل

برای ذخیره اسناد پیشنهاد نوسازی تولید شده استفاده می‌شود. شما باید یک سطل ایجاد کنید و مجوزهای لازم را برای دسترسی به آن به نمایندگان اعطا کنید.

اجرای ابری (اختیاری)

OrderingAgent از یک تابع Cloud Run برای ارتباط با AlloyDB استفاده می‌کند. Cloud Run یک محیط بدون سرور برای اجرای کد در پاسخ به درخواست‌های HTTP فراهم می‌کند.

آلیاژ دی‌بی

اگر از OrderingAgent استفاده می‌کنید، باید یک پایگاه داده AlloyDB برای ذخیره اطلاعات سفارش تنظیم کنید.

فایل .env

فایل .env اطلاعات حساسی مانند کلیدهای API، اعتبارنامه‌های پایگاه داده و نام‌های باکت را ذخیره می‌کند. بسیار مهم است که این فایل را ایمن نگه دارید و آن را در مخزن خود ذخیره نکنید. همچنین تنظیمات پیکربندی برای عامل‌ها و پروژه Google Cloud شما را ذخیره می‌کند. root_agent یا توابع پشتیبانی معمولاً مقادیر را از این فایل می‌خوانند. مطمئن شوید که همه متغیرهای مورد نیاز به درستی در فایل .env تنظیم شده‌اند. این شامل نام باکت Cloud Storage نیز می‌شود.

۸. تنظیمات مدل

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

یک کلید API از Google AI Studio دریافت کنید.
در مرحله بعدی که فایل .env را تنظیم می‌کنید، <<your API KEY>> را با مقدار واقعی API KEY خود جایگزین کنید.

۹. تنظیمات متغیرهای ENV

مقادیر پارامترهای خود را در فایل .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>>

مقادیر خود را جایگزین متغیرهایی کنید.

۱۰. عامل خود را اجرا کنید

با استفاده از ترمینال، به دایرکتوری والد پروژه عامل خود بروید:

cd agentic-apps/renovation-agent

نصب تمام وابستگی‌ها

pip install -r requirements.txt

برای اجرای عامل می‌توانید دستور زیر را در ترمینال Cloud Shell خود اجرا کنید:

adk run .

برای اجرای آن در یک رابط کاربری وبِ ارائه شده توسط ADK، می‌توانید دستور زیر را اجرا کنید:

توجه: شما باید این دستور را از خارج از پوشه پروژه عامل خود اجرا کنید و یک مرحله از آن خارج شوید و سپس آن را اجرا کنید:

adk web

با دستور زیر تست کنید:

user>> 

Hello. Generate Proposal Document for the kitchen remodel requirement in a proper format that applies to a renovation contract. Remember this text will eventually be stored as a pdf file so make sure to have the formatting appropriate. I have no other specification.

۱۱. نتیجه

برای دستور adk دستور زیر را اجرا کنید. نتیجه به شرح زیر است:

...

۹۱۴۵۲a۴de۹۳۳a۷۵b.png

می‌توانید تأیید کنید که آیا سند پیشنهاد نوسازی در مخزن ذخیره‌سازی ابری ایجاد شده است یا خیر.

۱۲. استقرار در Cloud Run

فایلی با نام Dockerfile در پوشه ریشه پروژه ایجاد کنید:

cd agentic-apps/renovation-agent

محتوا را از مخزن گیت‌هاب کپی کنید

https://github.com/AbiramiSukumaran/adk-renovation-single-agent/blob/main/Dockerfile

در این فایل Dockerfile قرار دهید.

با استفاده از دستور زیر، روی Cloud Run مستقر کنید:

adk deploy cloud_run --project=abis-345004 --region=us-central1 --service_name=renovation-agent --app_name=renovation-app --with_ui .

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

۱۳. تمیز کردن

برای جلوگیری از تحمیل هزینه به حساب Google Cloud خود برای منابع استفاده شده در این پست، این مراحل را دنبال کنید:

در کنسول گوگل کلود، به صفحه مدیریت منابع بروید.
در لیست پروژه‌ها، پروژه‌ای را که می‌خواهید حذف کنید انتخاب کنید و سپس روی «حذف» کلیک کنید.
در کادر محاوره‌ای، شناسه پروژه را تایپ کنید و سپس برای حذف پروژه، روی خاموش کردن کلیک کنید.

۱۴. تبریک

تبریک! شما با موفقیت برنامه چندعاملی خود را با استفاده از ADK ایجاد و با آن تعامل کردید! سیستم چندعاملی برای ساده‌سازی فرآیند نوسازی آشپزخانه با خودکارسازی وظایفی مانند تولید پیشنهاد، بررسی مجوز و ردیابی وضعیت سفارش طراحی شده است. هر عامل نقش خاصی دارد و root_agent فعالیت‌های آنها را برای ارائه یک راه‌حل جامع هماهنگ می‌کند. این سیستم از LLMها، سرویس‌های Google Cloud و APIهای خارجی بالقوه برای ارائه قابلیت‌های خود استفاده می‌کند. در اینجا پیوندی به مستندات محصول وجود دارد.

از نمونه های اولیه تا عوامل با ADK با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.