یک عامل ADK که از یک سرور MCP در Cloud Run استفاده می کند، بسازید و استقرار دهید

۱. مقدمه

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

در آزمایش ۱، شما یک سرور MCP ایجاد کردید که داده‌های مربوط به حیوانات یک باغ‌وحش خیالی را برای LLMها فراهم می‌کند، برای مثال هنگام استفاده از Gemini CLI. در این آزمایش، ما در حال ساخت یک عامل راهنمای تور برای باغ‌وحش خیالی هستیم. عامل از همان سرور MCP آزمایش ۱ برای دسترسی به جزئیات مربوط به حیوانات باغ‌وحش استفاده خواهد کرد و همچنین از ویکی‌پدیا برای ایجاد بهترین تجربه راهنمای تور استفاده خواهد کرد.

f8d4423edbfe993d.png

در نهایت، راهنمای تور را در Google Cloud Run مستقر خواهیم کرد تا همه بازدیدکنندگان باغ وحش به آن دسترسی داشته باشند، نه اینکه فقط به صورت محلی اجرا شود.

پیش‌نیازها

  • یک سرور MCP در حال اجرا روی Cloud Run یا URL سرویس مرتبط با آن.
  • یک پروژه گوگل کلود با قابلیت پرداخت.

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

  • نحوه ساختاردهی یک پروژه پایتون برای استقرار ADK.
  • نحوه پیاده‌سازی یک عامل استفاده‌کننده از ابزار با google-adk.
  • نحوه اتصال یک عامل به یک سرور MCP از راه دور برای مجموعه ابزارهای آن.
  • نحوه استقرار یک برنامه پایتون به عنوان یک کانتینر بدون سرور در Cloud Run.
  • نحوه پیکربندی احراز هویت امن سرویس به سرویس با استفاده از نقش‌های IAM.
  • نحوه حذف منابع ابری برای جلوگیری از هزینه‌های آینده.

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

  • یک حساب کاربری گوگل کلود و پروژه گوگل کلود
  • یک مرورگر وب مانند کروم

۲. چرا باید روی Cloud Run مستقر شویم؟

Cloud Run یک انتخاب عالی برای میزبانی از عوامل ADK است زیرا یک پلتفرم بدون سرور است، به این معنی که می‌توانید روی کد خود تمرکز کنید و نیازی به مدیریت زیرساخت‌های اساسی ندارید. ما کارهای عملیاتی را برای شما انجام می‌دهیم.

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

ویژگی‌های کلیدی

کانتینرها را در هر مکانی اجرا می‌کند:

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

مقیاس‌بندی خودکار:

  • اگر ۰ نفر از برنامه شما استفاده می‌کنند → ۰ نمونه اجرا می‌شود (مقیاس به صفر نمونه کاهش می‌یابد که مقرون به صرفه است).
  • اگر ۱۰۰۰ درخواست به آن برسد → به تعداد مورد نیاز کپی تهیه می‌کند.

بدون تابعیت به طور پیش‌فرض:

  • هر درخواست می‌تواند به یک نمونه متفاوت برود.
  • اگر نیاز به ذخیره وضعیت (state) دارید، از یک سرویس خارجی مانند Cloud SQL، Firestore یا Memorystore استفاده کنید.

پشتیبانی از هر زبان یا چارچوبی:

  • تا زمانی که در یک کانتینر لینوکس اجرا شود، Cloud Run اهمیتی نمی‌دهد که پایتون، گو، نودجی‌اس، جاوا یا دات‌نت باشد.

برای آنچه استفاده می‌کنید، هزینه بپردازید:

۳. تنظیمات و الزامات

تنظیم محیط خودتنظیم

  1. وارد کنسول گوگل کلود شوید و یک پروژه جدید ایجاد کنید یا از یک پروژه موجود دوباره استفاده کنید. اگر از قبل حساب جیمیل یا گوگل ورک اسپیس ندارید، باید یکی ایجاد کنید .

fbef9caa1602edd0.png

a99b7ace416376c4.png

