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

1. مقدمه

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

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

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

پیش نیازها

• یک سرور MCP در حال اجرا در Cloud Run یا URL سرویس مرتبط با آن.
• یک پروژه Google Cloud با فعال کردن صورت‌حساب.

چیزی که یاد خواهید گرفت

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

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

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

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

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

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

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

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

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

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

• اگر 0 نفر از برنامه شما استفاده می کنند ← 0 نمونه اجرا می شود (در حالت بیکار 0 دلار پرداخت می کنید).
• اگر 1000 درخواست به آن رسید ← به تعداد مورد نیاز نسخه می‌چرخد.

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

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

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

• تا زمانی که در یک کانتینر لینوکس اجرا می شود، Cloud Run اهمیتی نمی دهد که Python، Go، Node.js، جاوا یا Net باشد.

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

• صورتحساب در هر درخواست + زمان محاسبه (تا 100 میلی ثانیه).
• شما مانند یک VM سنتی برای منابع بیکار هزینه نمی کنید.

3. راه اندازی و الزامات

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

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

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

احتیاط: شناسه پروژه در سطح جهانی منحصر به فرد است و پس از انتخاب شما توسط شخص دیگری نمی توان از آن استفاده کرد. شما تنها کاربر آن شناسه هستید. حتی اگر پروژه ای حذف شود، ID نمی تواند دوباره استفاده شود

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

2. در مرحله بعد، برای استفاده از منابع Cloud/APIها باید صورتحساب را در کنسول Cloud فعال کنید . اجرا کردن از طریق این کد لبه هزینه زیادی نخواهد داشت. برای خاموش کردن منابع برای جلوگیری از تحمیل صورت‌حساب فراتر از این آموزش، می‌توانید منابعی را که ایجاد کرده‌اید حذف کنید یا پروژه را حذف کنید. کاربران جدید Google Cloud واجد شرایط برنامه آزمایشی رایگان 300 دلاری هستند.

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

به Cloud Shell Editor بروید

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

• روی ترمینال کلیک کنید
• روی New Terminal کلیک کنید

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

gcloud config set project [YOUR-PROJECT-ID]

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

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

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

5. باید این پیام را ببینید:

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.

4. قبل از شروع

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.

منطقه پیش‌فرض خود را برای استفاده از مدل‌های جاسازی هوش مصنوعی Vertex پیکربندی کنید. درباره مکان‌های موجود برای Vertex AI بیشتر بخوانید. در مثال ما از منطقه اروپا-غرب استفاده می کنیم.

gcloud config set compute/region europe-west1

5. ADK را دانلود و نصب کنید و پوشه پروژه ایجاد کنید

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

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

cd && mkdir zoo_guide_agent && cd zoo_guide_agent

یک محیط مجازی ایجاد کنید.

python3 -m venv .venv

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

source .venv/bin/activate

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

cloudshell edit requirements.txt

google-adk==1.12.0
langchain-community
wikipedia

شما باید دستور را از دایرکتوری اصلی پروژه خود، zoo_guide_agent اجرا کنید.

pip install -r requirements.txt

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

export PROJECT_ID=$(gcloud config get-value project)
export PROJECT_REGION=$(gcloud config get-value compute/region)
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
export SERVICE_ACCOUNT="${PROJECT_NUMBER}[e-mail]"

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

cloudshell edit .env

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

MODEL="gemini-2.5-flash"
SERVICE_ACCOUNT="${PROJECT_NUMBER}[e-mail]"

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

توجه: اگر آزمایشگاه 1 را تکمیل کرده اید و می خواهید از سرور MCP ایجاد شده در آن آزمایشگاه استفاده کنید، سه دستور زیر را اجرا کنید. اگر قبلاً از پیوند سرور عمومی MCP که در طول یک رویداد زنده به شما ارائه شده است استفاده می کنید، نیازی به اجرای این دو دستور ندارید.

1. به سرویس Cloud Run اجازه دهید تا با سرور MCP راه دور تماس بگیرد

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$SERVICE_ACCOUNT" \
  --role="roles/run.invoker"

2. URL سرور MCP را از آزمایشگاه 1 در یک متغیر محیطی ذخیره کنید.

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

6. گردش کار Agent را ایجاد کنید

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

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

cloudshell edit __init__.py

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

from . import agent

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

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

cloudshell edit agent.py

مرحله 1: واردات و راه اندازی اولیه

این بلوک اول تمام کتابخانه های لازم را از 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")

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

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

2. MCPToolset 🦁

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

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

3. LangchainTool 🌍

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

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

منابع:

• مجموعه ابزار MCP
• ابزارهای تابع
• ایالت

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

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

نقش عامل قالب‌کننده پاسخ، ارائه است. از هیچ ابزاری برای یافتن اطلاعات جدید استفاده نمی کند. در عوض، داده‌های خام جمع‌آوری‌شده توسط عامل پژوهشگر (که از طریق ایالت ارسال شده) را می‌گیرد و از مهارت‌های زبانی 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 }}
    """
)

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

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

چگونه: این یک 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
    ]
)

مرحله آخر: گردش کار اصلی را جمع آوری کنید

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

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

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

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

source .env

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

# 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"

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

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

یک فایل .gcloudignore ایجاد کنید

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

cloudshell edit .gcloudignore

دستور ویرایش cloudshell فایل .gcloudignore را در ویرایشگر بالای ترمینال باز می کند. موارد زیر را در فایل بنویسید و ذخیره کنید. سپس به ترمینال برگردید تا دستورات استقرار را در بخش بعدی اجرا کنید.

.venv/

مستقر کنید

دستورات زیر را برای استقرار عامل خود اجرا کنید.

توجه: اجرای دستور deploy زیر چند دقیقه طول می کشد تا اجرا شود.

# Run the deployment command
adk deploy cloud_run \
  --project=$PROJECT_ID \
  --region=europe-west1 \
  --service_name=zoo-tour-guide \
  --with_ui \
  .

gcloud run services update zoo-tour-guide \
  --region=europe-west1 \
  --update-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 را داشته باشد به این عامل دسترسی خواهد داشت، بنابراین این برای آزمایش بهترین است.

پیوند استقرار را دریافت کنید

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

9. عامل مستقر شده را آزمایش کنید

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

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

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

اکنون می توانید با عامل Zoo تعامل داشته باشید.

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?"

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

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

1. The Zoo Greeter (میز استقبال )

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

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

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

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

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

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

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

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

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

3. قالب پاسخ (ارائه کننده)

هنگامی که محقق جامع همه حقایق را جمع آوری کرد، این نماینده نهایی برای اجراست.

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

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

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

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

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

توجه: -

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

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

11. تبریک می گویم

برای تکمیل کد لبه تبریک می گویم.

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

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

12. نظرسنجی

خروجی:

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

فقط آن را بخوانید آن را بخوانید و تمرینات را کامل کنید