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

پایگاه داده به عنوان یک ابزار: Agentic RAG با ADK، جعبه ابزار MCP و Cloud SQL

۱. مقدمه

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

این آزمایشگاه کد رویکرد متفاوتی را نشان می‌دهد. شما ابزارهای پایگاه داده خود را در یک فایل YAML تعریف می‌کنید - کوئری‌های استاندارد SQL، جستجوی شباهت برداری، حتی تولید خودکار جاسازی - و MCP Toolbox for Databases تمام عملیات پایگاه داده را به عنوان یک سرور MCP مدیریت می‌کند. کد عامل شما مینیمال باقی می‌ماند: ابزارها را بارگذاری کنید، بگذارید Gemini تصمیم بگیرد کدام یک را فراخوانی کند.

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

یک دستیار هوشمند برای تابلوی مشاغل برای "TechJobs" - یک عامل ADK که توسط Gemini پشتیبانی می‌شود و به توسعه‌دهندگان کمک می‌کند تا با استفاده از فیلترهای استاندارد (نقش، پشته فناوری) فهرست مشاغل فنی را مرور کنند و از طریق توضیحات زبان طبیعی مانند "من یک کار از راه دور با کار بر روی ربات‌های چت هوش مصنوعی می‌خواهم" مشاغل را کشف کنند. این عامل از طریق MCP Toolbox for Databases، که تمام دسترسی به پایگاه داده - از جمله تولید خودکار جاسازی برای جستجوی برداری - را مدیریت می‌کند، از یک پایگاه داده Cloud SQL PostgreSQL می‌خواند و در آن می‌نویسد. در نهایت، هم Toolbox و هم عامل بر روی Cloud Run اجرا می‌شوند.

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

چگونه MCP (پروتکل زمینه مدل) دسترسی به ابزار را برای عوامل هوش مصنوعی استاندارد می‌کند، و چگونه MCP Toolbox for Databases این را در عملیات پایگاه داده اعمال می‌کند
جعبه ابزار MCP برای پایگاه‌های داده را به عنوان میان‌افزار بین یک عامل ADK و Cloud SQL PostgreSQL تنظیم کنید.
ابزارهای پایگاه داده را به صورت اعلانی در tools.yaml تعریف کنید - هیچ کد پایگاه داده‌ای در عامل شما وجود ندارد
با استفاده از ToolboxToolset یک عامل ADK بسازید که ابزارها را از یک سرور Toolbox در حال اجرا بارگیری کند.
با استفاده از embedding() داخلی Cloud SQL، جاسازی‌های برداری ایجاد کنید و جستجوی معنایی را با pgvector فعال کنید.
از ویژگی valueFromParam برای دریافت خودکار بردار در عملیات نوشتن استفاده کنید
سرور Toolbox و ADK agent را روی Cloud Run مستقر کنید.

پیش‌نیازها

یک حساب Google Cloud با یک حساب پرداخت آزمایشی
آشنایی اولیه با پایتون و SQL
تجربه قبلی با Cloud Database و ADK مفید خواهد بود.

۲. محیط خود را آماده کنید

این مرحله محیط Cloud Shell شما را آماده می‌کند، پروژه Google Cloud شما را پیکربندی می‌کند و مخزن مرجع را کلون می‌کند.

پوسته ابری را باز کنید

Cloud Shell را در مرورگر خود باز کنید. Cloud Shell یک محیط از پیش پیکربندی شده با تمام ابزارهای مورد نیاز برای این آزمایشگاه کد را فراهم می‌کند. در صورت درخواست، روی تأیید (Authorize) کلیک کنید.

سپس روی « مشاهده » -> « ترمینال » کلیک کنید تا ترمینال باز شود. رابط کاربری شما باید شبیه به این باشد.

۸۶۳۰۷fac5da2f077.png

این رابط اصلی ما خواهد بود، IDE در بالا، ترمینال در پایین

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