5e3ff691252acf41.png

  • نام پروژه ، نام نمایشی برای شرکت‌کنندگان این پروژه است. این یک رشته کاراکتری است که توسط APIهای گوگل استفاده نمی‌شود. شما همیشه می‌توانید آن را به‌روزرسانی کنید.
  • شناسه پروژه در تمام پروژه‌های گوگل کلود منحصر به فرد است و تغییرناپذیر است (پس از تنظیم، قابل تغییر نیست). کنسول کلود به طور خودکار یک رشته منحصر به فرد تولید می‌کند؛ معمولاً برای شما مهم نیست که چه باشد. در اکثر آزمایشگاه‌های کد، باید شناسه پروژه خود را (که معمولاً با عنوان PROJECT_ID شناخته می‌شود) ارجاع دهید. اگر شناسه تولید شده را دوست ندارید، می‌توانید یک شناسه تصادفی دیگر ایجاد کنید. به عنوان یک جایگزین، می‌توانید شناسه خودتان را امتحان کنید و ببینید که آیا در دسترس است یا خیر. پس از این مرحله قابل تغییر نیست و در طول پروژه باقی می‌ماند.
  • برای اطلاع شما، یک مقدار سوم، شماره پروژه ، وجود دارد که برخی از APIها از آن استفاده می‌کنند. برای کسب اطلاعات بیشتر در مورد هر سه این مقادیر، به مستندات مراجعه کنید.
  1. در مرحله بعد، برای استفاده از منابع/API های ابری، باید پرداخت صورتحساب را در کنسول ابری فعال کنید . اجرای این آزمایشگاه کد هزینه زیادی نخواهد داشت، اگر اصلاً هزینه‌ای داشته باشد. برای خاموش کردن منابع به منظور جلوگیری از پرداخت صورتحساب پس از این آموزش، می‌توانید منابعی را که ایجاد کرده‌اید یا پروژه را حذف کنید. کاربران جدید Google Cloud واجد شرایط برنامه آزمایشی رایگان ۳۰۰ دلاری هستند.

شروع پوسته ابری

اگر ترمینال در پایین صفحه نمایش داده نشد، آن را باز کنید:

  • روی ترمینال کلیک کنید
  • روی ترمینال جدید کلیک کنید

d32c46fffa0a30a5.png

در ترمینال، پروژه خود را با این دستور تنظیم کنید. اگر آزمایش ۱ را تمام کرده‌اید، مطمئن شوید که از همان شناسه پروژه استفاده می‌کنید: 

gcloud config set project [YOUR-PROJECT-ID]

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

gcloud projects list | awk '/PROJECT_ID/{print $2}'

۴. اگر از شما خواسته شد که مجوز دهید، برای ادامه روی «مجوز دادن» کلیک کنید.

6356559df3eccdda.png

۵. شما باید این پیام را ببینید: 

Updated property [core/project].

If you see a `WARNING` and are asked `Do you want to continue (Y/n)?`,

then you have likely entered the project ID incorrectly. Press `n`,

press `Enter`, and try to run the `gcloud config set project` command again.

۴. قبل از شروع

فعال کردن APIها و تنظیم متغیرهای محیطی

فعال کردن تمام سرویس‌های لازم:

gcloud services enable \
    run.googleapis.com \
    artifactregistry.googleapis.com \
    cloudbuild.googleapis.com \
    aiplatform.googleapis.com \
    compute.googleapis.com

خروجی مورد انتظار

Operation "operations/acat.p2-[GUID]" finished successfully.

۵. پوشه پروژه را ایجاد کنید

دایرکتوری پروژه را ایجاد کنید.

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

cd && mkdir zoo_guide_agent && cd zoo_guide_agent

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

cloudshell edit requirements.txt

google-adk==1.14.0
langchain-community==0.3.27
wikipedia==1.4.0

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

export PROJECT_ID=$(gcloud config get-value project)
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
export SERVICE_ACCOUNT="${PROJECT_NUMBER}-compute@developer.gserviceaccount.com"

یک فایل .env برای احراز هویت عامل در دایرکتوری zoo_guide_agent ایجاد و باز کنید. 

cloudshell edit .env

دستور cloudshell edit فایل .env را در ویرایشگر بالای ترمینال باز می‌کند. عبارت زیر را در فایل .env وارد کنید و به ترمینال برگردید. 

MODEL="gemini-2.5-flash"
SERVICE_ACCOUNT="${PROJECT_NUMBER}-compute@developer.gserviceaccount.com"

