Lokale Tests eines ADK-Agents durchführen, der in ein Google-Tabellenblatt schreibt, bevor er in Cloud Run bereitgestellt wird

1. Einführung

Übersicht

In diesem Beitrag erstellen Sie einen Gemini-Agenten mit dem Google Agent Development Kit (ADK) und FastAPI. Vor der Bereitstellung konfigurieren Sie Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC), um lokal mit demselben Dienstkonto wie der Cloud Run-Dienstidentität zu testen.

Für die Kommunikation mit Google Sheets benötigt Ihre Anwendung ein OAuth-Zugriffstoken mit dem entsprechenden Bereich für den Zugriff auf die Tabelle. Sie erfahren, wie Sie dieses Zugriffstoken bei lokaler Ausführung und in Cloud Run mit ADC abrufen:

• Lokal:ADC findet die Anmeldedaten, die vom Befehl gcloud auth application-default generiert wurden. Weitere Informationen
• In Cloud Run:ADC ruft Anmeldedaten über den Metadatenserver ab. Weitere Informationen

Hinweis zur Terminologie:

Vielleicht sind Ihnen die Begriffe „Identität annehmen“ oder „dieselben Berechtigungen annehmen“ vertrauter. Wenn in Google Cloud die Identität eines Dienstkontos übernommen wird, kann ein authentifiziertes Hauptkonto auf alles zugreifen, worauf das Dienstkonto Zugriff hat. Nur authentifizierte Hauptkonten mit den entsprechenden Berechtigungen können die Identität von Dienstkonten übernehmen. Weitere Informationen finden Sie unter https://docs.cloud.google.com/iam/docs/service-account-overview#impersonation.

Lerninhalte

• Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) für Ihre lokale Umgebung konfigurieren
• Einen ADK-Agenten erstellen, der Daten in einer Google-Tabelle lesen und schreiben kann
• Agent in Cloud Run bereitstellen

2. Einrichtung und Anforderungen

Voraussetzungen

• Sie sind in der Cloud Console angemeldet.
• Sie haben bereits einen Cloud Run-Dienst bereitgestellt. Cloud Run-Dienst bereitstellen

Umgebungsvariablen festlegen

Sie können Umgebungsvariablen festlegen, die in diesem Codelab verwendet werden.

Sie finden die Tabellen-ID in der URL Ihrer Google-Tabelle, wenn Sie den Freigabelink kopieren, z.B. 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

Erforderliche Google Cloud APIs aktivieren

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

Dienstkonto erstellen

Erstellen Sie zuerst das Dienstkonto mit dem folgenden Befehl.

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

Weisen Sie als Nächstes dem Dienstkonto die Rolle „Vertex AI User“ zu (erforderlich für Gemini-Modelle in Vertex AI).

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

Gewähren Sie Ihrer gcloud-Identität die Berechtigung, die Identität des Dienstkontos zu übernehmen (für die lokale Entwicklung erforderlich). Sie können Ihre gcloud-Identitäten mit dem Befehl gcloud auth list aufrufen.

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

Hinweis:Schließlich müssen Sie Ihrem Dienstkonto Bearbeiterzugriff auf Ihr Tabellenblatt gewähren, so wie Sie ein Google-Tabellenblatt für einen Kollegen freigeben würden.

1. Öffnen Sie die Google-Tabelle im Browser.
2. Klicken Sie auf die Schaltfläche „Teilen“.
3. Fügen Sie die E-Mail-Adresse des Dienstkontos $SERVICE_ACCOUNT_EMAIL ein und gewähren Sie ihr Bearbeiterzugriff.

3. Anwendung erstellen

Erstellen Sie zuerst ein Verzeichnis für den Quellcode und wechseln Sie in dieses Verzeichnis.

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

Erstellen Sie dann eine main.py-Datei mit folgendem Inhalt:

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

Erstellen Sie als Nächstes eine requirements.txt-Datei mit folgendem Inhalt:

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

4. Dienst lokal testen

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

Testen Sie den Agent jetzt über ein anderes Terminal:

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

Der Server sollte mit {"response":"The spreadsheet at Sheet1!A1 has been updated with the value \"hello world\"."} antworten.

Hinweis:Löschen Sie den „Hello World“-Wert aus Ihrer Tabelle, bevor Sie den Test in Cloud Run durchführen. So können Sie sicher sein, dass die Funktion in Cloud Run funktioniert.

5. In Cloud Run bereitstellen

Nachdem Sie nun wissen, dass Ihr Dienstkonto die entsprechenden Berechtigungen für den Zugriff auf die Tabelle hat, stellen Sie die Anwendung in Cloud Run bereit und verwenden das Dienstkonto als Dienstidentität.

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

Wenn die Bereitstellung abgeschlossen ist, senden Sie einen Prompt an Ihren Cloud Run-Dienst.

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

Sie sollten die Antwort {"response":"OK. I've updated cell A1 in Sheet1 with \"hello world\"."} erhalten.

Öffnen Sie jetzt Ihre Google-Tabelle. In der ersten Zelle sehen Sie den Wert „hello world“.

6. Glückwunsch!

Herzlichen Glückwunsch zum Abschluss des Codelabs!

Nächste Schritte

Wir empfehlen Ihnen, sich die folgende Dokumentation anzusehen, um die Funktionen Ihres Agents zu erweitern:

• Erstellen Sie mit dem Google Agent Development Kit (ADK) komplexe Agent-Workflows.
• Weitere Best Practices für das Erstellen von KI-Lösungen in Cloud Run
• Sichere Authentifizierung bei Google Cloud APIs über Cloud Run

Behandelte Themen

• Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) für Ihre lokale Umgebung konfigurieren
• Einen ADK-Agenten erstellen, der Daten in einer Google-Tabelle lesen und schreiben kann
• Agent in Cloud Run bereitstellen

7. Bereinigen

Um unbeabsichtigte Gebühren zu vermeiden (z. B. wenn diese Cloud Run-Funktion versehentlich öfter aufgerufen wird als Ihre monatliche Cloud Run-Aufrufkontingent im kostenlosen Kontingent), können Sie entweder den Cloud Run-Dienst oder das Projekt löschen.

Wenn Sie einen Cloud Run-Dienst löschen möchten, rufen Sie in der Cloud Console https://console.cloud.google.com/run/ auf und löschen Sie den Dienst local-adk-sheets-codelab, den Sie in diesem Codelab erstellt haben.

Wenn Sie das gesamte Projekt löschen möchten, rufen Sie https://console.cloud.google.com/cloud-resource-manager auf, wählen Sie das Projekt aus, das Sie in Schritt 2 erstellt haben, und klicken Sie auf „Löschen“. Wenn Sie das Projekt löschen, müssen Sie das Projekt in Ihrem Cloud SDK ändern. Sie können die Liste aller verfügbaren Projekte mit gcloud projects list aufrufen.