دایرکتوری کاری خود را ایجاد کنید. تمام کدهایی که در این آزمایشگاه کد می‌نویسید، در اینجا قرار دارند:

mkdir -p ~/build-agent-adk-toolbox-cloudsql
cloudshell workspace ~/build-agent-adk-toolbox-cloudsql && cd ~/build-agent-adk-toolbox-cloudsql

پس از آن، بیایید چندین دایرکتوری را برای مدیریت مواردی مانند بارگذاری اسکریپت‌ها و گزارش‌ها آماده کنیم.

mkdir -p ~/build-agent-adk-toolbox-cloudsql/scripts
mkdir -p ~/build-agent-adk-toolbox-cloudsql/logs

پروژه گوگل کلود خود را راه‌اندازی کنید

فایل .env را با متغیرهای مکان ایجاد کنید:

# For Vertex AI / Gemini API calls
echo "GOOGLE_CLOUD_LOCATION=global" > .env
# For Cloud SQL, Cloud Run, Artifact Registry
echo "REGION=us-central1" >> .env

مهم! مرحله زیر برای کمک به راه‌اندازی سریع پروژه Google Cloud که به یک حساب Trial Billing (strict) متصل است، ارائه شده است. اگر ترجیح می‌دهید از پروژه قبلی خود استفاده کنید، می‌توانید مرحله زیر را نادیده بگیرید و به جای آن مرحله زیر را انجام دهید:

نام پروژه خود را به عنوان متغیر GOOGLE_CLOUD_PROJECT در فایل .env اضافه کنید.
پروژه خود را در ترمینال با استفاده از gcloud config set project your-project-id فعال کنید.

پس از آن، می‌توانید مستقیماً به بخش فعال‌سازی API بروید.

اگر در این مورد مطمئن نیستید، بخش زیر را ادامه دهید

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

curl -sL https://raw.githubusercontent.com/alphinside/cloud-trial-project-setup/main/setup_verify_trial_project.sh -o setup_verify_trial_project.sh

اسکریپت را اجرا کنید. این اسکریپت حساب کاربری آزمایشی شما را تأیید می‌کند، یک پروژه جدید ایجاد می‌کند (یا یک پروژه موجود را تأیید می‌کند)، شناسه پروژه شما را در یک فایل .env در دایرکتوری فعلی ذخیره می‌کند و پروژه فعال را در gcloud تنظیم می‌کند.

bash setup_verify_trial_project.sh && source .env

اسکریپت:

تأیید کنید که یک حساب پرداخت آزمایشی فعال دارید
بررسی وجود یک پروژه موجود در .env (در صورت وجود)
یک پروژه جدید ایجاد کنید یا از پروژه موجود دوباره استفاده کنید
حساب پرداخت آزمایشی را به پروژه خود پیوند دهید
شناسه پروژه را در .env ذخیره کنید
پروژه را به عنوان پروژه فعال gcloud تنظیم کنید

با بررسی متن زرد رنگ کنار دایرکتوری کاری خود در اعلان ترمینال Cloud Shell، مطمئن شوید که پروژه به درستی تنظیم شده است. باید شناسه پروژه شما نمایش داده شود.

فعال‌سازی API مورد نیاز

در مرحله بعد، باید چندین API را برای محصولی که با آن تعامل خواهیم داشت، فعال کنیم:

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

رابط برنامه‌نویسی کاربردی هوش مصنوعی ورتکس ( aiplatform.googleapis.com ) — عامل شما از مدل‌های Gemini استفاده می‌کند و تول‌باکس از رابط برنامه‌نویسی کاربردی جاسازی برای جستجوی برداری استفاده می‌کند.
رابط برنامه‌نویسی کاربردی مدیریت SQL ابری ( sqladmin.googleapis.com ) - شما یک نمونه PostgreSQL را تهیه و مدیریت می‌کنید.
رابط برنامه‌نویسی کاربردی موتور محاسبات (compute Engine API ) ( compute.googleapis.com ) — برای ایجاد نمونه‌های Cloud SQL مورد نیاز است.
Cloud Run، Cloud Build، Artifact Registry - که در مرحله استقرار بعداً در این آزمایشگاه کد استفاده می‌شود