افزودن آدرس اینترنتی سرور MCP . اگر آزمایش ۱ را به پایان رسانده‌اید، برای استفاده از سرور MCP که در آزمایش ۱ ایجاد کرده‌اید، این مراحل را دنبال کنید:

  1. به سرویس Cloud Run اجازه دهید تا با سرور MCP از راه دور تماس بگیرد. 
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$SERVICE_ACCOUNT" \
  --role="roles/run.invoker"
  1. آدرس اینترنتی سرور MCP را از آزمایش ۱ در یک متغیر محیطی ذخیره کنید. 
echo -e "\nMCP_SERVER_URL=https://zoo-mcp-server-${PROJECT_NUMBER}.europe-west1.run.app/mcp" >> .env

اگر از لینک سرور عمومی MCP استفاده می‌کنید، دستور زیر را اجرا کنید و PROJECT_NUMBER با آنچه ارائه شده است جایگزین کنید. 

echo -e "\nMCP_SERVER_URL=https://zoo-mcp-server-${PROJECT_NUMBER}.europe-west1.run.app/mcp" >> .env

۶. ایجاد گردش کار برای اپراتور

ایجاد فایل init.py

فایل init.py را ایجاد کنید. این فایل به پایتون می‌گوید که دایرکتوری zoo_guide_agent یک پکیج است. 

cloudshell edit __init__.py

دستور بالا ویرایشگر کد را باز می‌کند. کد زیر را به __init__.py اضافه کنید: 

from . import agent

فایل اصلی agent.py را ایجاد کنید

فایل اصلی agent.py را ایجاد کنید. این دستور فایل پایتون را ایجاد می‌کند و کد کامل سیستم چندعاملی شما را در آن قرار می‌دهد. 

cloudshell edit agent.py

مرحله ۱: وارد کردن و راه‌اندازی اولیه

این بلوک اول تمام کتابخانه‌های لازم را از ADK و Google Cloud می‌آورد. همچنین ثبت وقایع را تنظیم می‌کند و متغیرهای محیطی را از فایل .env شما بارگذاری می‌کند، که برای دسترسی به مدل و URL سرور شما بسیار مهم است.

کد زیر را به فایل agent.py خود اضافه کنید: 

import os
import logging
import google.cloud.logging
from dotenv import load_dotenv

from google.adk import Agent
from google.adk.agents import SequentialAgent
from google.adk.tools.mcp_tool.mcp_toolset import MCPToolset, StreamableHTTPConnectionParams
from google.adk.tools.tool_context import ToolContext
from google.adk.tools.langchain_tool import LangchainTool

from langchain_community.tools import WikipediaQueryRun
from langchain_community.utilities import WikipediaAPIWrapper

import google.auth
import google.auth.transport.requests
import google.oauth2.id_token

# --- Setup Logging and Environment ---

cloud_logging_client = google.cloud.logging.Client()
cloud_logging_client.setup_logging()

load_dotenv()

model_name = os.getenv("MODEL")

مرحله ۲: تعریف ابزارها (قابلیت‌های عامل)

3eb9c6772576b906.jpeg

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

کد زیر را به انتهای agent.py اضافه کنید: 

# Greet user and save their prompt

def add_prompt_to_state(
    tool_context: ToolContext, prompt: str
) -> dict[str, str]:
    """Saves the user's initial prompt to the state."""
    tool_context.state["PROMPT"] = prompt
    logging.info(f"[State updated] Added to PROMPT: {prompt}")
    return {"status": "success"}


# Configuring the MCP Tool to connect to the Zoo MCP server

mcp_server_url = os.getenv("MCP_SERVER_URL")
if not mcp_server_url:
    raise ValueError("The environment variable MCP_SERVER_URL is not set.")

def get_id_token():
    """Get an ID token to authenticate with the MCP server."""
    target_url = os.getenv("MCP_SERVER_URL")
    audience = target_url.split('/mcp/')[0]
    request = google.auth.transport.requests.Request()
    id_token = google.oauth2.id_token.fetch_id_token(request, audience)
    return id_token

"""
# Use this code if you are using the public MCP Server and comment out the code below defining mcp_tools
mcp_tools = MCPToolset(
    connection_params=StreamableHTTPConnectionParams(
        url=mcp_server_url
    )
)
"""

mcp_tools = MCPToolset(
            connection_params=StreamableHTTPConnectionParams(
                url=mcp_server_url,
                headers={
                    "Authorization": f"Bearer {get_id_token()}",
                },
            ),
        )

