كيفية إجراء اختبار محلي لوكيل ADK يكتب إلى "جدول بيانات Google" قبل نشره على Cloud Run

1- مقدمة

نظرة عامة

في هذا المنشور، ستنشئ وكيل Gemini باستخدام حزمة تطوير الوكلاء (ADK) من Google وFastAPI. قبل النشر، عليك ضبط بيانات الاعتماد التلقائية للتطبيق (ADC) لإجراء الاختبار محليًا باستخدام حساب الخدمة نفسه الذي يمثّل هوية خدمة Cloud Run.

للتواصل مع "جداول بيانات Google"، يحتاج تطبيقك إلى رمز OAuth المميّز للوصول مع النطاق المناسب للوصول إلى جدول البيانات. ستتعرّف على كيفية الحصول على رمز الوصول هذا عند التشغيل محليًا وعلى Cloud Run باستخدام بيانات الاعتماد التلقائية للتطبيق (ADC):

  • محليًا: تعثر بيانات الاعتماد التلقائية للتطبيق (ADC) على بيانات الاعتماد التي تم إنشاؤها باستخدام الأمر gcloud auth application-default. يمكنك العثور على مزيد من المعلومات هنا
  • على Cloud Run: تستخدم بيانات الاعتماد التلقائية للتطبيق (ADC) خادم البيانات الوصفية للحصول على بيانات الاعتماد. يمكنك العثور على مزيد من المعلومات هنا.

ملاحظة حول المصطلحات:

قد تكون على دراية أكبر بمصطلحات "تولّي هوية" أو "تولّي الأذونات نفسها". في Google Cloud، يتيح انتحال حساب خدمة لكيان أساسي تم التحقّق من هويته الوصول إلى أي محتوى يمكن لحساب الخدمة الوصول إليه. لا يمكن انتحال حسابات الخدمة إلا للكيانات الأساسية التي تم التحقّق من هويتها والتي لديها الأذونات المناسبة. يمكنك قراءة المزيد هنا https://docs.cloud.google.com/iam/docs/service-account-overview#impersonation

ما ستتعرّف عليه

  • كيفية ضبط بيانات الاعتماد التلقائية للتطبيق (ADC) لبيئتك المحلية
  • كيفية إنشاء وكيل ADK يمكنه القراءة والكتابة في "جدول بيانات Google"
  • كيفية نشر الوكيل على Cloud Run

2. الإعداد والمتطلبات

المتطلبات الأساسية

  • لقد سجّلت الدخول إلى Cloud Console.
  • سبق لك نشر خدمة Cloud Run. على سبيل المثال، يمكنك اتّباع خطوات نشر خدمة Cloud Run للبدء.

ضبط المتغيّرات البيئية

يمكنك ضبط المتغيّرات البيئية التي سيتم استخدامها في هذا الدرس التطبيقي حول الترميز.

يمكنك العثور على رقم تعريف جدول البيانات في عنوان URL لـ "جدول بيانات Google" عند نسخ رابط المشاركة، مثلاً https://docs.google.com/spreadsheets/d/YOUR_SPREADSHEET_ID/edit?usp=sharing

PROJECT_ID=<YOUR-PROJECT-ID>
REGION=<YOUR_REGION>
SPREADSHEET_ID=<YOUR_SPREADSHEET_ID>
SA_NAME=sheet-agent-sa
SERVICE_ACCOUNT_EMAIL=$SA_NAME@$PROJECT_ID.iam.gserviceaccount.com

تفعيل واجهات برمجة تطبيقات Google Cloud المطلوبة

gcloud services enable \
  sheets.googleapis.com \
  aiplatform.googleapis.com \
  artifactregistry.googleapis.com \
  cloudbuild.googleapis.com \
  run.googleapis.com \
  logging.googleapis.com \
  --project=$PROJECT_ID

إنشاء حساب خدمة

أولاً، أنشئ حساب الخدمة باستخدام الأمر التالي.

gcloud iam service-accounts create $SA_NAME \
    --description="Service account for spreadsheet agent codelab" \
    --display-name="Spreadsheet Agent Service Account" \
    --project=$PROJECT_ID

