Cloud Run पर डिप्लॉय करने से पहले, Google शीट में लिखने वाले ADK एजेंट की स्थानीय तौर पर टेस्टिंग कैसे करें

1. परिचय

खास जानकारी

इस पोस्ट में, Google Agent Development Kit (ADK) और FastAPI का इस्तेमाल करके, Gemini एजेंट बनाने का तरीका बताया गया है. डिप्लॉय करने से पहले, आपको Application Default Credentials (ADC) कॉन्फ़िगर करना होगा, ताकि Cloud Run सेवा की पहचान के तौर पर इस्तेमाल किए जा रहे सेवा खाते का इस्तेमाल करके, स्थानीय तौर पर टेस्ट किया जा सके.

Google Sheets से कम्यूनिकेट करने के लिए, आपके ऐप्लिकेशन को 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 पर जाएं

आपको क्या सीखने को मिलेगा

  • अपने लोकल एनवायरमेंट के लिए, Application Default Credentials (ADC) कॉन्फ़िगर करने का तरीका
  • ऐसा ADK एजेंट बनाने का तरीका जो Google Sheet को पढ़ और उसमें लिख सकता है
  • एजेंट को Cloud Run पर डिप्लॉय करने का तरीका

2. सेटअप और ज़रूरी शर्तें

ज़रूरी शर्तें

  • आपने Cloud Console में लॉग इन किया हो.
  • आपने पहले Cloud Run सेवा डिप्लॉय की हो. उदाहरण के लिए, शुरू करने के लिए, Cloud Run सेवा डिप्लॉय करने का तरीका देखें.

एनवायरमेंट वैरिएबल सेट करना

एनवायरमेंट वैरिएबल सेट किए जा सकते हैं. इनका इस्तेमाल इस कोडलैब में किया जाएगा.

शेयर करने का लिंक कॉपी करने पर, Google Sheet के यूआरएल में शीट आईडी देखा जा सकता है. जैसे, 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 API चालू करना

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 के उपयोगकर्ता की भूमिका असाइन करें. Vertex AI पर Gemini मॉडल के लिए यह ज़रूरी है

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

अपने gcloud आइडेंटिटी को, सेवा खाते के तौर पर काम करने की अनुमति दें. लोकल डेवलपमेंट के लिए यह ज़रूरी है. gcloud auth list कमांड चलाकर, अपनी gcloud आइडेंटिटी देखी जा सकती हैं

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 Sheet खोलें.
  2. शेयर करें बटन पर क्लिक करें.
  3. सेवा खाते का ईमेल $SERVICE_ACCOUNT_EMAIL चिपकाएं और उसे एडिटर ऐक्सेस दें.

3. ऐप्लिकेशन बनाना

सबसे पहले, सोर्स कोड के लिए कोई डायरेक्ट्री बनाएं और उस डायरेक्ट्री में cd करें.

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 Sheet खोलें. आपको पहले सेल में "hello world" वैल्यू दिखेगी.

6. बधाई हो!

कोडलैब पूरा करने के लिए बधाई!

अब क्या करना है?

हमारा सुझाव है कि अपने एजेंट की क्षमताओं को बढ़ाने के लिए, यह दस्तावेज़ पढ़ें:

हमने क्या-क्या कवर किया

  • अपने लोकल एनवायरमेंट के लिए, Application Default Credentials (ADC) कॉन्फ़िगर करने का तरीका
  • ऐसा ADK एजेंट बनाने का तरीका जो Google Sheet को पढ़ और उसमें लिख सकता है
  • एजेंट को Cloud Run पर डिप्लॉय करने का तरीका

7. स्टोरेज में जगह बनाएं

अनजाने में शुल्क लगने से बचने के लिए, Cloud Run सेवा को मिटाया जा सकता है या प्रोजेक्ट मिटाया जा सकता है. उदाहरण के लिए, अगर इस Cloud Run फ़ंक्शन को मुफ़्त टियर में, Cloud Run के लिए हर महीने मिलने वाले कोटा से ज़्यादा बार अनजाने में कॉल किया जाता है, तो शुल्क लग सकता है.

Cloud Run सेवा मिटाने के लिए, Cloud Console में Cloud Run पर जाएं. इसके लिए, https://console.cloud.google.com/run/ पर जाएं. इसके बाद, इस कोडलैब में बनाई गई local-adk-sheets-codelab सेवा मिटाएं.

अगर आपको पूरा प्रोजेक्ट मिटाना है, तो https://console.cloud.google.com/cloud-resource-manager पर जाएं. इसके बाद, चरण 2 में बनाया गया प्रोजेक्ट चुनें और मिटाएं को चुनें. प्रोजेक्ट मिटाने पर, आपको अपने Cloud SDK में प्रोजेक्ट बदलने होंगे. gcloud projects list कमांड चलाकर, उपलब्ध सभी प्रोजेक्ट की सूची देखी जा सकती है.