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

نحوه استقرار یک برنامه gradio frontend که یک عامل ADK باطن را فراخوانی می کند، هر دو در Cloud Run اجرا می شوند

1. مقدمه

نمای کلی

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

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

نحوه استقرار یک عامل ADK در Cloud Run
نحوه استقرار یک برنامه gradio در Cloud Run
نحوه برقراری تماس های تایید شده سرویس به سرویس در Cloud Run

2. API ها را فعال کنید

ابتدا پروژه Google Cloud خود را تنظیم کنید.

gcloud config set project <YOUR_PROJECT_ID>

با اجرای دستور زیر می توانید پروژه Google Cloud خود را تأیید کنید:

gcloud config get-value project

این نرم افزار کد نیاز به فعال کردن API های زیر دارد:

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

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

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

ابتدا متغیرهای محیطی را برای این Codelab تنظیم کنید که در سرتاسر این Codelab مورد استفاده قرار خواهند گرفت.

export PROJECT_ID=<YOUR_PROJECT_ID>
export REGION=<YOUR_REGION>

export SERVICE_ACCOUNT_ADK="adk-agent-cr"
export SERVICE_ACCOUNT_ADDRESS_ADK=$SERVICE_ACCOUNT_ADK@$PROJECT_ID.iam.gserviceaccount.com

export SERVICE_ACCOUNT_GRADIO="adk-agent-gradio"
export SERVICE_ACCOUNT_ADDRESS_GRADIO=$SERVICE_ACCOUNT_GRADIO@$PROJECT_ID.iam.gserviceaccount.com

export AGENT_APP_NAME="multi_tool_agent"

در مرحله بعد، حساب سرویس را برای عامل ADK ایجاد کنید.

gcloud iam service-accounts create $SERVICE_ACCOUNT_ADK \
--display-name="Service account for adk agent on cloud run"

و به حساب سرویس ADK نقش "کاربر Vertex AI" را اعطا کنید

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$SERVICE_ACCOUNT_ADDRESS_ADK" \
  --role="roles/aiplatform.user"

اکنون حساب سرویس را برای Gradio frontend ایجاد کنید

gcloud iam service-accounts create $SERVICE_ACCOUNT_GRADIO \
  --display-name="Service account for gradio frontend cloud run"

و به Gradio frontend نقش فراخوان دهنده Cloud Run را اعطا کنید، که به آن اجازه می دهد تا عامل ADK میزبانی شده در Cloud Run را فراخوانی کند.

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

4. یک برنامه ADK ایجاد کنید

در مرحله بعد، کد برنامه سریع ADK را ایجاد می کنید.

توجه: در انتهای آزمایشگاه، ساختار فایل شما باید به شکل زیر باشد:

- codelab-gradio-adk  <-- you'll deploy the ADK agent from here
  - gradio-frontend  <-- you'll deploy the gradio app from here
    - app.py
    - requirements.txt
  - multi_tool_agent
    - __init__.py
    - agent.py
    - requirements.txt

ابتدا یک دایرکتوری برای کل کدلب ایجاد کنید

mkdir codelab-gradio-adk
cd codelab-gradio-adk

اکنون یک دایرکتوری برای سرویس عامل ADK ایجاد کنید.

mkdir multi_tool_agent && cd multi_tool_agent

یک فایل __init__.py با محتویات زیر ایجاد کنید:

from . import agent

یک فایل requirements.txt ایجاد کنید:

google-adk

یک فایل به نام agent.py ایجاد کنید

import datetime
from zoneinfo import ZoneInfo
from google.adk.agents import Agent

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.",
        }


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(
    name="weather_time_agent",
    model="gemini-2.5-flash",
    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],
)

5. عامل ADK را مستقر کنید

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

به پوشه والد بروید.

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

cd ..

ابتدا سرویس Cloud Run را ایجاد کنید:

توجه: همانطور که در مرحله آینده نشان داده شده است، --with_ui برای آزمایش با Dev UI اختیاری است:

توجه: دستور -- به شما اجازه می دهد تا از طریق پرچم های خط فرمان به دستور زیرین gcloud run deploy عبور کنید.