۳. آماده‌سازی اسکریپت‌ها برای مقداردهی اولیه پایگاه داده

این مرحله ایجاد نمونه Cloud SQL را آغاز می‌کند و یک اسکریپت راه‌اندازی خودکار را اجرا می‌کند که منتظر آماده شدن نمونه می‌ماند، سپس پایگاه داده را ایجاد می‌کند، فهرست مشاغل را به آن اضافه می‌کند و جاسازی‌ها را ایجاد می‌کند - همه اینها در یک عملیات.

ابتدا، بیایید رمز عبور پایگاه داده را به فایل .env خود اضافه کنیم و آن را مجدداً بارگذاری کنیم:

echo "DB_PASSWORD=techjobs-pwd" >> .env
echo "DB_INSTANCE=jobs-instance" >> .env
echo "DB_NAME=jobs_db" >> .env
source .env

ایجاد اسکریپت Bash برای مثال و ایجاد پایگاه داده

سپس، اسکریپت scripts/setup_database.sh را با دستور زیر ایجاد کنید

mkdir -p ~/build-agent-adk-toolbox-cloudsql/scripts
cloudshell edit scripts/setup_database.sh

سپس، کد زیر را در فایل scripts/setup_database.sh کپی کنید.

#!/bin/bash
set -e
source .env

echo "================================================"
echo "Database Setup"
echo "================================================"
echo ""

# Step 1: Create Cloud SQL instance
echo "[1/5] Creating Cloud SQL instance..."

# Check if instance already exists
if gcloud sql instances describe "$DB_INSTANCE" --quiet >/dev/null 2>&1; then
    echo "      Instance already exists"
else
    echo "      Creating instance (takes 5-10 minutes)..."
    gcloud sql instances create "$DB_INSTANCE" \
        --database-version=POSTGRES_17 \
        --tier=db-custom-1-3840 \
        --edition=ENTERPRISE \
        --region="$REGION" \
        --root-password="$DB_PASSWORD" \
        --enable-google-ml-integration \
        --database-flags cloudsql.enable_google_ml_integration=on \
        --quiet
fi
echo "      ✓ Instance ready"
echo ""

# Step 2: Verify instance is ready
echo "[2/5] Verifying instance state..."

STATE=$(gcloud sql instances describe "$DB_INSTANCE" --format='value(state)')

if [ "$STATE" != "RUNNABLE" ]; then
    echo "ERROR: Instance not ready (state: $STATE)"
    exit 1
fi
echo "      ✓ Instance is RUNNABLE"
echo ""

# Step 3: Grant IAM permissions
echo "[3/5] Granting Vertex AI permissions..."

SERVICE_ACCOUNT=$(gcloud sql instances describe "$DB_INSTANCE" \
    --format='value(serviceAccountEmailAddress)')

if [ -z "$SERVICE_ACCOUNT" ]; then
    echo "ERROR: Could not retrieve service account"
    exit 1
fi

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

echo "      ✓ Permissions granted"
echo ""

# Step 4: Create database
echo "[4/5] Creating database..."

# Check if database already exists
if gcloud sql databases describe "$DB_NAME" \
    --instance="$DB_INSTANCE" --quiet >/dev/null 2>&1; then
    echo "      Database already exists"
else
    gcloud sql databases create "$DB_NAME" \
        --instance="$DB_INSTANCE" \
        --quiet
fi

echo "      ✓ Database '$DB_NAME' ready"
echo ""

# Step 5: Seed database and generate embeddings
echo "[5/5] Seeding database and generating embeddings..."

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SETUP_SCRIPT="${SCRIPT_DIR}/setup_jobs_db.py"

