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

Tester en local un agent ADK qui écrit dans une feuille de calcul Google avant de le déployer sur Cloud Run

1. Introduction

Présentation

Dans cet article, vous allez créer un agent Gemini à l'aide de Google Agent Development Kit (ADK) et de FastAPI. Avant le déploiement, vous configurerez les identifiants par défaut de l'application (ADC) pour effectuer des tests en local à l'aide du même compte de service que l'identité du service Cloud Run.

Pour communiquer avec Google Sheets, votre application a besoin d'un jeton d'accès OAuth avec le champ d'application approprié pour accéder à la feuille de calcul. Vous apprendrez à obtenir ce jeton d'accès lorsque vous exécutez l'application en local et sur Cloud Run avec les identifiants par défaut de l'application :

En local : les identifiants par défaut de l'application trouvent les identifiants générés par la commande gcloud auth application-default. Pour en savoir plus, cliquez ici.
Sur Cloud Run : les identifiants par défaut de l'application utilisent le serveur de métadonnées pour obtenir les identifiants. Pour en savoir plus, cliquez ici.

Remarque sur la terminologie :

Vous connaissez peut-être mieux les termes "emprunter une identité" ou "emprunter les mêmes autorisations". Dans Google Cloud, emprunter l'identité d'un compte de service permet à un compte principal authentifié d'accéder à ce que le compte de service peut accéder. Seuls les comptes principaux authentifiés disposant des autorisations appropriées peuvent emprunter l'identité des comptes de service. Pour en savoir plus, consultez https://docs.cloud.google.com/iam/docs/service-account-overview#impersonation.

Points abordés

Configurer les identifiants par défaut de l'application pour votre environnement local
Créer un agent ADK capable de lire et d'écrire dans une feuille de calcul Google Sheets
Déployer l'agent sur Cloud Run

2. Préparation

Prérequis

Vous êtes connecté à la console Cloud.
Vous avez déjà déployé un service Cloud Run. Par exemple, vous pouvez suivre la procédure de déploiement d'un service Cloud Run pour commencer.

Définir des variables d'environnement

Vous pouvez définir des variables d'environnement qui seront utilisées tout au long de cet atelier de programmation.

Vous trouverez l'ID de votre feuille dans l'URL de votre feuille Google lorsque vous copiez le lien de partage, par exemple 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

Activer les API Google Cloud requises

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

Créer un compte de service

Commencez par créer le compte de service à l'aide de la commande suivante.

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

Ensuite, attribuez le rôle Utilisateur Vertex AI au compte de service (nécessaire pour les modèles Gemini sur Vertex AI).

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

Accordez à votre identité gcloud l'autorisation d'emprunter l'identité du compte de service (nécessaire pour le développement local). Vous pouvez afficher vos identités gcloud en exécutant 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

Ouvrez la feuille Google dans le navigateur.
Cliquez sur le bouton Partager.
Collez l'adresse e-mail du compte de service $SERVICE_ACCOUNT_EMAIL et accordez-lui un accès Éditeur.

3. Créer l'application

Commencez par créer un répertoire pour le code source, puis accédez à ce répertoire.

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

Ensuite, créez un fichier main.py avec le contenu suivant :

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

Créez ensuite un fichier requirements.txt avec le contenu suivant :

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

4. Tester le service en local

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

Testez maintenant votre agent à partir d'un autre 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"}'

Le serveur doit répondre : {"response":"The spreadsheet at Sheet1!A1 has been updated with the value \"hello world\"."}

5. Déployer dans Cloud Run

Maintenant que vous savez que votre compte de service dispose des autorisations appropriées pour accéder à la feuille de calcul, vous allez le déployer sur Cloud Run en utilisant le compte de service comme identité de service.

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

Une fois le déploiement terminé, envoyez une invite à votre service 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"}'

Vous devriez recevoir une réponse de type {"response":"OK. I've updated cell A1 in Sheet1 with \"hello world\"."}.

Ouvrez maintenant votre feuille Google. La valeur "hello world" s'affiche dans la première cellule.

6. Félicitations !

Bravo ! Vous avez terminé cet atelier de programmation.

Et ensuite ?

Nous vous recommandons de consulter la documentation suivante pour étendre les capacités de votre agent :

Découvrez les workflows d'agent avancés à l'aide de Google Agent Development Kit (ADK).
Découvrez les bonnes pratiques pour créer des solutions d'IA sur Cloud Run.
Découvrez comment vous authentifier de manière sécurisée auprès des API Google Cloud à partir de Cloud Run.

Points abordés

Configurer les identifiants par défaut de l'application pour votre environnement local
Créer un agent ADK capable de lire et d'écrire dans une feuille de calcul Google Sheets
Déployer l'agent sur Cloud Run

7. Libérer de l'espace

Pour éviter des frais involontaires (par exemple, si cette fonction Cloud Run est appelée par inadvertance plus de fois que votre allocation mensuelle d'appels Cloud Run dans le niveau sans frais), vous pouvez supprimer le service Cloud Run ou le projet.

Pour supprimer un service Cloud Run, accédez à Cloud Run dans la console Cloud à l'adresse https://console.cloud.google.com/run/, puis supprimez le service local-adk-sheets-codelab que vous avez créé dans cet atelier de programmation.

Si vous choisissez de supprimer l'intégralité du projet, accédez à https://console.cloud.google.com/cloud-resource-manager, sélectionnez le projet que vous avez créé à l'étape 2, puis choisissez "Supprimer". Si vous supprimez le projet, vous devrez modifier les projets dans votre Cloud SDK. Vous pouvez afficher la liste de tous les projets disponibles en exécutant gcloud projects list.