یک عامل آگاه به مدیریت سازمانی با MCP و Cloud Run مستقر کنید

۱. مقدمه

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

(شما می‌توانید بخش اول این مجموعه را بخوانید که نحوه ایجاد پایه داده‌ها با ثبت یک نوع جنبه کاتالوگ دانش، اعمال جنبه‌ها به جداول BigQuery و آزمایش قوانین به صورت محلی از طریق AGY CLI را پوشش می‌دهد. 👉 بخش ۱ را بخوانید .)

با این حال، آزمایش در یک رابط خط فرمان محلی (CLI) فقط آغاز کار است. برای گسترش این قابلیت به کل شرکت خود، به امنیت متمرکز، اتصالات استاندارد ابزار هوش مصنوعی و یک چارچوب کاربردی مناسب برای هماهنگ کردن منطق عامل و ارائه یک رابط چت آشنا نیاز دارید.

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

.

وقتی کاربر با رابط کاربری ADK تعامل می‌کند، توالی زیر رخ می‌دهد:

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

• نحوه استفاده از پروتکل مدل زمینه (MCP) برای استانداردسازی نحوه تعامل عوامل هوش مصنوعی با داده‌های Google Cloud.
• نحوه اتصال عامل ADK به سرور MCP کاتالوگ دانش تحت مدیریت گوگل.
• چگونه قوانین مدیریتی خود را به صورت پویا از مهارت عامل مشترک بارگذاری کنید.
• چگونه عامل خود را در Cloud Run مستقر کنید و محیط وب داخلی ADK را اجرا کنید.

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

• یک پروژه گوگل کلود با قابلیت پرداخت.
• دسترسی به پوسته ابری گوگل.
• آشنایی اولیه با Cloud Run، حساب‌های سرویس IAM و پایتون.
• مجموعه داده‌های BigQuery و جنبه‌های کاتالوگ دانش که در بخش ۱ ایجاد شدند. (اگر آنها را حذف کرده‌اید نگران نباشید؛ ما یک اسکریپت سریع برای بازسازی آنها در زیر ارائه می‌دهیم!)

مفاهیم کلیدی

• پروتکل زمینه مدل (MCP): MCP را به عنوان یک "کابل USB-C جهانی" برای عوامل هوش مصنوعی در نظر بگیرید. MCP به جای نوشتن کد یکپارچه‌سازی API سفارشی برای هر مدل هوش مصنوعی، یک روش استاندارد برای هوش مصنوعی فراهم می‌کند تا به طور ایمن به ابزارهای داده سازمانی شما (مانند کاتالوگ دانش و BigQuery) متصل شود.
• کیت توسعه عامل (ADK): یک چارچوب انعطاف‌پذیر و متن‌باز توسط گوگل که برای ساده‌سازی توسعه عامل‌های هوش مصنوعی از ابتدا تا انتها طراحی شده است. این کیت اصول مهندسی نرم‌افزار را در ایجاد عامل اعمال می‌کند و به شما امکان می‌دهد ابزارهای پیچیده را هماهنگ کنید، وضعیت را مدیریت کنید و به راحتی یک رابط کاربری توسعه‌دهنده داخلی را برای آزمایش و استقرار راه‌اندازی کنید.
• پلتفرم عامل سازمانی جمینی (GEAP) : محیط میزبانی و هماهنگی در سطح سازمانی برای استقرار عامل‌های هوش مصنوعی در فضای ابری گوگل.

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

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

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

از کنسول گوگل کلود ، روی آیکون Cloud Shell در نوار ابزار بالا سمت راست کلیک کنید:

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

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

مقداردهی اولیه محیط

Cloud Shell را باز کنید و متغیرهای پروژه خود را تنظیم کنید تا مطمئن شوید که همه دستورات زیرساخت صحیح را هدف قرار می‌دهند.

export PROJECT_ID=$(gcloud config get-value project)
gcloud config set project $PROJECT_ID
export REGION="us-central1"

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