if [ ! -f "$SETUP_SCRIPT" ]; then
    echo "ERROR: Setup script not found: $SETUP_SCRIPT"
    exit 1
fi

uv run "$SETUP_SCRIPT"

echo ""
echo "================================================"
echo "Setup complete!"
echo "================================================"
echo ""

ایجاد اسکریپت پایتون برای ایجاد پایگاه داده

پس از آن، فایل پایتون اسکریپت seeding به نام scripts/setup_jobs_db.py با استفاده از دستور زیر ایجاد کنید.

cloudshell edit scripts/setup_jobs_db.py

سپس، کد زیر را در فایل scripts/setup_jobs_db.py کپی کنید.

import os
import sys
from pathlib import Path
from dotenv import load_dotenv
from google.cloud.sql.connector import Connector
import pg8000
import time

# Load environment variables from .env file
env_path = Path(__file__).parent.parent / '.env'
load_dotenv(env_path)
EMBEDDING_MODEL='gemini-embedding-001'

# Verify required environment variables
required_vars = ['GOOGLE_CLOUD_PROJECT', 'REGION', 'DB_PASSWORD']
missing_vars = [var for var in required_vars if not os.environ.get(var)]

if missing_vars:
    print(f"ERROR: Missing required environment variables: {', '.join(missing_vars)}", file=sys.stderr)
    print(f"", file=sys.stderr)
    print(f"Expected .env file location: {env_path}", file=sys.stderr)
    if not env_path.exists():
        print(f"✗ File not found at that location", file=sys.stderr)
    else:
        print(f"✓ File exists but is missing the variables above", file=sys.stderr)
    print(f"", file=sys.stderr)
    print(f"Make sure your .env file contains:", file=sys.stderr)
    for var in missing_vars:
        print(f"  {var}=<value>", file=sys.stderr)
    sys.exit(1)

