ক্লাউড রানে ডেপ্লয় করার আগে, গুগল শিটে ডেটা লেখে এমন একটি ADK এজেন্টের লোকাল টেস্টিং কীভাবে করবেন

১. ভূমিকা

সংক্ষিপ্ত বিবরণ

এই পোস্টে, আপনি গুগল এজেন্ট ডেভেলপমেন্ট কিট (ADK) এবং ফাস্টএপিআই (FastAPI) ব্যবহার করে একটি জেমিনি এজেন্ট তৈরি করবেন। ডেপ্লয়মেন্টের আগে, ক্লাউড রান সার্ভিস আইডেন্টিটির মতো একই সার্ভিস অ্যাকাউন্ট ব্যবহার করে স্থানীয়ভাবে পরীক্ষা করার জন্য আপনি অ্যাপ্লিকেশন ডিফল্ট ক্রেডেনশিয়ালস (ADC) কনফিগার করবেন।

গুগল শিটসের সাথে যোগাযোগ করতে, আপনার অ্যাপ্লিকেশনের স্প্রেডশিট অ্যাক্সেস করার জন্য উপযুক্ত স্কোপ সহ একটি OAuth অ্যাক্সেস টোকেন প্রয়োজন। স্থানীয়ভাবে এবং ADC সহ ক্লাউড রানে চালানোর সময় কীভাবে এই অ্যাক্সেস টোকেনটি পেতে হয় তা আপনি শিখবেন:

• স্থানীয়ভাবে: gcloud auth application-default কমান্ড দ্বারা তৈরি ক্রেডেনশিয়ালগুলো ADC খুঁজে পায়। আপনি এখানে আরও তথ্য পেতে পারেন।
• ক্লাউড রান-এ: ADC ক্রেডেনশিয়াল পেতে মেটাডেটা সার্ভার ব্যবহার করে। আপনি এখানে আরও তথ্য পেতে পারেন।

পরিভাষা সংক্রান্ত টীকা:

আপনি হয়তো 'assuming an identity' বা 'assuming the same permissions' শব্দগুলোর সাথে বেশি পরিচিত। গুগল ক্লাউডে, একটি সার্ভিস অ্যাকাউন্টকে ইমপারসোনেট করলে একজন অথেনটিকেটেড প্রিন্সিপাল সেই সার্ভিস অ্যাকাউন্টের অ্যাক্সেসযোগ্য সবকিছু অ্যাক্সেস করতে পারে। শুধুমাত্র উপযুক্ত পারমিশনসহ অথেনটিকেটেড প্রিন্সিপালরাই সার্ভিস অ্যাকাউন্ট ইমপারসোনেট করতে পারে। আপনি এখানে আরও পড়তে পারেন : https://docs.cloud.google.com/iam/docs/service-account-overview#impersonation

আপনি যা শিখবেন

• আপনার স্থানীয় পরিবেশের জন্য অ্যাপ্লিকেশন ডিফল্ট ক্রেডেনশিয়াল (ADC) কীভাবে কনফিগার করবেন
• কীভাবে একটি ADK এজেন্ট তৈরি করবেন যা গুগল শিটে পড়তে এবং লিখতে পারে
• ক্লাউড রানে এজেন্ট কীভাবে স্থাপন করবেন

২. সেটআপ এবং প্রয়োজনীয়তা

পূর্বশর্ত

• আপনি ক্লাউড কনসোলে লগ ইন করেছেন।
• আপনি পূর্বে একটি ক্লাউড রান পরিষেবা স্থাপন করেছেন। উদাহরণস্বরূপ, শুরু করার জন্য আপনি 'একটি ক্লাউড রান পরিষেবা স্থাপন করুন' অনুসরণ করতে পারেন।

পরিবেশ ভেরিয়েবল সেট করুন

আপনি এনভায়রনমেন্ট ভেরিয়েবল সেট করতে পারেন, যা এই কোডল্যাব জুড়ে ব্যবহৃত হবে।

আপনি যখন শেয়ার লিঙ্কটি কপি করবেন, তখন আপনার গুগল শীটের URL-এ আপনার শীট আইডিটি খুঁজে পাবেন, যেমন: 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

প্রয়োজনীয় গুগল ক্লাউড এপিআই সক্রিয় করুন

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

এরপরে, সার্ভিস অ্যাকাউন্টটিকে ভার্টেক্স এআই ইউজার রোলটি প্রদান করুন (ভার্টেক্স এআই-তে জেমিনি মডেলের জন্য এটি প্রয়োজন)।

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. ব্রাউজারে গুগল শিটটি খুলুন।
2. শেয়ার বাটনটিতে ক্লিক করুন।
3. সার্ভিস অ্যাকাউন্টের ইমেইল $SERVICE_ACCOUNT_EMAIL পেস্ট করুন এবং এটিকে এডিটর অ্যাক্সেস দিন।