حداقل مجموعه APIهای Google Cloud مورد نیاز برای مدیریت پایگاه داده خود، اجرای مدل‌های Vertex AI و میزبانی ADK Agent در Cloud Run را فعال کنید.

gcloud services enable \
    dataplex.googleapis.com \
    bigquery.googleapis.com \
    aiplatform.googleapis.com \
    run.googleapis.com \
    artifactregistry.googleapis.com \
    cloudbuild.googleapis.com

ایست بازرسی: از سرگیری یا بازسازی؟

از آنجایی که این بخش ۲ است، نماینده شما برای عملکرد خود به داده‌های مدیریت‌شده از بخش ۱ نیاز دارد. لطفاً مسیر خود را انتخاب کنید:

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

عالی! به دایرکتوری کاری بروید و آماده ادامه هستید.

cd ~/devrel-demos/data-analytics/governance-context

مسیر ب: از بخش ۱ صرف نظر کردم یا منابعم را حذف کردم (پاکسازی شد)

مشکلی نیست! ما یک بلوک فرمان "Fast-Track" در زیر ارائه داده‌ایم. این بلوک به طور خودکار دریاچه داده BigQuery را بازسازی می‌کند، نوع جنبه را ثبت می‌کند و ابرداده‌های مدیریتی را دقیقاً مانند آنچه در بخش ۱ انجام دادیم، اعمال می‌کند.

# 1. Clone the repo and navigate to the working directory
git clone --depth 1 --filter=blob:none --sparse https://github.com/GoogleCloudPlatform/devrel-demos.git
cd devrel-demos
git sparse-checkout set data-analytics/governance-context
cd data-analytics/governance-context

# 2. Rebuild the BigQuery datasets and tables
chmod +x ./setup_bq_tables.sh
./setup_bq_tables.sh

# 3. Register the Knowledge Catalog aspect type
gcloud dataplex aspect-types create official-data-product-spec \
    --location="${REGION}" \
    --project="${PROJECT_ID}" \
    --metadata-template-file-name="aspect_template.json"

# 4. Generate and apply aspects (governance rules)
chmod +x ./generate_payloads.sh ./apply_governance.sh
./generate_payloads.sh
./apply_governance.sh

۳. صفحه کنترل داده متمرکز (MCP مدیریت‌شده)

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

با استفاده از این نقطه پایانی مدیریت‌شده، به موارد زیر دست می‌یابیم:

1. بدون نیاز به نگهداری: نیازی به مدیریت کانتینرها، مقیاس‌بندی یا وصله‌بندی برای سرور MCP نیست.
2. استانداردسازی: عامل با استفاده از پروتکل Model Context (انتقال SSE) به یک نقطه پایانی استاندارد و امن Google API متصل می‌شود.
3. دامنه کنترل‌شده: سرور MCP فقط ابزارهای فراداده ضروری ( search_entries ، lookup_context ، lookup_entry ) را در معرض نمایش قرار می‌دهد و یک حلقه استدلال فقط خواندنی و مبتنی بر مدیریت را اجرا می‌کند.

سرور MCP کاتالوگ دانش تحت مدیریت گوگل از طریق URL امن زیر قابل دسترسی است:

https://dataplex.googleapis.com/mcp

از آنجا که این یک API گوگل شخص ثالث است، عامل باید با استفاده از یک توکن دسترسی استاندارد Google Cloud OAuth2 به جای یک توکن ID، احراز هویت کند. ما این احراز هویت را به طور خودکار در کد برنامه خود مدیریت خواهیم کرد.

۴. ساخت بک‌اند عامل با ADK

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

ما از کیت توسعه عامل (ADK) گوگل استفاده خواهیم کرد. ADK یک چارچوب کد-اول است که به طور خودکار منطق عامل شما را در یک بک‌اند FastAPI قرار می‌دهد و یک رابط وب داخلی برای آزمایش فوری فراهم می‌کند.

کد عامل را در ویرایشگر Cloud Shell باز کنید