# Job listings data (fictional, for tutorial purposes only)
JOBS = [
    ("Senior Backend Engineer", "Stripe", "Backend", "Go, PostgreSQL, gRPC, Kubernetes", "$180-250K/year", "San Francisco, Hybrid", 3,
     "Design and build high-throughput microservices powering payment infrastructure for millions of businesses. Optimize Go services for sub-100ms latency at scale, work with PostgreSQL and Redis for data persistence, and deploy on Kubernetes clusters handling billions of API calls."),
    ("Machine Learning Engineer", "Spotify", "Data/AI", "Python, TensorFlow, BigQuery, Vertex AI", "$170-230K/year", "Stockholm, Remote", 2,
     "Build and deploy ML models for music recommendation and personalization systems serving hundreds of millions of listeners. Design feature pipelines in BigQuery, train models using distributed computing, and serve predictions through real-time APIs processing thousands of requests per second."),
    ("Frontend Engineer", "Vercel", "Frontend", "React, TypeScript, Next.js", "$140-190K/year", "Remote", 4,
     "Build developer-facing dashboard interfaces and deployment tools used by millions of developers worldwide. Create responsive, accessible React components for project management, analytics, and real-time deployment monitoring with a focus on developer experience."),
    ("DevOps Engineer", "Datadog", "DevOps", "Terraform, GCP, Docker, Kubernetes, ArgoCD", "$160-220K/year", "New York, Hybrid", 2,
     "Manage cloud infrastructure powering an observability platform used by thousands of engineering teams. Automate deployment pipelines with ArgoCD, manage multi-cloud Kubernetes clusters, and implement infrastructure-as-code with Terraform across production environments."),
    ("Mobile Engineer (Android)", "Grab", "Mobile", "Kotlin, Jetpack Compose, GraphQL", "$120-170K/year", "Singapore, Hybrid", 3,
     "Develop features for a super-app serving millions of users across Southeast Asia. Build modern Android UIs with Jetpack Compose, integrate GraphQL APIs, and optimize app performance for diverse device capabilities and network conditions."),
    ("Data Engineer", "Airbnb", "Data", "Python, Apache Spark, Airflow, BigQuery", "$160-210K/year", "San Francisco, Hybrid", 2,
     "Build data pipelines that process booking, search, and pricing data for a global travel marketplace. Design ETL workflows with Apache Spark and Airflow, maintain data warehouses in BigQuery, and ensure data quality for analytics and machine learning teams."),
    ("Full Stack Engineer", "Revolut", "Full Stack", "TypeScript, Node.js, React, PostgreSQL", "$130-180K/year", "London, Remote", 5,
     "Build the next generation of financial products making banking accessible to millions of users across 35 countries. Develop real-time trading interfaces with React and WebSockets, build Node.js APIs handling market data streams, and design PostgreSQL schemas for financial transactions."),
    ("Site Reliability Engineer", "Cloudflare", "SRE", "Go, Prometheus, Grafana, GCP, Terraform", "$170-230K/year", "Austin, Hybrid", 2,
     "Ensure 99.99% uptime for a global network handling millions of requests per second. Define SLOs, build monitoring dashboards with Prometheus and Grafana, manage incident response, and automate infrastructure scaling across 300+ data centers worldwide."),
    ("Cloud Architect", "Google Cloud", "Cloud", "GCP, Terraform, Kubernetes, Python", "$200-280K/year", "Seattle, Hybrid", 1,
     "Help enterprises modernize their infrastructure on Google Cloud. Design multi-region architectures, lead migration projects from on-premises to GKE, and build reference implementations using Terraform and Cloud Foundation Toolkit."),
    ("Backend Engineer (Payments)", "Square", "Backend", "Java, Spring Boot, PostgreSQL, Kafka", "$160-220K/year", "San Francisco, Hybrid", 3,
     "Build payment processing systems handling millions of transactions for businesses of all sizes. Design event-driven architectures using Kafka, implement idempotent payment flows with Spring Boot, and ensure PCI-DSS compliance across all services."),
    ("AI Engineer", "Hugging Face", "Data/AI", "Python, LangChain, Vertex AI, FastAPI, PostgreSQL", "$150-210K/year", "Paris, Remote", 2,
     "Build AI-powered tools for the largest open-source ML community. Develop RAG pipelines that index and search model documentation, create conversational agents using LangChain, and deploy AI services with FastAPI on cloud infrastructure."),
    ("Platform Engineer", "Coinbase", "Platform", "Rust, Kubernetes, AWS, Terraform", "$180-250K/year", "Remote", 0,
     "Build the infrastructure platform for a leading cryptocurrency exchange. Develop high-performance matching engines in Rust, manage Kubernetes clusters for microservices, and design CI/CD pipelines that enable rapid feature deployment with zero downtime."),
    ("QA Automation Engineer", "Shopify", "QA", "Python, Selenium, Cypress, Jenkins", "$110-160K/year", "Toronto, Hybrid", 3,
     "Design and maintain automated test suites for a commerce platform powering millions of merchants. Build end-to-end test frameworks with Cypress and Selenium, integrate tests into Jenkins CI pipelines, and establish quality gates that prevent regressions in checkout and payment flows."),
    ("Security Engineer", "CrowdStrike", "Security", "Python, SIEM, Kubernetes, Penetration Testing", "$170-240K/year", "Austin, On-site", 1,
     "Protect enterprise customers from cyber threats on a leading endpoint security platform. Conduct penetration testing, design security monitoring with SIEM tools, implement zero-trust networking in Kubernetes environments, and lead incident response for security events."),
    ("Product Engineer", "GitLab", "Full Stack", "Go, React, PostgreSQL, Redis, GCP", "$140-200K/year", "Remote", 4,
     "Own features end-to-end for an all-in-one DevSecOps platform used by millions of developers. Build Go microservices for CI/CD pipelines, create React frontends for code review and project management, and collaborate with product managers to iterate on user-facing features using data-driven development."),
]