توجه: uvx --from دستوری را از بسته google-adk اجرا می کند. uvx یک محیط مجازی موقت ایجاد می کند، google-adk را در آن نصب می کند، دستور مشخص شده را اجرا می کند و سپس محیط را خراب می کند.

uvx --from google-adk \
adk deploy cloud_run \
    --project=$PROJECT_ID \
    --region=$REGION \
    --service_name=adk-agent-cr \
    --with_ui \
    ./multi_tool_agent \
    -- \
    --service-account=$SERVICE_ACCOUNT_ADDRESS_ADK \
    --allow-unauthenticated

سپس URL را به عنوان env var که در قسمت دوم این کد لبه استفاده خواهید کرد ذخیره کنید

AGENT_SERVICE_URL=$(gcloud run services describe adk-agent-cr --region $REGION --format 'value(status.url)')

حالا، عامل را امتحان کنید

URL سرویس را در مرورگر وب خود باز کنید و بپرسید، tell me about the weather in new york . شما باید پاسخی شبیه به "هوای نیویورک آفتابی با دمای 25 درجه سانتیگراد (77 درجه فارنهایت) ببینید."

در نهایت، نماینده را ایمن کنید

بیایید اکنون دسترسی ایمن به عامل را تضمین کنیم. در بخش بعدی، یک سرویس Cloud Run را مستقر خواهید کرد که یک تماس احراز هویت شده با این سرویس پشتیبان برقرار می کند.

gcloud run services remove-iam-policy-binding adk-agent-cr \
  --member="allUsers" \
  --role="roles/run.invoker" \
  --region=$REGION

6. یک gradio front-end راه اندازی کنید

در این مرحله، یک پیشانی درجه‌ای برای عامل ADK خود ایجاد می‌کنید

توجه: می توانید برنامه gradio را در همان سرویس عامل ADK داشته باشید. این کد لبه 2 سرویس جداگانه را برای نشان دادن نحوه برقراری سرویس احراز هویت برای تماس های سرویس در Cloud Run ارائه می دهد.

ابتدا یک برنامه در کنار پوشه multi_tool_agent ایجاد کنید

mkdir gradio-frontend && cd gradio-frontend

در مرحله بعد، یک فایل requirements.txt ایجاد کنید که حاوی موارد زیر باشد

gradio
requests
google-auth

اکنون یک فایل app.py ایجاد کنید

import gradio as gr
import requests
import json
import uuid
import os
import google.auth.transport.requests
import google.oauth2.id_token

# https://weather-time-service2-392295011265.us-west4.run.app
BASE_URL = os.environ.get("AGENT_SERVICE_URL")

# multi_tool_agent
APP_NAME = os.environ.get("AGENT_APP_NAME")

# Generate a unique user ID for each session of the Gradio app
USER_ID = f"gradio-user-{uuid.uuid4()}"

# API Endpoints
CREATE_SESSION_URL = f"{BASE_URL}/apps/{APP_NAME}/users/{USER_ID}/sessions"
RUN_SSE_URL = f"{BASE_URL}/run_sse"

def get_id_token():
    """Get an ID token to authenticate with the other Cloud Run service."""
    audience = BASE_URL
    request = google.auth.transport.requests.Request()
    id_token = google.oauth2.id_token.fetch_id_token(request, audience)
    return id_token

def create_session() -> str | None:
    """Creates a new session and returns the session ID."""
    try:
        id_token = get_id_token()
        headers = {"Authorization": f"Bearer {id_token}"}
        response = requests.post(CREATE_SESSION_URL, headers=headers)
        response.raise_for_status()
        return response.json().get("id")
    except Exception as e:
        print(f"Error creating session: {e}")
        return None