به جای اینکه کل فایل را در ترمینال بارگذاری کنیم، بیایید آن را در ویرایشگر Cloud Shell باز کنیم تا بتوانید به راحتی کد را بررسی، ویرایش و درک کنید.

دستور زیر را در ترمینال اجرا کنید و به ساختار کد در ویرایشگر نگاه کنید. این برنامه با استفاده از کیت توسعه عامل گوگل (ADK) ساخته شده است:

cd ~/devrel-demos/data-analytics/governance-context/mcp_server

# Copy the governance skill directory inside the application bundle so it packages during Cloud Run deployment
mkdir -p skills
cp -r ../.agents/skills/knowledge-catalog-governance skills/

cloudshell edit agent.py

(نکته: agent.py در بالا حاوی کد تکراری برای مدیریت احراز هویت Google Cloud OAuth2 و به‌روزرسانی توکن است، که تضمین می‌کند عامل می‌تواند به طور ایمن با API کاتالوگ دانش مدیریت‌شده توسط گوگل ارتباط برقرار کند.)

۱. بارگذاری مهارت‌های بومی

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

• فراداده سطح ۱: عامل فقط نام و توضیحات مهارت را در هنگام راه‌اندازی بارگذاری می‌کند. این زمینه حداقلی به LLM اجازه می‌دهد تا بدون مصرف مقادیر زیادی توکن از قبل، زمان استفاده از مهارت را تشخیص دهد.
• دستورالعمل‌های سطح ۲: مجموعه کامل دستورالعمل‌های درون SKILL.md تنها زمانی که مدل تشخیص دهد مرتبط است، به صورت پویا در زمان اجرا فراخوانی می‌شود.

base_dir = Path(__file__).parent
governance_skill = load_skill_from_dir(
    base_dir / "skills" / "knowledge-catalog-governance"
)

# Bundle the skill and MCP tools together into a SkillToolset
governance_skill_toolset = skill_toolset.SkillToolset(
    skills=[governance_skill],
    additional_tools=[tools]
)

۲. هماهنگ‌سازی عامل‌ها

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

• governance_researcher: مجهز به governance_skill_toolset و tools Knowledge Catalog MCP است. این ابزار بررسی می‌کند که آیا پرس‌وجو در محدوده‌ی data catalog و compliance قرار می‌گیرد یا خیر، سپس با استفاده از متغیرهای محیطی تزریق‌شده به دستورالعمل‌های سیستمی خود، Knowledge Catalog را پرس‌وجو می‌کند.
• compliance_formatter: مسئول ترجمه نتایج جستجوی خام فراداده JSON به یک پاسخ تمیز، یا توضیح دقیق مرزهای دامنه در صورت خارج از محدوده بودن درخواست است.

# 1. Researcher Agent (has access to the encapsulated SkillToolset)
governance_researcher = LlmAgent(
    name="governance_researcher",
    model=model_name,
    description="Dynamically interprets metadata schema (Booleans/Enums) and searches for assets using strict syntax.",
    instruction=f"""
    You are a governance researcher. Your job is to verify Knowledge Catalog metadata rules and find compliant assets for the user's query.
    
    YOUR ACTIVE ENVIRONMENT CONTEXT:
    - Google Cloud Project ID: {project_id}
    - Location (Region): {location}

    YOUR WORKFLOW:
    1. First, check if the user query is related to data analytics assets, database tables, or data compliance.
       - If YES: Call `load_skill` with `name="knowledge-catalog-governance"` to load the rules, then use search/lookup tools to locate a certified compliant table.
       - If NO (e.g., general chit-chat, unrelated tasks): Skip skill loading and output a JSON object indicating it is out of scope:
         {"error": "out_of_scope", "message": "The query does not pertain to data catalog search or governance compliance."}
    2. Populate the required projectId and location parameters in tool calls with the active environment parameters.
    3. Return the verified table's metadata in JSON format as your final research output.
    """,
    tools=[governance_skill_toolset, tools],
    output_key="research_data"
)