# Configuring the Wikipedia Tool
wikipedia_tool = LangchainTool(
    tool=WikipediaQueryRun(api_wrapper=WikipediaAPIWrapper())
)

سه ابزار توضیح داده شده

  1. add_prompt_to_state 📝

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

نحوه‌ی انجام: این یک تابع پایتون است که اعلان بازدیدکننده را در دیکشنری مشترک tool_context.state می‌نویسد. این زمینه‌ی ابزار، حافظه‌ی کوتاه‌مدت عامل را برای یک مکالمه‌ی واحد نشان می‌دهد. داده‌های ذخیره‌شده در وضعیت توسط یک عامل، می‌تواند توسط عامل بعدی در گردش کار خوانده شود.

  1. MCPToolset

این برای اتصال نماینده راهنمای تور به سرور MCP باغ وحش که در آزمایش ۱ ایجاد شده است، استفاده می‌شود. این سرور ابزارهای ویژه‌ای برای جستجوی اطلاعات خاص در مورد حیوانات ما، مانند نام، سن و محل نگهداری آنها دارد.

چگونه: به طور ایمن به آدرس اینترنتی سرور خصوصی باغ وحش متصل می‌شود. از get_id_token برای دریافت خودکار یک "keycard" امن (یک توکن شناسه حساب سرویس) برای اثبات هویت خود و دسترسی به آن استفاده می‌کند.

  1. LangchainTool

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

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

منابع:

مرحله ۳: تعریف نمایندگان متخصص

b8a9504b21920969.jpeg

در ادامه، عامل محقق و عامل قالب‌بندی پاسخ را تعریف خواهیم کرد. عامل محقق «مغز» عملیات ما است. این عامل، درخواست کاربر را از State مشترک می‌گیرد، ابزارهای قدرتمند خود (ابزار MCP Server در Zoo و ابزار ویکی‌پدیا) را بررسی می‌کند و تصمیم می‌گیرد که از کدام یک برای یافتن پاسخ استفاده کند.

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

کد زیر را به انتهای agent.py اضافه کنید: 

# 1. Researcher Agent
comprehensive_researcher = Agent(
    name="comprehensive_researcher",
    model=model_name,
    description="The primary researcher that can access both internal zoo data and external knowledge from Wikipedia.",
    instruction="""
    You are a helpful research assistant. Your goal is to fully answer the user's PROMPT.
    You have access to two tools:
    1. A tool for getting specific data about animals AT OUR ZOO (names, ages, locations).
    2. A tool for searching Wikipedia for general knowledge (facts, lifespan, diet, habitat).

    First, analyze the user's PROMPT.
    - If the prompt can be answered by only one tool, use that tool.
    - If the prompt is complex and requires information from both the zoo's database AND Wikipedia,
      you MUST use both tools to gather all necessary information.
    - Synthesize the results from the tool(s) you use into preliminary data outputs.

    PROMPT:
    {{ PROMPT }}
    """,
    tools=[
        mcp_tools,
        wikipedia_tool
    ],
    output_key="research_data" # A key to store the combined findings
)

# 2. Response Formatter Agent
response_formatter = Agent(
    name="response_formatter",
    model=model_name,
    description="Synthesizes all information into a friendly, readable response.",
    instruction="""
    You are the friendly voice of the Zoo Tour Guide. Your task is to take the
    RESEARCH_DATA and present it to the user in a complete and helpful answer.

    - First, present the specific information from the zoo (like names, ages, and where to find them).
    - Then, add the interesting general facts from the research.
    - If some information is missing, just present the information you have.
    - Be conversational and engaging.

    RESEARCH_DATA:
    {{ research_data }}
    """
)

مرحله ۴: عامل گردش کار

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

نحوه‌ی کار: این یک SequentialAgent است، نوع خاصی از عامل که به خودی خود فکر نمی‌کند. تنها وظیفه‌ی آن اجرای لیستی از sub_agents (محقق و قالب‌دهنده) در یک توالی ثابت است و به طور خودکار حافظه‌ی مشترک را از یکی به دیگری منتقل می‌کند.

این بلوک کد را به انتهای agent.py اضافه کنید: 

