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

Jak przeprowadzić lokalne testowanie agenta ADK, który zapisuje dane w arkuszu Google, przed wdrożeniem go w Cloud Run

1. Wprowadzenie

Przegląd

W tym poście utworzysz agenta Gemini za pomocą Google Agent Development Kit (ADK) i FastAPI. Przed wdrożeniem skonfigurujesz domyślne dane logowania aplikacji (ADC), aby testować lokalnie za pomocą tego samego konta usługi co tożsamość usługi Cloud Run.

Aby komunikować się z Arkuszami Google, Twoja aplikacja potrzebuje tokena dostępu OAuth z odpowiednim zakresem, który umożliwi dostęp do arkusza kalkulacyjnego. Dowiesz się, jak uzyskać ten token dostępu podczas uruchamiania lokalnie i w Cloud Run za pomocą ADC:

Lokalnie: ADC znajduje dane logowania wygenerowane przez polecenie gcloud auth application-default. Więcej informacji znajdziesz tutaj.
W Cloud Run: ADC używa serwera metadanych do uzyskiwania danych logowania. Więcej informacji znajdziesz tutaj.

Uwaga dotycząca terminologii:

Możesz lepiej znać terminy „przyjmowanie tożsamości” lub „przyjmowanie tych samych uprawnień”. W Google Cloud przejęcie tożsamości konta usługi umożliwia uwierzytelnionemu podmiotowi zabezpieczeń dostęp do wszystkiego, do czego ma dostęp konto usługi. Tylko uwierzytelnione podmioty zabezpieczeń z odpowiednimi uprawnieniami mogą przejmować tożsamość kont usługi. Więcej informacji znajdziesz tutaj: https://docs.cloud.google.com/iam/docs/service-account-overview#impersonation

Czego się nauczysz

Jak skonfigurować domyślne uwierzytelnianie aplikacji (ADC) w środowisku lokalnym
Jak utworzyć agenta ADK, który może odczytywać i zapisywać dane w Arkuszach Google
Jak wdrożyć agenta w Cloud Run

2. Konfiguracja i wymagania

Wymagania wstępne

Jesteś zalogowany(-a) w Cloud Console.
Masz już wdrożoną usługę Cloud Run. Aby zacząć, możesz na przykład wdrożyć usługę Cloud Run.

Ustawianie zmiennych środowiskowych

Możesz ustawić zmienne środowiskowe, które będą używane podczas tego ćwiczenia.

Identyfikator arkusza znajdziesz w adresie URL arkusza Google, gdy skopiujesz link do udostępniania, np.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

Włączanie wymaganych interfejsów 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

Utwórz konto usługi

Najpierw utwórz konto usługi za pomocą tego polecenia.

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

Następnie przyznaj kontu usługi rolę użytkownika Vertex AI (wymaganą w przypadku modeli Gemini w Vertex AI).

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

Przyznaj tożsamości gcloud uprawnienia do przejmowania tożsamości konta usługi (wymagane do programowania lokalnego). Tożsamości gcloud możesz sprawdzić, uruchamiając polecenie 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

Otwórz arkusz Google w przeglądarce.
Kliknij przycisk Udostępnij.
Wklej adres e-mail konta usługi $SERVICE_ACCOUNT_EMAIL i przyznaj mu uprawnienia do edycji.

3. Tworzenie aplikacji

Najpierw utwórz katalog na kod źródłowy i przejdź do niego.

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

Następnie utwórz plik main.py o tej zawartości:

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

Następnie utwórz plik requirements.txt o tej zawartości:

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

4. Testowanie usługi lokalnie

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

Teraz przetestuj agenta w innym terminalu:

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

Serwer powinien odpowiedzieć: {"response":"The spreadsheet at Sheet1!A1 has been updated with the value \"hello world\"."}

5. Wdrożenie w Cloud Run

Teraz, gdy wiesz, że Twoje konto usługi ma odpowiednie uprawnienia dostępu do arkusza kalkulacyjnego, wdrożysz usługę w Cloud Run, używając konta usługi jako tożsamości usługi.

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

Gdy wdrożenie się zakończy, wyślij prośbę do usługi 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"}'

Powinna pojawić się odpowiedź {"response":"OK. I've updated cell A1 in Sheet1 with \"hello world\"."}.

Teraz otwórz arkusz Google. W pierwszej komórce zobaczysz wartość „hello world”.

6. Gratulacje!

Gratulujemy ukończenia ćwiczenia!

Co dalej?

Aby rozszerzyć możliwości agenta, zalecamy zapoznanie się z tymi dokumentami:

Poznaj zaawansowane przepływy pracy agenta za pomocą Google Agent Development Kit (ADK)
Dowiedz się więcej o sprawdzonych metodach tworzenia rozwiązań AI w Cloud Run.
Dowiedz się, jak bezpiecznie uwierzytelniać się w Google Cloud APIs z Cloud Run.

Omówione zagadnienia

Jak skonfigurować domyślne uwierzytelnianie aplikacji (ADC) w środowisku lokalnym
Jak utworzyć agenta ADK, który może odczytywać i zapisywać dane w Arkuszach Google
Jak wdrożyć agenta w Cloud Run

7. Zwalnianie miejsca

Aby uniknąć przypadkowych opłat (np. jeśli ta funkcja Cloud Run zostanie przypadkowo wywołana więcej razy niż miesięczny limit wywołań Cloud Run w bezpłatnej wersji), możesz usunąć usługę Cloud Run lub projekt.

Aby usunąć usługę Cloud Run, otwórz Cloud Run w Cloud Console pod adresem https://console.cloud.google.com/run/ i usuń usługę local-adk-sheets-codelab utworzoną w tym ćwiczeniu.

Jeśli chcesz usunąć cały projekt, otwórz https://console.cloud.google.com/cloud-resource-manager, wybierz projekt utworzony w kroku 2 i kliknij Usuń. Jeśli usuniesz projekt, musisz zmienić projekty w Cloud SDK. Listę wszystkich dostępnych projektów możesz wyświetlić, uruchamiając polecenie gcloud projects list.