# 2. Formatter Agent (formats the output or explains out-of-scope errors)
compliance_formatter = LlmAgent(
    name="compliance_formatter",
    model=model_name,
    description="Formats the JSON research data into a helpful response for the user.",
    instruction="""
    You are the **Intelligent Data Governance Specialist**.
    Your job is to explain the findings of the governance research clearly to the user.

    **YOUR GOAL:**
    1. If the researcher found a matching table (valid JSON with table metadata):
       - Explain the logical connection between the User's Request, the Governance Schema (translated criteria), and the Recommended Table.
       - Use the following RESPONSE TEMPLATE:
         - **Analysis:** "I analyzed the metadata schema and translated your request into the following technical criteria:..."
         - **Recommendation:** "Based on this, I recommend the following table:"
           - **Table:** [Insert Table Name]
           - **Description:** [Insert Table Description]
         - **Verification:** "This asset is a verified match because: [Explain the verification details]."
    2. If the researcher returned an 'out_of_scope' error or no matching tables were found:
       - Apologize politely and explain that no data asset currently matches the strict governance criteria defined in `official-data-product-spec`.
       - Clearly state what domain of questions this agent is certified to answer (e.g., Data Catalog Search and Data Governance compliance).
    """
)

# 3. Orchestrated Workflow (Exported as root_agent)
root_agent = SequentialAgent(
    name="governance_workflow",
    description="Workflow to learn metadata rules, search with strict syntax, and recommend assets.",
    sub_agents=[
        governance_researcher,
        compliance_formatter,
    ]
)

پیکربندی متغیرهای زمان اجرا

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

دستور زیر را برای تولید فایل .env اجرا کنید. توجه داشته باشید که MCP_SERVER_URL مستقیماً به نقطه پایانی API کاتالوگ دانش مدیریت‌شده توسط گوگل اشاره می‌کند:

export MCP_SERVER_URL="https://dataplex.googleapis.com/mcp"

echo MCP_SERVER_URL=$MCP_SERVER_URL > .env
echo GOOGLE_GENAI_USE_VERTEXAI=1 >> .env
echo GOOGLE_CLOUD_PROJECT=$PROJECT_ID >> .env
echo GOOGLE_CLOUD_LOCATION=$REGION >> .env

۵. اجرا و آزمایش عامل به صورت محلی

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

هنگام اجرای محلی در Cloud Shell، عامل به طور خودکار از اعتبارنامه‌های فعال کاربر Google Cloud شما استفاده می‌کند، بنابراین از قبل مجوزهای لازم برای دسترسی به Vertex AI و Knowledge Catalog را دارد.

1. به دایرکتوری mcp_server بروید، یک محیط مجازی ایجاد کنید و وابستگی‌ها را نصب کنید:

cd ~/devrel-demos/data-analytics/governance-context/mcp_server

# Create a virtual environment using uv
uv venv
source .venv/bin/activate

# Install the dependencies listed in requirements.txt
uv pip install -r requirements.txt

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

adk run .

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

I need the Q1 revenue summary for our internal board meeting.

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

4. برای خروج از جلسه تعاملی، exit یا quit را تایپ کنید (یا Ctrl+C را فشار دهید). پس از خروج، می‌توانید محیط مجازی را غیرفعال کنید:

deactivate

۶. عامل را به محیط عملیاتی منتقل کنید

اکنون که عامل را به صورت محلی تأیید کرده‌اید، آماده‌اید تا آن را برای استفاده در محیط عملیاتی، در Google Cloud مستقر کنید.

ایجاد حساب کاربری سرویس

برای امنیت، عامل مستقر شده نباید تحت اعتبارنامه‌های شخصی شما اجرا شود. ما یک هویت جداگانه ( knowledge-catalog-agent-sa ) برای عامل ایجاد خواهیم کرد که به اصل حداقل امتیاز پایبند است.

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

