Como fazer testes locais de um agente do ADK que grava em uma planilha Google antes da implantação no Cloud Run

1. Introdução

Visão geral

Nesta postagem, você vai criar um agente do Gemini usando o Kit de Desenvolvimento de Agente (ADK) do Google e o FastAPI. Antes da implantação, configure as Application Default Credentials (ADC) para testar localmente usando a mesma conta de serviço que a identidade do serviço do Cloud Run.

Para se comunicar com as Planilhas Google, seu aplicativo precisa de um token de acesso OAuth com o escopo adequado para acessar a planilha. Você vai aprender a receber esse token de acesso ao executar localmente e no Cloud Run com ADC:

  • Localmente:o ADC encontra as credenciais, conforme gerado pelo comando gcloud auth application-default. Saiba mais
  • No Cloud Run:o ADC usa o servidor de metadados para receber credenciais. Saiba mais.

Observação sobre a terminologia:

Talvez você esteja mais familiarizado com os termos "assumir uma identidade" ou "assumir as mesmas permissões". No Google Cloud, a representação de uma conta de serviço permite que um principal autenticado acesse tudo o que ela pode acessar. Somente os principais autenticados com as permissões apropriadas podem representar contas de serviço. Saiba mais aqui: https://docs.cloud.google.com/iam/docs/service-account-overview#impersonation

O que você vai aprender

  • Como configurar o Application Default Credentials (ADC) para seu ambiente local
  • Como criar um agente do ADK que pode ler e gravar em uma planilha Google
  • Como implantar o agente no Cloud Run

2. Configuração e requisitos

Pré-requisitos

  • Você fez login no console do Cloud.
  • Você já implantou um serviço do Cloud Run. Por exemplo, siga as etapas para implantar um serviço do Cloud Run e começar.

Definir variáveis de ambiente

É possível definir variáveis de ambiente que serão usadas ao longo deste codelab.

Você pode encontrar o ID da planilha no URL dela ao copiar o link de compartilhamento, por exemplo, 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

Ativar as APIs obrigatórias do Google Cloud

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

Criar a conta de serviço

Primeiro, crie a conta de serviço com o seguinte comando.

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

Em seguida, conceda o papel de usuário da Vertex AI à conta de serviço (necessário para modelos do Gemini na Vertex AI).

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

Conceda à sua identidade da gcloud permissão para representar a conta de serviço (necessária para o desenvolvimento local). Para ver suas identidades da gcloud, execute 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
  1. Abra a planilha Google no navegador.
  2. Clique no botão "Compartilhar".
  3. Cole o e-mail da conta de serviço $SERVICE_ACCOUNT_EMAIL e conceda acesso de editor a ela.

3. Criar o app

Primeiro, crie um diretório para o código-fonte e use o comando "cd" para acessar esse diretório.

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

Em seguida, crie um arquivo main.py com o seguinte conteúdo:

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

Em seguida, crie um arquivo requirements.txt com o seguinte conteúdo:

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

4. Testar o serviço localmente 

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

Agora, teste o agente em outro 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"}'

O servidor deve responder: {"response":"The spreadsheet at Sheet1!A1 has been updated with the value \"hello world\"."}

5. Implantar no Cloud Run

Agora que você sabe que sua conta de serviço tem as permissões adequadas para acessar a planilha, implante no Cloud Run usando a conta de serviço como identidade do serviço.

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

Quando a implantação terminar, envie um comando para o serviço do 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"}'

Você vai receber uma resposta de {"response":"OK. I've updated cell A1 in Sheet1 with \"hello world\"."}

Agora abra a planilha Google. O valor "hello world" vai aparecer na primeira célula.

6. Parabéns!

Parabéns por concluir o codelab!

Qual é a próxima etapa?

Recomendamos consultar a seguinte documentação para ampliar os recursos do seu agente:

O que vimos

  • Como configurar o Application Default Credentials (ADC) para seu ambiente local
  • Como criar um agente do ADK que pode ler e gravar em uma planilha Google
  • Como implantar o agente no Cloud Run

7. Limpar

Para evitar cobranças acidentais, por exemplo, se essa função do Cloud Run for invocada mais vezes do que sua alocação mensal de invocações do Cloud Run no nível sem custo financeiro, exclua o serviço do Cloud Run ou o projeto.

Para excluir um serviço do Cloud Run, acesse o Cloud Run no console do Cloud em https://console.cloud.google.com/run/ e exclua o serviço local-adk-sheets-codelab que você criou neste codelab.

Se você quiser excluir todo o projeto, acesse https://console.cloud.google.com/cloud-resource-manager, selecione o projeto criado na etapa 2 e escolha "Excluir". Se você excluir o projeto, vai precisar mudar de projeto no SDK Cloud. Para conferir a lista de todos os projetos disponíveis, execute gcloud projects list.