def get_connection():
    """Create a connection to Cloud SQL using the connector."""
    project = os.environ['GOOGLE_CLOUD_PROJECT']
    region = os.environ['REGION']
    password = os.environ['DB_PASSWORD']
    instance = os.environ['DB_INSTANCE']
    database = os.environ['DB_NAME']

    connector = Connector()
    conn = connector.connect(
        f"{project}:{region}:{instance}",
        "pg8000",
        user="postgres",
        password=password,
        db=database
    )
    return conn, connector


def create_schema(cursor):
    """Create extensions and jobs table."""
    cursor.execute("CREATE EXTENSION IF NOT EXISTS google_ml_integration")
    cursor.execute("CREATE EXTENSION IF NOT EXISTS vector")
    cursor.execute("""
        CREATE TABLE IF NOT EXISTS jobs (
            id SERIAL PRIMARY KEY,
            title VARCHAR NOT NULL,
            company VARCHAR NOT NULL,
            role VARCHAR NOT NULL,
            tech_stack VARCHAR NOT NULL,
            salary_range VARCHAR NOT NULL,
            location VARCHAR NOT NULL,
            openings INTEGER NOT NULL,
            description TEXT NOT NULL,
            description_embedding vector(3072)
        )
    """)


def seed_jobs(cursor, conn):
    """Insert job listings."""
    cursor.execute("SELECT COUNT(*) FROM jobs")
    existing_count = cursor.fetchone()[0]

    if existing_count > 0:
        print(f"      {existing_count} jobs already exist, skipping seed")
        return 0

    cursor.executemany("""
        INSERT INTO jobs (title, company, role, tech_stack, salary_range, location, openings, description)
        VALUES (%s, %s, %s, %s, %s, %s, %s, %s)
    """, JOBS)
    conn.commit()
    return len(JOBS)


def generate_embeddings(cursor, conn):
    """Generate embeddings using Cloud SQL's embedding() function."""
    cursor.execute("SELECT COUNT(*) FROM jobs WHERE description_embedding IS NULL")
    null_count = cursor.fetchone()[0]

    if null_count == 0:
        print("      All jobs already have embeddings")
        return 0

    cursor.execute(f"""
        UPDATE jobs
        SET description_embedding = embedding('{EMBEDDING_MODEL}', description)::vector
        WHERE description_embedding IS NULL
    """)
    rows_updated = cursor.rowcount
    conn.commit()
    return rows_updated


def main():
    conn, connector = get_connection()
    cursor = conn.cursor()

    try:
        create_schema(cursor)
        conn.commit()

        seeded = seed_jobs(cursor, conn)
        if seeded > 0:
            print(f"      ✓ Inserted {seeded} jobs")

        # Waiting for vertex role propagation
        time.sleep(60)
        embedded = generate_embeddings(cursor, conn)
        if embedded > 0:
            print(f"      ✓ Generated {embedded} embeddings")

    except Exception as e:
        print(f"ERROR: {e}", file=sys.stderr)
        sys.exit(1)
    finally:
        cursor.close()
        conn.close()
        connector.close()


if __name__ == "__main__":
    main()

حالا بریم مرحله بعدی

۴. ایجاد و مقداردهی اولیه پایگاه داده

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

پروژه پایتون را تنظیم کنید

uv یک پکیج سریع پایتون و مدیر پروژه است که با زبان Rust نوشته شده است ( مستندات uv ). این codelab از آن برای سرعت و سادگی در نگهداری پروژه پایتون استفاده می‌کند.

یک پروژه پایتون را راه‌اندازی کنید و وابستگی‌های مورد نیاز را اضافه کنید:

uv init
uv add cloud-sql-python-connector --extra pg8000
uv add python-dotenv

توجه داشته باشید که ما در اینجا cloud-sql-python-connector Python SDK برای ایجاد یک اتصال امن با نمونه پایگاه داده خود استفاده می‌کنیم که با استفاده از Application Default Credentials احراز هویت می‌شود.