export AGENT_SA=knowledge-catalog-agent-sa
export AGENT_SERVICE_ACCOUNT="${AGENT_SA}@${PROJECT_ID}.iam.gserviceaccount.com"

gcloud iam service-accounts create ${AGENT_SA} \
    --display-name="Service Account for Knowledge Catalog Agent"

اعطای مجوزها

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

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

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$AGENT_SERVICE_ACCOUNT" \
  --role="roles/dataplex.catalogAdmin"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$AGENT_SERVICE_ACCOUNT" \
  --role="roles/bigquery.dataViewer"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$AGENT_SERVICE_ACCOUNT" \
  --role="roles/mcp.toolUser"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$AGENT_SERVICE_ACCOUNT" \
  --role="roles/viewer"

استقرار در Cloud Run

در نهایت، عامل را در Cloud Run مستقر می‌کنیم. دستور زیر تصویر کانتینر را با استفاده از Dockerfile در دایرکتوری فعلی شما می‌سازد، آن را در Artifact Registry آپلود می‌کند و در Cloud Run مستقر می‌کند. تکمیل این فرآیند ممکن است ۱ تا ۳ دقیقه طول بکشد.

gcloud run deploy knowledge-catalog-agent \
  --source . \
  --project=$PROJECT_ID \
  --region=$REGION \
  --service-account=$AGENT_SERVICE_ACCOUNT \
  --allow-unauthenticated \
  --clear-base-image \
  --labels created-by=adk

