Come eseguire test locali di un agente ADK che scrive in un foglio Google prima del deployment in Cloud Run

1. Introduzione

Panoramica

In questo post, creerai un agente Gemini utilizzando Google Agent Development Kit (ADK) e FastAPI. Prima del deployment, configurerai le Credenziali predefinite dell'applicazione (ADC) per eseguire test in locale utilizzando lo stesso service account dell'identità del servizio Cloud Run.

Per comunicare con Fogli Google, la tua applicazione ha bisogno di un token di accesso OAuth con l'ambito appropriato per accedere al foglio di lavoro. Scoprirai come ottenere questo token di accesso quando esegui l'applicazione in locale e su Cloud Run con ADC:

• In locale: ADC trova le credenziali, come generate dal comando gcloud auth application-default. Puoi trovare ulteriori informazioni qui
• Su Cloud Run: ADC utilizza il server dei metadati per ottenere le credenziali. Puoi trovare ulteriori informazioni qui.

Nota sulla terminologia:

Potresti avere più familiarità con i termini "assumere un'identità" o "assumere le stesse autorizzazioni". In Google Cloud, la simulazione dell'identità di un service account consente a un'entità autenticata di accedere a tutto ciò a cui il service account può accedere. Solo le entità autenticate con le autorizzazioni appropriate possono simulare l'identità dei service account. Puoi leggere ulteriori informazioni qui: https://docs.cloud.google.com/iam/docs/service-account-overview#impersonation

Cosa imparerai a fare

• Come configurare le Credenziali predefinite dell'applicazione (ADC) per il tuo ambiente locale
• Come creare un agente ADK in grado di leggere e scrivere in un foglio Google
• Come eseguire il deployment dell'agente su Cloud Run

2. Configurazione e requisiti

Prerequisiti

• Hai eseguito l'accesso a Cloud Console.
• In precedenza hai eseguito il deployment di un servizio Cloud Run. Ad esempio, puoi seguire la procedura per eseguire il deployment di un servizio Cloud Run per iniziare.

Imposta le variabili di ambiente

Puoi impostare le variabili di ambiente che verranno utilizzate durante questo codelab.

Puoi trovare l'ID del foglio nell'URL del foglio Google quando copi il link di condivisione, ad esempio 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

Abilita le API Google Cloud richieste

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

Crea service account

Innanzitutto, crea il service account con il comando seguente.

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

Poi, assegna il ruolo Utente Vertex AI al service account (necessario per i modelli Gemini su Vertex AI)

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

Concedi alla tua identità gcloud l'autorizzazione a simulare l'identità del service account (necessario per lo sviluppo locale). Puoi visualizzare le tue identità gcloud eseguendo 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

Nota: infine, dovrai concedere al tuo service account l'accesso come Editor al foglio, proprio come se condividessi un foglio Google con un collega.

1. Apri il foglio Google nel browser.
2. Fai clic sul pulsante Condividi.
3. Incolla l'indirizzo email del service account $SERVICE_ACCOUNT_EMAIL e concedigli l'accesso come Editor.

3. Crea l'app

Innanzitutto, crea una directory per il codice sorgente e passa a questa directory.

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

Poi, crea un file main.py con i seguenti contenuti:

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

Poi, crea un file requirements.txt con i seguenti contenuti:

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

4. Testa il servizio in locale

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

Ora, testa l'agente da un altro terminale:

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

Il server dovrebbe rispondere: {"response":"The spreadsheet at Sheet1!A1 has been updated with the value \"hello world\"."}

Nota: assicurati di eliminare il valore "hello world" dal foglio di lavoro prima di eseguire il test da Cloud Run, in modo da sapere che funziona da Cloud Run.

5. Esegui il deployment in Cloud Run

Ora che sai che il tuo service account dispone delle autorizzazioni appropriate per accedere al foglio di lavoro, eseguirai il deployment su Cloud Run utilizzando il service account come identità del servizio.

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

Al termine del deployment, invia un prompt al tuo servizio 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"}'

Dovresti ricevere una risposta di {"response":"OK. I've updated cell A1 in Sheet1 with \"hello world\"."}

Ora apri il foglio Google. Nella prima cella vedrai il valore "hello world".

6. Complimenti!

Complimenti per aver completato il codelab.

Passaggi successivi

Ti consigliamo di esplorare la seguente documentazione per espandere le funzionalità del tuo agente:

• Esplora i flussi di lavoro avanzati degli agenti utilizzando il Google Agent Development Kit (ADK)
• Scopri di più sulle best practice per la creazione di soluzioni AI su Cloud Run.
• Scopri come eseguire l'autenticazione in modo sicuro alle API Google Cloud da Cloud Run.

Argomenti trattati

• Come configurare le Credenziali predefinite dell'applicazione (ADC) per il tuo ambiente locale
• Come creare un agente ADK in grado di leggere e scrivere in un foglio Google
• Come eseguire il deployment dell'agente su Cloud Run

7. Libera spazio

Per evitare addebiti involontari (ad esempio, se questa funzione Cloud Run viene richiamata inavvertitamente più volte rispetto a alla tua allocazione mensile di richiami di Cloud Run nel livello senza costi), puoi eliminare il servizio Cloud Run o il progetto.

Per eliminare un servizio Cloud Run, vai a Cloud Run nella console Google Cloud all'indirizzo https://console.cloud.google.com/run/ ed elimina il servizio local-adk-sheets-codelab che hai creato in questo codelab.

Se scegli di eliminare l'intero progetto, puoi andare all'indirizzo https://console.cloud.google.com/cloud-resource-manager, selezionare il progetto creato nel passaggio 2 e scegliere Elimina. Se elimini il progetto, dovrai cambiare progetto in Cloud SDK. Puoi visualizzare l'elenco di tutti i progetti disponibili eseguendo gcloud projects list.