def query_agent(prompt: str):
    """Sends a prompt to the agent and returns the streamed response."""
    session_id = create_session()
    if not session_id:
        return "Error: Could not create a session."

    id_token = get_id_token()
    headers = {
        "Content-Type": "application/json",
        "Accept": "text/event-stream",
        "Authorization": f"Bearer {id_token}",
    }
    payload = {
        "app_name": APP_NAME,
        "user_id": USER_ID,
        "session_id": session_id,
        "new_message": {"role": "user", "parts": [{"text": prompt}]},
        "streaming": True
    }

    full_response = ""
    try:
        with requests.post(RUN_SSE_URL, headers=headers, json=payload, stream=True) as response:
            response.raise_for_status()
            for chunk in response.iter_lines():
                if chunk and chunk.decode('utf-8').startswith('data:'):
                    json_data = chunk.decode('utf-8')[len('data:'):].strip()
                    try:
                        data = json.loads(json_data)
                        text = data.get("content", {}).get("parts", [{}])[0].get("text", "")
                        if text:
                            full_response = text
                    except json.JSONDecodeError:
                        pass # Ignore chunks that are not valid JSON
        return full_response
    except requests.exceptions.RequestException as e:
        return f"An error occurred: {e}"

iface = gr.Interface(
    fn=query_agent,
    inputs=gr.Textbox(lines=2, placeholder="e.g., What's the weather in new york?"),
    outputs="text",
    title="Weather and Time Agent",
    description="Ask a question about the weather or time in a specific location.",
)

if __name__ == "__main__":
    iface.launch()

7. برنامه gradio خود را مستقر و آزمایش کنید

در این مرحله، اپلیکیشن gradio front end را در Cloud Run مستقر خواهید کرد.

مطمئن شوید که در دایرکتوری برنامه gradio هستید.

pwd

شما باید codelab-gradio-adk/gradio-frontend را ببینید

اکنون برنامه gradio خود را مستقر کنید.

توجه: اگرچه این سرویس پیش‌نمایش درجهیو یک وب‌سایت در دسترس عموم است، اما سرویس پشتیبان نیاز به احراز هویت دارد. برای نشان دادن اینکه چرا ممکن است بخواهید این کار را انجام دهید، می توانید احراز هویت کاربر (به عنوان مثال Firebase Auth) را به این سرویس frontend اضافه کنید و سپس فقط به کاربرانی که وارد سیستم شده اند اجازه دهید با سرویس Backend تماس بگیرند.

gcloud run deploy my-adk-gradio-frontend \
--source . \
--region $REGION \
--allow-unauthenticated \
--set-env-vars AGENT_SERVICE_URL=$AGENT_SERVICE_URL,AGENT_APP_NAME=$AGENT_APP_NAME \
--service-account=$SERVICE_ACCOUNT_ADDRESS_GRADIO

هنگامی که مستقر شد، بپرسید what's the weather in new york? و باید پاسخی شبیه به The weather in New York is sunny with a temperature of 25 degrees Celsius (77 degrees Fahrenheit).

8. تبریک!

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

توصیه می‌کنیم اسناد مربوط به میزبانی برنامه‌های هوش مصنوعی و اسناد عامل را بررسی کنید.

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

نحوه استقرار یک عامل ADK در Cloud Run
نحوه استقرار یک برنامه gradio در Cloud Run
نحوه برقراری تماس های تایید شده سرویس به سرویس در Cloud Run

9. پاکسازی کنید

برای جلوگیری از هزینه‌های سهوی، به عنوان مثال، اگر سرویس‌های Cloud Run به طور سهوی بیش‌تر از تخصیص فراخوانی ماهانه Cloud Run در ردیف رایگان فراخوانی می‌شوند، می‌توانید سرویس Cloud Run را که در مرحله 6 ایجاد کرده‌اید حذف کنید.

برای حذف خدمات Cloud Run، به کنسول Cloud Run Cloud در https://console.cloud.google.com/run بروید و خدمات my-adk-gradio-frontend و adk-agent-cr حذف کنید.

برای حذف کل پروژه، به Manage Resources بروید، پروژه ای را که در مرحله 2 ایجاد کردید انتخاب کنید و Delete را انتخاب کنید. اگر پروژه را حذف کنید، باید پروژه ها را در Cloud SDK خود تغییر دهید. با اجرای gcloud projects list می توانید لیست تمام پروژه های موجود را مشاهده کنید.