بعد ذلك، امنح دور مستخدم Vertex AI لحساب الخدمة (مطلوب لنماذج Gemini على Vertex AI)

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

امنح هوية gcloud إذن انتحال حساب الخدمة (مطلوب للتطوير المحلي). يمكنك الاطّلاع على هويات gcloud من خلال تشغيل gcloud auth list

USER_EMAIL=$(gcloud config get-value account)

gcloud iam service-accounts add-iam-policy-binding $SERVICE_ACCOUNT_EMAIL \
    --member="user:$USER_EMAIL" \
    --role="roles/iam.serviceAccountTokenCreator" \
    --project=$PROJECT_ID
  1. افتح "جدول بيانات Google" في المتصفّح.
  2. انقر على الزر مشاركة.
  3. ألصِق عنوان البريد الإلكتروني لحساب الخدمة $SERVICE_ACCOUNT_EMAIL وامنحه إذن وصول بصفة محرِّر.

3. إنشاء التطبيق

أولاً، أنشئ دليلًا للرمز المصدري وانتقِل إلى هذا الدليل.

mkdir local-adk-sheets-codelab && cd $_

بعد ذلك، أنشئ ملفًا باسم main.py يتضمّن المحتوى التالي:

import os
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from google.auth import default
from googleapiclient.discovery import build
from google.adk.agents.llm_agent import Agent
from google.adk.runners import InMemoryRunner

# 1. Environment and Global Google Sheets Client Setup (ADC)
SPREADSHEET_ID = os.environ.get("SPREADSHEET_ID")
if not SPREADSHEET_ID:
    raise ValueError("SPREADSHEET_ID environment variable is missing. Please set it before running.")

credentials, _ = default(scopes=['https://www.googleapis.com/auth/spreadsheets'])
sheets_api = build('sheets', 'v4', credentials=credentials).spreadsheets()

# 2. Tools
def read_spreadsheet(range_name: str) -> dict:
    """Reads values from the Google Spreadsheet for a given range.
   
    Args:
        range_name: The A1 notation or R1C1 notation of the range to retrieve, e.g., 'Sheet1!A1:D10'.
    """
    return sheets_api.values().get(spreadsheetId=SPREADSHEET_ID, range=range_name).execute()

def update_spreadsheet(range_name: str, values: list[list[str]]) -> dict:
    """Updates the Google Spreadsheet range with the specified grid of values.
   
    Args:
        range_name: The A1 notation or R1C1 notation of the range to update, e.g., 'Sheet1!C2'.
        values: A list of lists of strings representing the grid of values to write.
    """
    return sheets_api.values().update(
        spreadsheetId=SPREADSHEET_ID,
        range=range_name,
        valueInputOption="USER_ENTERED",
        body={"values": values}
    ).execute()

# 3. Agent Definition
MODEL_NAME = os.environ.get("GEMINI_MODEL", "gemini-3.1-flash-lite")
root_agent = Agent(
    name="spreadsheet_agent",
    model=MODEL_NAME,
    instruction="""You are a helpful spreadsheet assistant.
    You can read and write to the user's Google Spreadsheet using the tools provided.
    Always use the appropriate tools when the user asks you to read or update a spreadsheet.
    When updating a range, make sure the values parameter is a list of lists (e.g. [[value]]).
    Be concise and helpful in your responses.""",
    description="An agent that can read and write to a specific Google Spreadsheet.",
    tools=[read_spreadsheet, update_spreadsheet]
)

# 4. FastAPI Application Setup
app = FastAPI()

class ChatRequest(BaseModel):
    prompt: str

@app.post("/chat")
async def chat_endpoint(request: ChatRequest):
    try:
        async with InMemoryRunner(app_name="sheets_agent_app", agent=root_agent) as runner:
            events = await runner.run_debug(request.prompt, quiet=True)
           
            # Extract the final response text
            texts = [
                "".join(p.text for p in e.content.parts if p.text)
                for e in reversed(events) if e.content and e.content.parts
            ]
            return {"response": next((t for t in texts if t), "No response from agent.")}
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

بعد ذلك، أنشئ ملفًا باسم requirements.txt يتضمّن المحتوى التالي:

fastapi>=0.100.0
uvicorn>=0.22.0
google-adk>=1.27.1
google-auth
google-api-python-client

4. اختبار الخدمة محليًا 

gcloud auth application-default login --impersonate-service-account=$SERVICE_ACCOUNT_EMAIL

GOOGLE_GENAI_USE_VERTEXAI=1 GOOGLE_CLOUD_PROJECT=$PROJECT_ID SPREADSHEET_ID=$SPREADSHEET_ID uvicorn main:app --host 0.0.0.0 --port 8080

الآن، اختبِر وكيلك من محطة طرفية أخرى:

curl -X POST http://localhost:8080/chat \
    -H "Content-Type: application/json" \
    -d '{"prompt": "Update spreadsheet '$SPREADSHEET_ID' at range Sheet1!A1 with the value hello world"}'

يجب أن يردّ الخادم بالرسالة: {"response":"The spreadsheet at Sheet1!A1 has been updated with the value \"hello world\"."}

5. النشر على Cloud Run

بعد التأكّد من أنّ حساب الخدمة لديه الأذونات المناسبة للوصول إلى جدول البيانات، يمكنك الآن النشر على Cloud Run باستخدام حساب الخدمة كهوية الخدمة.

gcloud run deploy local-adk-sheets-codelab \
    --source . \
    --region=$REGION \
    --set-env-vars GOOGLE_GENAI_USE_VERTEXAI=1,GOOGLE_CLOUD_PROJECT=$PROJECT_ID,GOOGLE_CLOUD_LOCATION=global,SPREADSHEET_ID=$SPREADSHEET_ID \
    --service-account $SERVICE_ACCOUNT_EMAIL \
    --no-allow-unauthenticated \
    --project=$PROJECT_ID

عند اكتمال عملية النشر، أرسِل طلبًا إلى خدمة Cloud Run.

# Retrieve the Service URL
SERVICE_URL=$(gcloud run services describe local-adk-sheets-codelab --region $REGION --format 'value(status.url)')

curl -X POST $SERVICE_URL/chat \
    -H "Authorization: bearer $(gcloud auth print-identity-token)" \
    -H "Content-Type: application/json" \
    -d '{"prompt": "Update spreadsheet '$SPREADSHEET_ID' at range Sheet1!A1 with the value hello world"}'

يجب أن تتلقّى ردًا بالرسالة {"response":"OK. I've updated cell A1 in Sheet1 with \"hello world\"."}

افتح الآن "جدول بيانات Google". سيظهر لك في الخلية الأولى القيمة "hello world".

6. تهانينا!

تهانينا على إكمال الدرس التطبيقي حول الترميز.

ما هي الخطوات التالية؟

ننصحك باستكشاف المستندات التالية لتوسيع إمكانات وكيلك:

المواضيع التي تناولناها

  • كيفية ضبط بيانات الاعتماد التلقائية للتطبيق (ADC) لبيئتك المحلية
  • كيفية إنشاء وكيل ADK يمكنه القراءة والكتابة في "جدول بيانات Google"
  • كيفية نشر الوكيل على Cloud Run

7. تَنظيم

لتجنُّب الرسوم غير المقصودة (على سبيل المثال، إذا تم استدعاء وظيفة Cloud Run هذه عن غير قصد مرات أكثر من عدد استدعاءات Cloud Run الشهرية المخصّصة لك في المستوى المجاني)، يمكنك إما حذف خدمة Cloud Run أو حذف المشروع.

لحذف خدمة Cloud Run، انتقِل إلى Cloud Run في Cloud Console على https://console.cloud.google.com/run/ وحذف الخدمة local-adk-sheets-codelab التي أنشأتها في هذا الدرس التطبيقي حول الترميز.

إذا اخترت حذف المشروع بأكمله، يمكنك الانتقال إلى https://console.cloud.google.com/cloud-resource-manager، واختيار المشروع الذي أنشأته في الخطوة 2، ثم النقر على حذف. إذا حذفت المشروع، عليك تغيير المشاريع في Cloud SDK. يمكنك الاطّلاع على قائمة بجميع المشاريع المتاحة من خلال تشغيل gcloud projects list.