৩. অ্যাপটি তৈরি করুন

প্রথমে, সোর্স কোডের জন্য একটি ডিরেক্টরি তৈরি করুন এবং সেই ডিরেক্টরিতে প্রবেশ করুন।

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

৪. স্থানীয়ভাবে পরিষেবাটি পরীক্ষা করুন

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

দ্রষ্টব্য: ক্লাউড রান থেকে পরীক্ষা করার আগে আপনার স্প্রেডশীট থেকে ‘hello world’ ভ্যালুটি মুছে ফেলতে ভুলবেন না, যাতে আপনি নিশ্চিত হতে পারেন যে এটি ক্লাউড রান থেকে কাজ করছে।

৫. ক্লাউড রান-এ ডেপ্লয় করুন

এখন যেহেতু আপনি জানেন যে আপনার সার্ভিস অ্যাকাউন্টের স্প্রেডশিট অ্যাক্সেস করার জন্য উপযুক্ত অনুমতি রয়েছে, তাই এখন আপনি সার্ভিস অ্যাকাউন্টটিকে সার্ভিস আইডেন্টিটি হিসেবে ব্যবহার করে ক্লাউড রান-এ ডেপ্লয় করবেন।

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

ডেপ্লয়মেন্ট শেষ হলে, আপনার ক্লাউড রান সার্ভিসে একটি প্রম্পট পাঠান।

# 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\"."} এই প্রতিক্রিয়াটি পাবেন।

এখন আপনার গুগল শিটটি খুলুন। আপনি প্রথম সেলটিতে "hello world" লেখাটি দেখতে পাবেন।

৬. অভিনন্দন!

কোডল্যাবটি সম্পন্ন করার জন্য অভিনন্দন!

এরপর কী?

আপনার এজেন্টের সক্ষমতা বাড়াতে আমরা নিম্নলিখিত ডকুমেন্টেশনগুলো খতিয়ে দেখার পরামর্শ দিচ্ছি:

• গুগল এজেন্ট ডেভেলপমেন্ট কিট (ADK) ব্যবহার করে উন্নত এজেন্ট ওয়ার্কফ্লো অন্বেষণ করুন।
• ক্লাউড রান-এ এআই সলিউশন তৈরির আরও সেরা অনুশীলন সম্পর্কে জানুন।
• Cloud Run থেকে Google Cloud API-গুলিতে কীভাবে নিরাপদে প্রমাণীকরণ করতে হয়, তা বুঝুন।

আমরা যা আলোচনা করেছি

• আপনার স্থানীয় পরিবেশের জন্য অ্যাপ্লিকেশন ডিফল্ট ক্রেডেনশিয়াল (ADC) কীভাবে কনফিগার করবেন
• কীভাবে একটি ADK এজেন্ট তৈরি করবেন যা গুগল শিটে পড়তে এবং লিখতে পারে
• ক্লাউড রানে এজেন্ট কীভাবে স্থাপন করবেন

৭. পরিষ্কার করুন

অনিচ্ছাকৃত চার্জ এড়াতে (উদাহরণস্বরূপ, যদি এই ক্লাউড রান ফাংশনটি ফ্রি টিয়ারে আপনার মাসিক ক্লাউড রান ইনভোকেশন বরাদ্দের চেয়ে বেশিবার অনিচ্ছাকৃতভাবে চালু হয়ে যায়), আপনি হয় ক্লাউড রান পরিষেবাটি অথবা প্রজেক্টটি ডিলিট করে দিতে পারেন।

একটি ক্লাউড রান সার্ভিস ডিলিট করতে, https://console.cloud.google.com/run/ -এ অবস্থিত ক্লাউড কনসোলের ক্লাউড রান-এ যান এবং এই কোডল্যাবে আপনার তৈরি করা local-adk-sheets-codelab সার্ভিসটি ডিলিট করুন।

আপনি যদি পুরো প্রজেক্টটি মুছে ফেলতে চান, তাহলে আপনি https://console.cloud.google.com/cloud-resource-manager -এ গিয়ে, ধাপ ২-এ তৈরি করা প্রজেক্টটি নির্বাচন করে 'ডিলিট' (Delete) বিকল্পটি বেছে নিতে পারেন। প্রজেক্টটি মুছে ফেললে, আপনাকে আপনার ক্লাউড এসডিকে (Cloud SDK)-তে প্রজেক্ট পরিবর্তন করতে হবে। আপনি gcloud projects list চালিয়ে সমস্ত উপলব্ধ প্রজেক্টের তালিকা দেখতে পারেন।