اسکریپت راه‌اندازی را اجرا کنید

اکنون می‌توانیم اسکریپت راه‌اندازی را در پس‌زمینه اجرا کنیم و خروجی کنسول را که با استفاده از دستور زیر در فایل logs/atabase_setup.log نوشته خواهد شد، بررسی کنیم. می‌توانید در حالی که منتظر پایان این بخش هستید، به بخش بعدی بروید.

mkdir -p ~/build-agent-adk-toolbox-cloudsql/logs
bash scripts/setup_database.sh > logs/database_setup.log 2>&1 &

دانلود فایل باینری جعبه ابزار

ما در این آموزش از MCP Toolbox استفاده خواهیم کرد، خوشبختانه این ابزار با یک فایل باینری از پیش ساخته شده ارائه می‌شود که آماده استفاده در محیط لینوکس است. اکنون، بیایید آن را در پس‌زمینه دانلود کنیم، زیرا زمان زیادی طول می‌کشد. دستور زیر را برای دانلود فایل باینری و بررسی گزارش خروجی در logs/toolbox_dl.log اجرا کنید. می‌توانید در حالی که منتظر پایان این بخش هستید، به بخش بعدی بروید.

cd ~/build-agent-adk-toolbox-cloudsql
curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/v1.0.0/linux/amd64/toolbox > logs/toolbox_dl.log 2>&1 &

آشنایی با اسکریپت راه‌اندازی `scripts/setup_database.sh`

حالا بیایید سعی کنیم اسکریپت راه‌اندازی که قبلاً پیکربندی کردیم را بفهمیم. این اسکریپت فرآیند زیر را انجام می‌دهد.

اولین دستوری که در آنجا اجرا می‌کنیم، دستور gcloud sql instances create با پرچم زیر است.

db-custom-1-3840 کوچکترین لایه اختصاصی Cloud SQL با هسته اختصاصی (1 vCPU، 3.75 GB RAM) در نسخه ENTERPRISE است. می‌توانید جزئیات بیشتر را اینجا بخوانید. برای ادغام Vertex AI ML به یک هسته اختصاصی نیاز است - لایه‌های مشترک هسته ( db-f1-micro ، db-g1-small ) از آن پشتیبانی نمی‌کنند.
--root-password ‎ رمز عبور را برای کاربر پیش‌فرض postgres تنظیم می‌کند.
--enable-google-ml-integration امکان ادغام داخلی Cloud SQL با Vertex AI را فراهم می‌کند، که به شما امکان می‌دهد مدل‌های جاسازی را مستقیماً از SQL با استفاده از تابع embedding() فراخوانی کنید.

بررسی کنید که آیا نمونه از قبل در وضعیت RUNNABLE قرار دارد یا خیر
به حساب سرویس نمونه‌ی Cloud SQL اجازه دهید تا با استفاده از دستور gcloud projects add-iam-policy-binding Vertex AI را فراخوانی کند. این مجوز برای تابع داخلی embedding() که هنگام seeding پایگاه داده از آن استفاده خواهیم کرد، لازم است.
ایجاد پایگاه داده
اجرای اسکریپت seeding اسکریپت setup_jobs_db.py

آشنایی با `scripts/setup_jobs_db.py`

حالا، به سراغ اسکریپت seeding می‌رویم، این اسکریپت کارهای زیر را انجام می‌دهد:

مقداردهی اولیه اتصال به نمونه پایگاه داده
دو افزونه PostgreSQL را نصب می‌کند:

google_ml_integration — تابع embedding() SQL را فراهم می‌کند که مدل‌های تعبیه هوش مصنوعی Vertex را مستقیماً از SQL فراخوانی می‌کند. این یک افزونه در سطح پایگاه داده است که توابع یادگیری ماشین را در jobs_db در دسترس قرار می‌دهد. پرچم سطح نمونه ( --enable-google-ml-integration ) که هنگام ایجاد نمونه تنظیم می‌کنید، به ماشین مجازی Cloud SQL اجازه می‌دهد تا به Vertex AI دسترسی پیدا کند — این افزونه توابع SQL را در این پایگاه داده خاص در دسترس قرار می‌دهد.
vector ( pgvector ) - نوع داده vector و عملگرهای فاصله را برای ذخیره و جستجوی جاسازی‌ها اضافه می‌کند.

جدول را ایجاد کنید، توجه داشته باشید که ستون description_embedding vector(3072) است - یک ستون pgvector که بردارهای 3072 بعدی را ذخیره می‌کند.
داده‌های اولیه مشاغل را وارد کنید
داده‌های جاسازی را از فیلد description تولید کنید و description_embedding با استفاده از ادغام رأس داخلی از طریق تابع embedding() پر کنید.

embedding('gemini-embedding-001', description) — مدل embedding Gemini مربوط به Vertex AI را مستقیماً از SQL فراخوانی می‌کند و متن description هر کار را ارسال می‌کند. این افزونه google_ml_integration است که شما در اسکریپت seed نصب کرده‌اید.
::vector — آرایه اعشاری برگشتی را به نوع vector pgvector تبدیل می‌کند تا بتوان آن را ذخیره و با عملگرهای فاصله پرس‌وجو کرد.
UPDATE در هر ۱۵ ردیف اجرا می‌شود و به ازای هر شرح شغل، یک جاسازی ۳۰۷۲ بعدی ایجاد می‌کند.

این داده‌های اولیه‌ای را که توسط نماینده ما قابل دسترسی خواهد بود، آماده می‌کند.

۵. پیکربندی جعبه ابزار MCP برای پایگاه‌های داده

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

MCP چیست و چرا از جعبه ابزار استفاده کنیم؟

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

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

با Toolbox، شما یک فایل YAML می‌نویسید. هر ابزار به یک دستور SQL پارامتری نگاشت می‌شود. Toolbox ادغام اتصال، پرس‌وجوهای پارامتری، احراز هویت و مشاهده‌پذیری را مدیریت می‌کند. ابزارها از عامل جدا شده‌اند - یک پرس‌وجو را با ویرایش tools.yaml و راه‌اندازی مجدد Toolbox، بدون دست زدن به کد عامل، به‌روزرسانی کنید. همین ابزارها در ADK، LangGraph، LlamaIndex یا هر چارچوب سازگار با MCP کار می‌کنند.

پیکربندی ابزارها را بنویسید

حالا، باید فایلی به نام tools.yaml در ویرایشگر Cloud Shell ایجاد کنیم تا پیکربندی ابزارهایمان را تنظیم کنیم.

cloudshell edit tools.yaml

این فایل از YAML چند سندی استفاده می‌کند - هر بلوک جدا شده با --- یک منبع مستقل است. هر منبع یک kind دارد که ماهیت آن را اعلام می‌کند ( sources برای اتصالات پایگاه داده، tools برای اقدامات قابل فراخوانی توسط عامل) و یک type که backend را مشخص می‌کند ( cloud-sql-postgres برای منبع، postgres-sql برای ابزارهای مبتنی بر SQL). یک ابزار منبع خود را با name ارجاع می‌دهد، به این ترتیب Toolbox می‌داند که در کدام مخزن اتصال اجرا شود. متغیرهای محیطی از سینتکس ${VAR_NAME} استفاده می‌کنند و در هنگام راه‌اندازی حل می‌شوند.

حالا، بیایید اسکریپت‌های زیر را ابتدا در فایل tools.yaml کپی کنیم.

# tools.yaml

# --- Data Source ---
kind: source
name: jobs-db
type: cloud-sql-postgres
project: ${GOOGLE_CLOUD_PROJECT}
region: ${REGION}
instance: ${DB_INSTANCE}
database: ${DB_NAME}
user: postgres
password: ${DB_PASSWORD}

---