1. Introduzione
Il potenziale dell'utilizzo dell'AI generativa per la creazione di piani di test deriva dalla sua capacità di risolvere due delle maggiori sfide della garanzia di qualità moderna: velocità e completezza. Nei rapidi cicli Agile e DevOps di oggi, la creazione manuale di piani di test dettagliati rappresenta un collo di bottiglia significativo, che ritarda l'intero processo di test. Un agente basato sull'IA generativa può acquisire storie utente e requisiti tecnici per produrre un piano di test completo in pochi minuti, non giorni, garantendo che il processo di controllo qualità sia al passo con lo sviluppo. Inoltre, l'AI eccelle nell'identificazione di scenari complessi, casi limite e percorsi negativi che un essere umano potrebbe trascurare, il che porta a una copertura dei test notevolmente migliorata e a una riduzione significativa dei bug che sfuggono alla produzione.
In questo codelab esploreremo come creare un agente in grado di recuperare i documenti dei requisiti di prodotto da Confluence e di fornire feedback costruttivi, nonché di generare un piano di test completo che può essere esportato in un file CSV.
Nel codelab, seguirai un approccio passo passo come segue:
- Prepara il progetto Google Cloud e abilita tutte le API richieste
- Configurare lo spazio di lavoro per l'ambiente di programmazione
- Preparazione di mcp-server locale per Confluence
- Strutturare il codice sorgente, il prompt e gli strumenti dell'agente ADK per connettersi al server MCP
- Informazioni sull'utilizzo dei contesti di Artifact Service e degli strumenti
- Test dell'agente utilizzando l'interfaccia utente di sviluppo web locale di ADK
- Gestisci le variabili di ambiente e configura i file richiesti necessari per eseguire il deployment dell'applicazione in Cloud Run
- Esegui il deployment dell'applicazione in Cloud Run
Panoramica dell'architettura
Prerequisiti
- Avere familiarità con Python
- Conoscenza dell'architettura full-stack di base che utilizza il servizio HTTP
Cosa imparerai a fare
- Progettazione dell'agente ADK utilizzando le sue diverse funzionalità
- Utilizzo dello strumento con lo strumento personalizzato e MCP
- Configurazione dell'output dei file per agente utilizzando Artifact Service Management
- Utilizzo di BuiltInPlanner per migliorare l'esecuzione delle attività eseguendo la pianificazione con le funzionalità di ragionamento di Gemini 2.5 Flash
- Interazione e debug tramite l'interfaccia web dell'ADK
- Esegui il deployment dell'applicazione in Cloud Run utilizzando Dockerfile e fornisci le variabili di ambiente
Che cosa ti serve
- Browser web Chrome
- Un account Gmail
- Un progetto cloud con fatturazione abilitata
- (Facoltativo) Spazio Confluence con pagine dei documenti dei requisiti del prodotto
Questo codelab, progettato per sviluppatori di tutti i livelli (inclusi i principianti), utilizza Python nella sua applicazione di esempio. Tuttavia, la conoscenza di Python non è necessaria per comprendere i concetti presentati. Non preoccuparti dello spazio Confluence se non ne hai uno, ti forniremo le credenziali per provare questo codelab
2. Prima di iniziare
Seleziona il progetto attivo in Cloud Console
Questo codelab presuppone che tu abbia già un progetto Google Cloud con la fatturazione abilitata. Se non l'hai ancora fatto, puoi seguire le istruzioni riportate di seguito per iniziare.
- Nella console Google Cloud, nella pagina di selezione del progetto, seleziona o crea un progetto Google Cloud.
- Verifica che la fatturazione sia attivata per il tuo progetto Cloud. Scopri come verificare se la fatturazione è abilitata per un progetto.
Configura il progetto cloud nel terminale Cloud Shell
- Utilizzerai Cloud Shell, un ambiente a riga di comando in esecuzione in Google Cloud. Fai clic su Attiva Cloud Shell nella parte superiore della console Google Cloud.
- Una volta eseguita la connessione a Cloud Shell, verifica di essere già autenticato e che il progetto sia impostato sul tuo ID progetto utilizzando il seguente comando:
gcloud auth list
- Esegui questo comando in Cloud Shell per verificare che il comando gcloud conosca il tuo progetto.
gcloud config list project
- Se il progetto non è impostato, utilizza il seguente comando per impostarlo:
gcloud config set project <YOUR_PROJECT_ID>
In alternativa, puoi anche visualizzare l'ID PROJECT_ID nella console.
Fai clic e vedrai tutti i tuoi progetti e l'ID progetto sul lato destro.
- Abilita le API richieste tramite il comando mostrato di seguito. L'operazione potrebbe richiedere alcuni minuti.
gcloud services enable aiplatform.googleapis.com \
run.googleapis.com \
cloudbuild.googleapis.com \
cloudresourcemanager.googleapis.com
Se il comando viene eseguito correttamente, dovresti visualizzare un messaggio simile a quello mostrato di seguito:
Operation "operations/..." finished successfully.
L'alternativa al comando gcloud è tramite la console, cercando ogni prodotto o utilizzando questo link.
Se manca un'API, puoi sempre abilitarla durante l'implementazione.
Consulta la documentazione per i comandi e l'utilizzo di gcloud.
Vai all'editor di Cloud Shell e configura la directory di lavoro dell'applicazione
Ora possiamo configurare l'editor di codice per svolgere alcune attività di programmazione. Per questo utilizzeremo l'editor di Cloud Shell
- Fai clic sul pulsante Apri editor per aprire un editor di Cloud Shell in cui puoi scrivere il codice
- Assicurati che il progetto Cloud Code sia impostato nell'angolo in basso a sinistra (barra di stato) dell'editor di Cloud Shell, come evidenziato nell'immagine seguente, e che sia impostato sul progetto Google Cloud attivo in cui hai attivato la fatturazione. Autorizza, se richiesto. Se segui già il comando precedente, il pulsante potrebbe anche puntare direttamente al progetto attivato anziché al pulsante di accesso.
- Successivamente, cloniamo la directory di lavoro del modello per questo codelab da GitHub eseguendo il seguente comando. creando la directory di lavoro nella directory qa-test-planner-agent
git clone https://github.com/alphinside/qa-test-planner-agent.git qa-test-planner-agent
- Dopodiché, vai alla sezione superiore dell'editor di Cloud Shell e fai clic su File->Apri cartella, individua la directory username e la directory qa-test-planner-agent, quindi fai clic sul pulsante OK. In questo modo, la directory scelta diventerà la directory di lavoro principale. In questo esempio, il nome utente è alvinprayuda, quindi il percorso della directory è mostrato di seguito
Ora, l'editor di Cloud Shell dovrebbe avere il seguente aspetto
Configurazione dell'ambiente
Prepara l'ambiente virtuale Python
Il passaggio successivo consiste nel preparare l'ambiente di sviluppo. Il terminale attivo corrente deve trovarsi nella directory di lavoro qa-test-planner-agent. In questo codelab utilizzeremo Python 3.12 e uv python project manager per semplificare la necessità di creare e gestire la versione di Python e l'ambiente virtuale.
- Se non hai ancora aperto il terminale, aprilo facendo clic su Terminale -> Nuovo terminale o utilizza Ctrl + Maiusc + C, che aprirà una finestra del terminale nella parte inferiore del browser.
- Scarica
uve installa Python 3.12 con il seguente comando
curl -LsSf https://astral.sh/uv/0.7.19/install.sh | sh && \
source $HOME/.local/bin/env && \
uv python install 3.12
- Ora inizializziamo l'ambiente virtuale utilizzando
uv. Esegui questo comando
uv sync --frozen
Verrà creata la directory .venv e verranno installate le dipendenze. Una rapida occhiata al file pyproject.toml ti fornirà informazioni sulle dipendenze visualizzate in questo modo
dependencies = [
"google-adk>=1.5.0",
"mcp-atlassian>=0.11.9",
"pandas>=2.3.0",
"python-dotenv>=1.1.1",
]
- Per testare l'ambiente virtuale, crea un nuovo file main.py e copia il seguente codice
def main():
print("Hello from qa-test-planner-agent")
if __name__ == "__main__":
main()
- Quindi, esegui questo comando:
uv run main.py
Riceverai un output simile a quello mostrato di seguito.
Using CPython 3.12 Creating virtual environment at: .venv Hello from qa-test-planner-agent!
Ciò dimostra che il progetto Python è in fase di configurazione corretta.
Ora possiamo passare al passaggio successivo, ovvero creare l'agente e poi i servizi
3. Crea l'agente utilizzando Google ADK e Gemini 2.5
Introduzione alla struttura delle directory ADK
Iniziamo esplorando cosa offre l'ADK e come creare l'agente. La documentazione completa dell'ADK è disponibile in questo URL . L'ADK ci offre molte utilità all'interno dell'esecuzione dei comandi della CLI. Alcuni di questi sono :
- Configura la struttura delle directory dell'agente
- Prova rapidamente l'interazione tramite l'input e l'output della CLI
- Configura rapidamente l'interfaccia web dell'interfaccia utente di sviluppo locale
Ora creiamo la struttura delle directory dell'agente utilizzando il comando CLI. Esegui questo comando
uv run adk create qa_test_planner \
--model gemini-2.5-flash \
--project {your-project-id} \
--region global
Verrà creata la seguente struttura di directory dell'agente nella directory di lavoro corrente
qa_test_planner/ ├── __init__.py ├── .env ├── agent.py
Se ispezioni i file init.py e agent.py, vedrai questo codice
# __init__.py
from . import agent
# agent.py
from google.adk.agents import Agent
root_agent = Agent(
model='gemini-2.5-flash',
name='root_agent',
description='A helpful assistant for user questions.',
instruction='Answer user questions to the best of your knowledge',
)
Creazione dell'agente di pianificazione dei test QA
Creiamo il nostro agente di pianificazione dei test QA. Apri il file qa_test_planner/agent.py e copia il codice riportato di seguito, che conterrà root_agent.
# qa_test_planner/agent.py
from google.adk.agents import Agent
from google.adk.tools.mcp_tool.mcp_toolset import (
MCPToolset,
StdioConnectionParams,
StdioServerParameters,
)
from google.adk.planners import BuiltInPlanner
from google.genai import types
from dotenv import load_dotenv
import os
from pathlib import Path
from pydantic import BaseModel
from typing import Literal
import tempfile
import pandas as pd
from google.adk.tools import ToolContext
load_dotenv(dotenv_path=Path(__file__).parent / ".env")
confluence_tool = MCPToolset(
connection_params=StdioConnectionParams(
server_params=StdioServerParameters(
command="uvx",
args=[
"mcp-atlassian",
f"--confluence-url={os.getenv('CONFLUENCE_URL')}",
f"--confluence-username={os.getenv('CONFLUENCE_USERNAME')}",
f"--confluence-token={os.getenv('CONFLUENCE_TOKEN')}",
"--enabled-tools=confluence_search,confluence_get_page,confluence_get_page_children",
],
env={},
),
timeout=60,
),
)
class TestPlan(BaseModel):
test_case_key: str
test_type: Literal["manual", "automatic"]
summary: str
preconditions: str
test_steps: str
expected_result: str
associated_requirements: str
async def write_test_tool(
prd_id: str, test_cases: list[dict], tool_context: ToolContext
):
"""A tool to write the test plan into file
Args:
prd_id: Product requirement document ID
test_cases: List of test case dictionaries that should conform to these fields:
- test_case_key: str
- test_type: Literal["manual","automatic"]
- summary: str
- preconditions: str
- test_steps: str
- expected_result: str
- associated_requirements: str
Returns:
A message indicating success or failure of the validation and writing process
"""
validated_test_cases = []
validation_errors = []
# Validate each test case
for i, test_case in enumerate(test_cases):
try:
validated_test_case = TestPlan(**test_case)
validated_test_cases.append(validated_test_case)
except Exception as e:
validation_errors.append(f"Error in test case {i + 1}: {str(e)}")
# If validation errors exist, return error message
if validation_errors:
return {
"status": "error",
"message": "Validation failed",
"errors": validation_errors,
}
# Write validated test cases to CSV
try:
# Convert validated test cases to a pandas DataFrame
data = []
for tc in validated_test_cases:
data.append(
{
"Test Case ID": tc.test_case_key,
"Type": tc.test_type,
"Summary": tc.summary,
"Preconditions": tc.preconditions,
"Test Steps": tc.test_steps,
"Expected Result": tc.expected_result,
"Associated Requirements": tc.associated_requirements,
}
)
# Create DataFrame from the test case data
df = pd.DataFrame(data)
if not df.empty:
# Create a temporary file with .csv extension
with tempfile.NamedTemporaryFile(suffix=".csv", delete=False) as temp_file:
# Write DataFrame to the temporary CSV file
df.to_csv(temp_file.name, index=False)
temp_file_path = temp_file.name
# Read the file bytes from the temporary file
with open(temp_file_path, "rb") as f:
file_bytes = f.read()
# Create an artifact with the file bytes
await tool_context.save_artifact(
filename=f"{prd_id}_test_plan.csv",
artifact=types.Part.from_bytes(data=file_bytes, mime_type="text/csv"),
)
# Clean up the temporary file
os.unlink(temp_file_path)
return {
"status": "success",
"message": (
f"Successfully wrote {len(validated_test_cases)} test cases to "
f"CSV file: {prd_id}_test_plan.csv"
),
}
else:
return {"status": "warning", "message": "No test cases to write"}
except Exception as e:
return {
"status": "error",
"message": f"An error occurred while writing to CSV: {str(e)}",
}
root_agent = Agent(
model="gemini-2.5-flash",
name="qa_test_planner_agent",
description="You are an expert QA Test Planner and Product Manager assistant",
instruction=f"""
Help user search any product requirement documents on Confluence. Furthermore you also can provide the following capabilities when asked:
- evaluate product requirement documents and assess it, then give expert input on what can be improved
- create a comprehensive test plan following Jira Xray mandatory field formatting, result showed as markdown table. Each test plan must also have explicit mapping on
which user stories or requirements identifier it's associated to
Here is the Confluence space ID with it's respective document grouping:
- "{os.getenv("CONFLUENCE_PRD_SPACE_ID")}" : space to store Product Requirements Documents
Do not making things up, Always stick to the fact based on data you retrieve via tools.
""",
tools=[confluence_tool, write_test_tool],
planner=BuiltInPlanner(
thinking_config=types.ThinkingConfig(
include_thoughts=True,
thinking_budget=2048,
)
),
)
File di configurazione dell'installazione
Ora dobbiamo aggiungere un'ulteriore configurazione per questo progetto, poiché l'agente avrà bisogno dell'accesso a Confluence
Apri il file qa_test_planner/.env e aggiungi i seguenti valori delle variabili di ambiente. Assicurati che il file .env risultante abbia questo aspetto
GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT={YOUR-CLOUD-PROJECT-ID}
GOOGLE_CLOUD_LOCATION=global
CONFLUENCE_URL={YOUR-CONFLUENCE-DOMAIN}
CONFLUENCE_USERNAME={YOUR-CONFLUENCE-USERNAME}
CONFLUENCE_TOKEN={YOUR-CONFLUENCE-API-TOKEN}
CONFLUENCE_PRD_SPACE_ID={YOUR-CONFLUENCE-SPACE-ID}
Purtroppo, questo spazio Confluence non può essere reso pubblico, quindi puoi esaminare questi file per leggere i documenti sui requisiti di prodotto disponibili, che saranno accessibili utilizzando le credenziali sopra indicate.
Spiegazione del codice
Questo script contiene l'inizializzazione dell'agente, in cui inizializziamo le seguenti operazioni:
- Imposta il modello da utilizzare su
gemini-2.5-flash - Configura gli strumenti MCP di Confluence che comunicheranno tramite Studio
- Configura lo strumento personalizzato
write_test_toolper scrivere il piano di test e scaricare il file CSV nell'artefatto - Configurare la descrizione e le istruzioni dell'agente
- Abilita la pianificazione prima di generare la risposta finale o l'esecuzione utilizzando le funzionalità di pensiero di Gemini 2.5 Flash
L'agente stesso, quando è basato sul modello Gemini con funzionalità di pensiero integrate e configurato con gli argomenti del planner, può mostrare le sue capacità di pensiero e visualizzarle anche nell'interfaccia web. Il codice per configurare questa impostazione è mostrato di seguito.
# qa-test-planner/agent.py
from google.adk.planners import BuiltInPlanner
from google.genai import types
...
# Provide the confluence tool to agent
root_agent = Agent(
model="gemini-2.5-flash",
name="qa_test_planner_agent",
...,
tools=[confluence_tool, write_test_tool],
planner=BuiltInPlanner(
thinking_config=types.ThinkingConfig(
include_thoughts=True,
thinking_budget=2048,
)
),
...
E prima di intraprendere azioni, possiamo vedere il suo processo di pensiero
Lo strumento MCP Confluence
Per connetterci al server MCP da ADK, dobbiamo utilizzare MCPToolSet, che può essere importato dal modulo google.adk.tools.mcp_tool.mcp_toolset. Il codice da inizializzare qui mostrato di seguito ( troncato per efficienza)
# qa-test-planner/agent.py
from google.adk.tools.mcp_tool.mcp_toolset import (
MCPToolset,
StdioConnectionParams,
StdioServerParameters,
)
...
# Initialize the Confluence MCP Tool via Stdio Output
confluence_tool = MCPToolset(
connection_params=StdioConnectionParams(
server_params=StdioServerParameters(
command="uvx",
args=[
"mcp-atlassian",
f"--confluence-url={os.getenv('CONFLUENCE_URL')}",
f"--confluence-username={os.getenv('CONFLUENCE_USERNAME')}",
f"--confluence-token={os.getenv('CONFLUENCE_TOKEN')}",
"--enabled-tools=confluence_search,confluence_get_page,confluence_get_page_children",
],
env={},
),
timeout=60,
),
)
...
# Provide the confluence tool to agent
root_agent = Agent(
model="gemini-2.5-flash",
name="qa_test_planner_agent",
...,
tools=[confluence_tool, write_test_tool],
...
Con questa configurazione, l'agente inizializzerà il server MCP di Confluence come processo separato e gestirà la comunicazione con questi processi tramite Studio I/O. Questo flusso è illustrato nell'immagine dell'architettura MCP seguente, contrassegnata all'interno della casella rossa.
Inoltre, negli argomenti del comando di inizializzazione di MCP, limitiamo anche gli strumenti che possono essere utilizzati solo a questi: confluence_search, confluence_get_page e confluence_get_page_children, che supportano i nostri casi d'uso dell'agente di test QA. Per questo tutorial del codelab, utilizziamo Atlassian MCP Server, un progetto della community ( per ulteriori dettagli, consulta la documentazione completa).
Strumento Scrivi test
Dopo aver ricevuto il contesto dallo strumento Confluence MCP, l'agente può creare il piano di test necessario per l'utente. Tuttavia, vogliamo produrre un file che contenga questo piano di test in modo che possa essere salvato e condiviso con l'altra persona. Per supportare questa funzionalità, forniamo lo strumento personalizzato write_test_tool di seguito.
# qa-test-planner/agent.py
...
async def write_test_tool(
prd_id: str, test_cases: list[dict], tool_context: ToolContext
):
"""A tool to write the test plan into file
Args:
prd_id: Product requirement document ID
test_cases: List of test case dictionaries that should conform to these fields:
- test_case_key: str
- test_type: Literal["manual","automatic"]
- summary: str
- preconditions: str
- test_steps: str
- expected_result: str
- associated_requirements: str
Returns:
A message indicating success or failure of the validation and writing process
"""
validated_test_cases = []
validation_errors = []
# Validate each test case
for i, test_case in enumerate(test_cases):
try:
validated_test_case = TestPlan(**test_case)
validated_test_cases.append(validated_test_case)
except Exception as e:
validation_errors.append(f"Error in test case {i + 1}: {str(e)}")
# If validation errors exist, return error message
if validation_errors:
return {
"status": "error",
"message": "Validation failed",
"errors": validation_errors,
}
# Write validated test cases to CSV
try:
# Convert validated test cases to a pandas DataFrame
data = []
for tc in validated_test_cases:
data.append(
{
"Test Case ID": tc.test_case_key,
"Type": tc.test_type,
"Summary": tc.summary,
"Preconditions": tc.preconditions,
"Test Steps": tc.test_steps,
"Expected Result": tc.expected_result,
"Associated Requirements": tc.associated_requirements,
}
)
# Create DataFrame from the test case data
df = pd.DataFrame(data)
if not df.empty:
# Create a temporary file with .csv extension
with tempfile.NamedTemporaryFile(suffix=".csv", delete=False) as temp_file:
# Write DataFrame to the temporary CSV file
df.to_csv(temp_file.name, index=False)
temp_file_path = temp_file.name
# Read the file bytes from the temporary file
with open(temp_file_path, "rb") as f:
file_bytes = f.read()
# Create an artifact with the file bytes
await tool_context.save_artifact(
filename=f"{prd_id}_test_plan.csv",
artifact=types.Part.from_bytes(data=file_bytes, mime_type="text/csv"),
)
# Clean up the temporary file
os.unlink(temp_file_path)
return {
"status": "success",
"message": (
f"Successfully wrote {len(validated_test_cases)} test cases to "
f"CSV file: {prd_id}_test_plan.csv"
),
}
else:
return {"status": "warning", "message": "No test cases to write"}
except Exception as e:
return {
"status": "error",
"message": f"An error occurred while writing to CSV: {str(e)}",
}
...
La funzione dichiarata sopra serve a supportare le seguenti funzionalità:
- Controlla il piano di test prodotto in modo che sia conforme alle specifiche dei campi obbligatori. La verifica viene eseguita utilizzando il modello Pydantic e, se si verifica un errore, viene restituito il messaggio di errore all'agente
- Esegui il dump del risultato in un file CSV utilizzando la funzionalità pandas
- Il file generato viene quindi salvato come artefatto utilizzando le funzionalità del servizio artefatti, a cui è possibile accedere utilizzando l'oggetto ToolContext, accessibile in ogni chiamata di strumento
Se salviamo i file generati come artefatto, questi verranno contrassegnati come evento nel runtime ADK e potranno essere visualizzati nell'interazione dell'agente in un secondo momento nell'interfaccia web
In questo modo, possiamo configurare dinamicamente la risposta del file dell'agente, da fornire all'utente.
4. Test dell'agente
Ora proviamo a comunicare con l'agente tramite la CLI. Esegui il seguente comando
uv run adk run qa_test_planner
Verrà visualizzato un output simile a questo, in cui puoi chattare a turno con l'agente, ma puoi inviare solo testo tramite questa interfaccia
Log setup complete: /tmp/agents_log/agent.xxxx_xxx.log To access latest log: tail -F /tmp/agents_log/agent.latest.log Running agent qa_test_planner_agent, type exit to exit. user: hello [qa_test_planner_agent]: Hello there! How can I help you today? user:
È bello poter chattare con l'agente tramite CLI. Ma ancora meglio se possiamo fare una bella chat web, e possiamo farlo anche noi. L'ADK ci consente inoltre di disporre di un'interfaccia utente di sviluppo per interagire e ispezionare ciò che accade durante l'interazione. Esegui questo comando per avviare il server dell'interfaccia utente di sviluppo locale
uv run adk web --port 8080
Verrà generato un output simile al seguente esempio, il che significa che possiamo già accedere all'interfaccia web
INFO: Started server process [xxxx] INFO: Waiting for application startup. +-----------------------------------------------------------------------------+ | ADK Web Server started | | | | For local testing, access at http://localhost:8080. | +-----------------------------------------------------------------------------+ INFO: Application startup complete. INFO: Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit)
Ora, per verificarlo, fai clic sul pulsante Anteprima web nella parte superiore di Cloud Shell Editor e seleziona Anteprima sulla porta 8080.
Visualizzerai la seguente pagina web in cui potrai selezionare gli agenti disponibili nel pulsante a discesa in alto a sinistra ( nel nostro caso dovrebbe essere qa_test_planner) e interagire con il bot. Nella finestra a sinistra vedrai molte informazioni sui dettagli del log durante il runtime dell'agente.
Proviamo alcune azioni. Chatta con gli agenti con questi prompt:
- " Elenca tutti i PRD disponibili "
- " Write test plan for Snaprecipe PRD "
Quando utilizzi alcuni strumenti, puoi esaminare cosa sta succedendo nella UI di sviluppo
Guarda come risponde l'agente e controlla anche quando viene richiesto il file di test, che genererà il piano di test nel file CSV come artefatto.
Ora puoi controllare il contenuto del file CSV importandolo, ad esempio, in un foglio Google.
Complimenti! Ora hai un agente QA Test Planner funzionante in esecuzione in locale. Ora vediamo come possiamo eseguirne il deployment in Cloud Run in modo che anche altre persone possano utilizzarlo.
5. Deployment in Cloud Run
Ora, ovviamente, vogliamo accedere a questa fantastica app da qualsiasi luogo. Per farlo, possiamo pacchettizzare questa applicazione ed eseguirne il deployment in Cloud Run. Ai fini di questa demo, questo servizio verrà esposto come servizio pubblico a cui possono accedere altri. Tuttavia, tieni presente che questa non è la best practice.
Nella directory di lavoro corrente, abbiamo già tutti i file necessari per il deployment delle nostre applicazioni in Cloud Run: la directory dell'agente, Dockerfile e server.py (lo script di servizio principale). Eseguiamo il deployment. Vai al terminale Cloud Shell e assicurati che il progetto attuale sia configurato sul tuo progetto attivo. In caso contrario, devi utilizzare il comando gcloud configure per impostare l'ID progetto:
gcloud config set project [PROJECT_ID]
Quindi, esegui questo comando per eseguirne il deployment in Cloud Run.
gcloud run deploy qa-test-planner-agent \
--source . \
--port 8080 \
--project {YOUR_PROJECT_ID} \
--allow-unauthenticated \
--region us-central1 \
--update-env-vars GOOGLE_GENAI_USE_VERTEXAI=1 \
--update-env-vars GOOGLE_CLOUD_PROJECT={YOUR_PROJECT_ID} \
--update-env-vars GOOGLE_CLOUD_LOCATION=global \
--update-env-vars CONFLUENCE_URL={YOUR_CONFLUENCE_URL} \
--update-env-vars CONFLUENCE_USERNAME={YOUR_CONFLUENCE_USERNAME} \
--update-env-vars CONFLUENCE_TOKEN={YOUR_CONFLUENCE_TOKEN} \
--update-env-vars CONFLUENCE_PRD_SPACE_ID={YOUR_PRD_SPACE_ID} \
--memory 1G
Se ti viene chiesto di confermare la creazione di un registro degli artefatti per il repository Docker, rispondi Y. Tieni presente che qui consentiamo l'accesso non autenticato perché si tratta di un'applicazione demo. Ti consigliamo di utilizzare l'autenticazione appropriata per le applicazioni aziendali e di produzione.
Una volta completato il deployment, dovresti ricevere un link simile a quello riportato di seguito:
https://qa-test-planner-agent-*******.us-central1.run.app
Quando accedi all'URL, visualizzerai l'interfaccia utente di sviluppo web in modo simile a quando lo provi localmente. Continua a utilizzare l'applicazione dalla finestra di navigazione in incognito o dal tuo dispositivo mobile. Dovrebbe essere già disponibile.
Ora proviamo di nuovo questi diversi prompt in sequenza e vediamo cosa succede:
- " Puoi trovare il PRD relativo al calcolatore del mutuo? "
- " Dammi un feedback su cosa possiamo migliorare"
- " Scrivi il piano di test"
Inoltre, poiché eseguiamo l'agente come app FastAPI, possiamo anche esaminare tutte le route API nella route /docs. Ad esempio, se accedi all'URL in questo modo https://qa-test-planner-agent-*******.us-central1.run.app/docs, vedrai la pagina della documentazione di Swagger come mostrato di seguito
Spiegazione del codice
Ora esaminiamo il file necessario per il deployment, a partire da server.py.
# server.py
import os
from fastapi import FastAPI
from google.adk.cli.fast_api import get_fast_api_app
AGENT_DIR = os.path.dirname(os.path.abspath(__file__))
app_args = {"agents_dir": AGENT_DIR, "web": True}
app: FastAPI = get_fast_api_app(**app_args)
app.title = "qa-test-planner-agent"
app.description = "API for interacting with the Agent qa-test-planner-agent"
if __name__ == "__main__":
import uvicorn
uvicorn.run(app, host="0.0.0.0", port=8080)
Possiamo convertire facilmente il nostro agente in un'app FastAPI utilizzando la funzione get_fast_api_app. In questa funzione possiamo configurare varie funzionalità, ad esempio la configurazione del servizio di sessione, del servizio artefatti o persino il monitoraggio dei dati nel cloud.
Se vuoi, puoi anche impostare il ciclo di vita dell'applicazione qui. Dopodiché possiamo utilizzare uvicorn per eseguire l'applicazione Fast API
Dopodiché, il Dockerfile ci fornirà i passaggi necessari per eseguire l'applicazione.
# Dockerfile
FROM python:3.12-slim
RUN pip install --no-cache-dir uv==0.7.13
WORKDIR /app
COPY . .
RUN uv sync --frozen
EXPOSE 8080
CMD ["uv", "run", "uvicorn", "server:app", "--host", "0.0.0.0", "--port", "8080"]
6. La sfida
Ora è il tuo momento di brillare e perfezionare le tue capacità di esplorazione. Puoi anche creare uno strumento in modo che il feedback sulla revisione del PRD venga scritto in un file?
7. Esegui la pulizia
Per evitare che al tuo account Google Cloud vengano addebitati costi relativi alle risorse utilizzate in questo codelab, segui questi passaggi:
- Nella console Google Cloud, vai alla pagina Gestisci risorse.
- Nell'elenco dei progetti, seleziona il progetto che vuoi eliminare, quindi fai clic su Elimina.
- Nella finestra di dialogo, digita l'ID progetto, quindi fai clic su Chiudi per eliminare il progetto.
- In alternativa, puoi andare a Cloud Run nella console, selezionare il servizio di cui hai appena eseguito il deployment ed eliminarlo.