پس از اتمام این دستور، یک URL سرویس (مثلاً https://knowledge-catalog-agent-xyz.run.app ) نمایش داده می‌شود. برای باز کردن رابط چت GenAI کاملاً مدیریت‌شده، روی آن لینک کلیک کنید.

۷. عامل زنده را آزمایش کنید

حالا که عامل شما فعال است، بیایید سناریوهای مدیریت را آزمایش کنیم. منطق کار یکسان است، اما اکنون شما با ADK Web Playground مستقر شده در تعامل هستید که وضعیت داخلی و اجرای ابزارها را تجسم می‌کند.

آدرس اینترنتی سرویسی که در مرحله قبل ایجاد کردید (مثلاً https://knowledge-catalog-agent-xyz.run.app) را در مرورگر خود باز کنید. عبارت زیر را در آن جایگذاری کنید:

"My dashboard needs to show what's happening right now with our ad spend. I can't wait for the overnight load. What do you recommend?"

فرآیند استدلال عامل را در رابط کاربری توسعه‌دهنده مشاهده کنید:

1. تشخیص قصد: عامل «همین الان» و «بی‌صبرانه منتظر یک شبه هستم» را تجزیه و تحلیل می‌کند.
2. جستجوی فراداده: ابزار MCP را با پرس‌وجوی search_entries فراخوانی می‌کند: [PROJECT_ID].us-central1.official-data-product-spec.update_frequency=REALTIME_STREAMING
3. انتخاب: مشخص می‌کند که جدول mkt_realtime_campaign_performance این معیارها را برآورده می‌کند.
4. پاسخ: نماینده، میز زمان واقعی را توصیه می‌کند.

چرا این مهم است:

بدون این فراداده مدیریتی، یک LLM احتمالاً جدول fin_monthly_closing_internal را صرفاً به این دلیل که ستونی به نام "ad_spend" دارد، توصیه می‌کند، بدون توجه به این واقعیت که داده‌ها ۲۴ ساعت قدمت دارند. زمینه فراداده شما از یک خطای تجاری جلوگیری کرد.

همچنین می‌توانید اعلان «جلسه هیئت مدیره» را آزمایش کنید تا ببینید که چگونه عامل بر اساس جنبه Data Product Tier به جداول مختلف منتقل می‌شود:

"We are preparing the deck for an internal Board of Directors meeting next week. I need the numbers to be absolutely finalized, trustworthy, and kept strictly confidential. Which table is safe to use?"

۸. تمیز کردن

برای جلوگیری از تحمیل هزینه به حساب Google Cloud خود، این مراحل را دنبال کنید تا تمام زیرساخت‌های ایجاد شده در این codelab از بین بروند.

دریاچه داده را نابود کنید

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

cd ~/devrel-demos/data-analytics/governance-context
chmod +x ./cleanup_data_lake.sh
./cleanup_data_lake.sh

سرویس‌های Cloud Run را حذف کنید

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

gcloud run services delete knowledge-catalog-agent --region=$REGION --quiet

پاکسازی مصنوعات ساخت و ذخیره‌سازی مرحله‌ای

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

مخزن رجیستری Artifact و سطل مرحله‌بندی Cloud Storage را حذف کنید:

# Delete the repository used for the agent build
gcloud artifacts repositories delete cloud-run-source-deploy \
    --location=$REGION \
    --quiet

# Delete the staging bucket created by Cloud Run source deploy
gcloud storage rm --recursive gs://run-sources-${PROJECT_ID}-${REGION}

حذف هویت و مجوزها

ابتدا محدودیت‌های سیاست IAM را حذف کنید، سپس حساب‌های سرویس را حذف کنید.

# Remove IAM roles granted to the Agent Service Account
gcloud projects remove-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$AGENT_SERVICE_ACCOUNT" \
  --role="roles/aiplatform.user" --quiet

gcloud projects remove-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$AGENT_SERVICE_ACCOUNT" \
  --role="roles/dataplex.catalogViewer" --quiet

gcloud projects remove-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$AGENT_SERVICE_ACCOUNT" \
  --role="roles/mcp.toolUser" --quiet

gcloud projects remove-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$AGENT_SERVICE_ACCOUNT" \
  --role="roles/bigquery.dataViewer" --quiet

# Delete the Service Account
gcloud iam service-accounts delete $AGENT_SERVICE_ACCOUNT --quiet

پیکربندی محلی را حذف کنید

در نهایت، فایل‌های پیکربندی محلی و متغیرهای محیطی را در Cloud Shell پاک‌سازی کنید.

# Uninstall the AGY CLI plugin
agy plugin uninstall dataplex

# Remove local repository files and unset variables
cd ~
rm -rf ~/devrel-demos
unset MCP_SERVER_URL
unset AGENT_SERVICE_ACCOUNT

۹. تبریک می‌گویم!

شما با موفقیت یک عامل GenAI آگاه از مدیریت و از ابتدا تا انتها را مستقر کرده‌اید.

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

نکات کلیدی

• هوش مصنوعی قطعی از طریق فراداده: به جای تکیه بر LLM برای حدس زدن جدول صحیح بر اساس نام ستون‌ها، شما یک حلقه استدلال دقیق را با استفاده از سرور MCP کاتالوگ دانش تحت مدیریت گوگل اعمال کردید و مدل را مجبور کردید قبل از توصیه جداول، گواهینامه‌های داده‌ها را تأیید کند.
• معماری جدا شده: عامل frontend نیازی به منطق پایگاه داده ندارد؛ فقط باید از طریق استاندارد MCP ارتباط برقرار کند. این بدان معناست که می‌توانید هر مدل هوش مصنوعی یا کلاینت آینده را به همان backend تحت کنترل متصل کنید.
• تفکیک وظایف: شما با جداسازی هویت‌های IAM، اصل حداقل امتیاز را اعمال کرده‌اید. عامل ADK که با کاربر در ارتباط است، با مجوزهایی محدود به فراخوانی مدل و مسیریابی API عمل می‌کند.
• هماهنگ‌سازی عامل با کدنویسی: شما از کیت توسعه عامل گوگل (ADK) برای قرار دادن فوری منطق عامل پایتون خود در یک بک‌اند FastAPI مقیاس‌پذیر استفاده کردید و از رابط کاربری توسعه‌دهنده داخلی آن برای تجسم و اشکال‌زدایی اجراهای ابزار داخلی عامل استفاده کردید.

بعدش چی؟

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