tour_guide_workflow = SequentialAgent(
    name="tour_guide_workflow",
    description="The main workflow for handling a user's request about an animal.",
    sub_agents=[
        comprehensive_researcher, # Step 1: Gather all data
        response_formatter,       # Step 2: Format the final response
    ]
)

مرحله نهایی: مونتاژ گردش کار اصلی ۱۰۰۰b9d20f4e134b.jpeg

این عامل به عنوان root_agent تعیین شده است که چارچوب ADK از آن به عنوان نقطه شروع برای همه مکالمات جدید استفاده می‌کند. نقش اصلی آن هماهنگ کردن فرآیند کلی است. این عامل به عنوان کنترل‌کننده اولیه عمل می‌کند و اولین نوبت مکالمه را مدیریت می‌کند.

این بلوک کد نهایی را به انتهای agent.py اضافه کنید: 

root_agent = Agent(
    name="greeter",
    model=model_name,
    description="The main entry point for the Zoo Tour Guide.",
    instruction="""
    - Let the user know you will help them learn about the animals we have in the zoo.
    - When the user responds, use the 'add_prompt_to_state' tool to save their response.
    After using the tool, transfer control to the 'tour_guide_workflow' agent.
    """,
    tools=[add_prompt_to_state],
    sub_agents=[tour_guide_workflow]
)

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

۷. برنامه را برای استقرار آماده کنید

با آماده شدن محیط محلی، مرحله بعدی آماده‌سازی پروژه Google Cloud برای استقرار است. این شامل بررسی نهایی ساختار فایل عامل شما برای اطمینان از سازگاری آن با دستور استقرار است. مهمتر از آن، شما یک مجوز IAM حیاتی پیکربندی می‌کنید که به سرویس Cloud Run مستقر شده شما اجازه می‌دهد از طرف شما عمل کند و مدل‌های هوش مصنوعی Vertex را فراخوانی کند. تکمیل این مرحله تضمین می‌کند که محیط ابری برای اجرای موفقیت‌آمیز عامل شما آماده است.

با اجرای دستور source، متغیرها را در جلسه پوسته خود بارگذاری کنید. 

source .env

به حساب کاربری سرویس، نقش Vertex AI User را اعطا کنید، که به آن اجازه می‌دهد پیش‌بینی‌هایی انجام دهد و مدل‌های گوگل را فراخوانی کند. 

# Grant the "Vertex AI User" role to your service account
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$SERVICE_ACCOUNT" \
  --role="roles/aiplatform.user"

۸. با استفاده از ADK CLI، عامل را مستقر کنید

با آماده شدن کد محلی و پروژه Google Cloud شما، زمان استقرار عامل فرا رسیده است. شما از دستور adk deploy cloud_run استفاده خواهید کرد، ابزاری مناسب که کل گردش کار استقرار را خودکار می‌کند. این دستور واحد، کد شما را بسته‌بندی می‌کند، یک تصویر کانتینر می‌سازد، آن را به Artifact Registry ارسال می‌کند و سرویس را در Cloud Run راه‌اندازی می‌کند و آن را در وب قابل دسترسی می‌سازد.

استقرار

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

# Run the deployment command
uvx --from google-adk \
adk deploy cloud_run \
  --project=$PROJECT_ID \
  --region=europe-west1 \
  --service_name=zoo-tour-guide \
  --with_ui \
  . \
  -- \
  --labels=dev-tutorial=codelab-adk

پذیرش درخواست‌ها

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

Deploying from source requires an Artifact Registry Docker repository to store built containers. A repository named [cloud-run-source-deploy] in region 
[europe-west1] will be created.

Do you want to continue (Y/n)?

Y را تایپ کنید و ENTER را بزنید.

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

Allow unauthenticated invocations to [your-service-name] (y/N)?.

برای این آزمایش، می‌خواهیم برای آزمایش آسان، فراخوانی‌های احراز هویت نشده را مجاز کنیم، y را تایپ کرده و Enter را بزنید.

