Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Cloud Run'a dağıtmadan önce bir Google E-Tablosu'na yazan ADK aracısının yerel olarak nasıl test edileceği

1. Giriş

Genel Bakış

Bu yayında, Google Agent Development Kit (ADK) ve FastAPI kullanarak bir Gemini ajanı oluşturacaksınız. Dağıtımdan önce, Cloud Run hizmet kimliğiyle aynı hizmet hesabını kullanarak yerel olarak test etmek için Uygulama Varsayılan Kimlik Bilgileri'ni (ADC) yapılandıracaksınız.

Uygulamanızın Google E-Tablolar ile iletişim kurabilmesi için e-tabloya erişmek üzere uygun kapsamda bir OAuth erişim jetonu gerekir. Yerel olarak ve ADC ile Cloud Run'da çalışırken bu erişim jetonunu nasıl alacağınızı öğreneceksiniz:

Yerel olarak: ADC, gcloud auth application-default komutu tarafından oluşturulan kimlik bilgilerini bulur. Daha fazla bilgiyi burada bulabilirsiniz.
Cloud Run'da: ADC, kimlik bilgilerini almak için meta veri sunucusunu kullanır. Daha fazla bilgiye buradan ulaşabilirsiniz.

Terminoloji Notu:

"Kimliğe bürünme" veya "aynı izinlere sahip olma" terimlerini daha iyi biliyor olabilirsiniz. Google Cloud'da, kimliği doğrulanmış bir asıl, hizmet hesabının kimliğine bürünerek hizmet hesabının erişebildiği her şeye erişebilir. Yalnızca uygun izinlere sahip kimliği doğrulanmış asıl kullanıcılar hizmet hesaplarının kimliğine bürünebilir. Daha fazla bilgiyi https://docs.cloud.google.com/iam/docs/service-account-overview#impersonation adresinde bulabilirsiniz.

Neler öğreneceksiniz?

Yerel ortamınız için Uygulama Varsayılan Kimlik Bilgileri'ni (ADC) yapılandırma
Google E-Tablosu'nu okuyup yazabilen bir ADK aracısı oluşturma
Aracıyı Cloud Run'a dağıtma

2. Kurulum ve Gereksinimler

Ön koşullar

Cloud Console'a giriş yapmış olmanız gerekir.
Daha önce bir Cloud Run hizmeti dağıtmış olmanız gerekir. Örneğin, başlamak için Cloud Run hizmeti dağıtma adımlarını uygulayabilirsiniz.

Ortam değişkenlerini ayarlama

Bu codelab boyunca kullanılacak ortam değişkenlerini ayarlayabilirsiniz.

Paylaş bağlantısını kopyaladığınızda, E-Tablo Kimliğinizi Google E-Tablonuzun URL'sinde bulabilirsiniz. Örneğin: 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

Gerekli Google Cloud API'lerini etkinleştirme

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

Hizmet hesabı oluşturma

Öncelikle aşağıdaki komutla hizmet hesabını oluşturun.

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

Ardından, hizmet hesabına Vertex AI Kullanıcısı rolünü verin (Vertex AI'daki Gemini modelleri için gereklidir).

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

gcloud kimliğinize hizmet hesabının kimliğine bürünme izni verin (yerel geliştirme için gereklidir). gcloud auth list komutunu çalıştırarak gcloud kimliklerinizi görebilirsiniz.

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

Google E-Tablosu'nu tarayıcıda açın.
Paylaş düğmesini tıklayın.
Hizmet hesabı e-posta adresini ($SERVICE_ACCOUNT_EMAIL) yapıştırın ve bu hesaba Düzenleyici erişimi verin.

3. Uygulamayı oluşturma

Öncelikle kaynak kod için bir dizin oluşturun ve bu dizine gidin.

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

Ardından, aşağıdaki içeriğe sahip bir main.py dosyası oluşturun:

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))

Ardından, aşağıdaki içeriğe sahip bir requirements.txt dosyası oluşturun:

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

4. Hizmeti yerel olarak test etme

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

Şimdi aracınızı başka bir terminalden test edin:

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"}'

Sunucu şu yanıtı vermelidir: {"response":"The spreadsheet at Sheet1!A1 has been updated with the value \"hello world\"."}

5. Cloud Run'a dağıt

Hizmet hesabınızın e-tabloya erişmek için uygun izinlere sahip olduğunu bildiğinize göre artık hizmet hesabını hizmet kimliği olarak kullanarak Cloud Run'a dağıtım yapabilirsiniz.

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

Dağıtım tamamlandığında Cloud Run hizmetinize bir istem gönderin.

# 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\"."} yanıtını alırsınız.

Şimdi Google E-Tablonuzu açın. İlk hücrede "hello world" değerini görürsünüz.

6. Tebrikler!

Codelab'i tamamladığınız için tebrik ederiz.

Yapabilecekleriniz

Aşağıdaki dokümanları inceleyerek aracınızın özelliklerini genişletmenizi öneririz:

Google Agent Development Kit (ADK)'yi kullanarak gelişmiş ajan iş akışlarını keşfedin.
Cloud Run'da yapay zeka çözümleri oluşturma ile ilgili en iyi uygulamalar hakkında daha fazla bilgi edinin.
Cloud Run'dan Google Cloud API'lerinde güvenli kimlik doğrulama hakkında bilgi edinin.

İşlediğimiz konular

Yerel ortamınız için Uygulama Varsayılan Kimlik Bilgileri'ni (ADC) yapılandırma
Google E-Tablosu'nu okuyup yazabilen bir ADK aracısı oluşturma
Aracıyı Cloud Run'a dağıtma

7. Temizleme

Yanlışlıkla ücretlendirilmemek için (örneğin, bu Cloud Run işlevi ücretsiz katmandaki aylık Cloud Run çağırma tahsisinizden daha fazla sayıda çağrılırsa) Cloud Run hizmetini veya projeyi silebilirsiniz.

Cloud Run hizmetini silmek için Cloud Console'da https://console.cloud.google.com/run/ adresine giderek Cloud Run'ı açın ve bu codelab'de oluşturduğunuz hizmeti local-adk-sheets-codelab silin.

Projenin tamamını silmeyi tercih ederseniz https://console.cloud.google.com/cloud-resource-manager adresine gidebilir, 2. adımda oluşturduğunuz projeyi seçip Sil'i tıklayabilirsiniz. Projeyi silerseniz Cloud SDK'nızda projeleri değiştirmeniz gerekir. gcloud projects list komutunu çalıştırarak kullanılabilir tüm projelerin listesini görüntüleyebilirsiniz.