پس از اجرای موفقیت‌آمیز، دستور، URL سرویس Cloud Run مستقر شده را ارائه می‌دهد. (چیزی شبیه به https://zoo-tour-guide-123456789.europe-west1.run.app خواهد بود). این URL را برای کار بعدی کپی کنید.

۹. تست عامل مستقر شده

حالا که عامل شما روی Cloud Run فعال است، آزمایشی انجام خواهید داد تا مطمئن شوید که پیاده‌سازی موفقیت‌آمیز بوده و عامل طبق انتظار کار می‌کند. برای دسترسی به رابط وب ADK و تعامل با عامل، از آدرس عمومی Service URL (چیزی شبیه به https://zoo-tour-guide-123456789.europe-west1.run.app/ ) استفاده خواهید کرد.

آدرس اینترنتی عمومی سرویس Cloud Run را در مرورگر وب خود باز کنید. از آنجا که --with_ui flag استفاده کرده‌اید، باید رابط کاربری توسعه‌دهنده ADK را ببینید.

در بالا سمت راست، گزینه Token Streaming فعال کنید.

اکنون می‌توانید با نماینده باغ وحش تعامل داشته باشید.

برای شروع مکالمه جدید، hello را تایپ کرده و اینتر را بزنید.

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

"Hello! I'm your Zoo Tour Guide. I can help you learn about the amazing animals we have here. What would you like to know or explore today?"

از نماینده سوالاتی مانند موارد زیر بپرسید: 

Where can I find the polar bears in the zoo and what is their diet?

۳۲۴۴d2f6c3b03088.pnge135694253b1be41.png

جریان عامل توضیح داده شده است

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

۱. پیشخدمت باغ وحش (میز خوشامدگویی )

کل فرآیند با عامل خوشامدگویی آغاز می‌شود.

وظیفه آن: شروع مکالمه. دستورالعمل آن این است که به کاربر سلام کند و بپرسد که دوست دارد درباره چه حیوانی اطلاعات کسب کند.

ابزار آن: وقتی کاربر پاسخ می‌دهد، خوشامدگو از ابزار add_prompt_to_state خود برای دریافت دقیق کلمات او (مثلاً «درباره شیرها به من بگو») و ذخیره آنها در حافظه سیستم استفاده می‌کند.

انتقال: پس از ذخیره اعلان، بلافاصله کنترل به عامل فرعی خود، tour_guide_workflow، منتقل می‌شود.

۲. محقق جامع (ابر محقق)

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

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

  • داده‌های داخلی از سوابق باغ‌وحش (از طریق سرور MCP).
  • دانش عمومی از وب (از طریق API ویکی‌پدیا).
  • یا، برای سوالات پیچیده، هر دو.

عملکرد آن: ابزار(های) لازم را برای جمع‌آوری تمام داده‌های خام مورد نیاز اجرا می‌کند. برای مثال، اگر از او پرسیده شود «شیرهای ما چند ساله هستند و در طبیعت چه می‌خورند؟»، سرور MCP را برای سن و ابزار ویکی‌پدیا را برای اطلاعات رژیم غذایی فراخوانی می‌کند.

۳. قالب‌دهنده پاسخ (ارائه‌دهنده)

وقتی محقق جامع تمام حقایق را جمع‌آوری کرد، این آخرین عاملی است که باید اجرا شود.

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

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

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

اگر علاقه‌مند به کسب اطلاعات بیشتر در مورد عوامل سازنده هستید، منابع زیر را بررسی کنید:

  1. اسناد ADK
  2. ساخت ابزارهای سفارشی برای عوامل ADK

۱۰. محیط را تمیز کنید 

gcloud run services delete zoo-tour-guide --region=europe-west1 --quiet
gcloud artifacts repositories delete cloud-run-source-deploy --location=europe-west1 --quiet

۱۱. تبریک

تبریک می‌گویم که آزمایشگاه کد را تمام کردی.

آنچه ما پوشش داده‌ایم

  • نحوه ساختاردهی یک پروژه پایتون برای استقرار با رابط خط فرمان ADK.
  • نحوه پیاده‌سازی گردش کار چندعاملی با استفاده از SequentialAgent و ParallelAgent.
  • نحوه اتصال به یک سرور MCP از راه دور با استفاده از MCPToolset برای استفاده از ابزارهای آن.
  • چگونه با ادغام ابزارهای خارجی مانند API ویکی‌پدیا، داده‌های داخلی را افزایش دهیم.
  • نحوه‌ی استقرار یک عامل به عنوان یک کانتینر بدون سرور در Cloud Run با استفاده از دستور adk deploy.

۱۲. نظرسنجی

خروجی:

چگونه از این آموزش استفاده خواهید کرد؟

فقط آن را بخوانید آن را بخوانید و تمرین‌ها را انجام دهید