In Agent Studio, puoi progettare ed eseguire l'iterazione dei prompt e confrontare i risultati di diverse configurazioni e modelli. Una volta terminata la progettazione del prompt, puoi eseguirne il deployment come applicazione web da condividere con i tuoi collaboratori o utenti target per consentire loro di testare l'applicazione web. L'applicazione web è ospitata su Cloud Run ed è disponibile al di fuori della console Google Cloud .
In questa guida rapida imparerai a:
- Crea un prompt con variabili del prompt
- Esegui il deployment del prompt come applicazione web
- Monitora l'avanzamento del deployment e testa l'applicazione di cui è stato eseguito il deployment
- Aggiorna e riesegui il deployment del prompt
- Testa l'invio di prompt con supporto multimodale
Prima di iniziare
Se non hai mai utilizzato Agent Studio, puoi seguire un'altra guida rapida o seguire il corso Google Cloud Skills Boost per apprendere le nozioni di base di Agent Studio. In questa guida, dovresti avere quanto segue:
- Un progetto Google Cloud con fatturazione e l'API Agent Platform abilitate.
- I ruoli richiesti per eseguire il deployment di un prompt di Agent Studio come applicazione web. Se hai creato un nuovo progetto per questa guida, disponi già delle autorizzazioni necessarie.
Facoltativamente, puoi anche assicurarti che il service account predefinito di Compute Engine disponga dei ruoli richiesti per il service account di deployment. Se hai l'autorizzazione per concedere ruoli, puoi concederli durante il deployment dell'applicazione.
Ruoli obbligatori
Per ottenere le autorizzazioni necessarie per eseguire il deployment di un prompt di Agent Studio come applicazione web, chiedi all'amministratore di concederti i seguenti ruoli IAM nel progetto:
- Utente della piattaforma agente (
roles/aiplatform.user) -
Abilita le API richieste:
Amministratore Service Usage (
roles/serviceusage.serviceUsageAdmin) -
Concedi i ruoli richiesti al account di servizio predefinito di Compute Engine:
Project IAM Admin (
roles/resourcemanager.projectIamAdmin) -
Esegui il deployment di un'applicazione Cloud Run:
- Cloud Run Admin (
roles/run.admin) - Cloud Run Source Developer (
roles/run.sourceDeveloper)
- Cloud Run Admin (
Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.
Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.
Ruoli richiesti per il account di servizio di deployment
Per assicurarti che il service account predefinito di Compute Engine disponga delle autorizzazioni necessarie per eseguire le build per tuo conto, chiedi all'amministratore di concedere i seguenti ruoli IAM al service account predefinito di Compute Engine nel tuo progetto:
- Vertex AI Service Agent (
roles/aiplatform.serviceAgent) - Service account Cloud Build (
roles/cloudbuild.builds.builder)
Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.
L'amministratore potrebbe anche essere in grado di concedere al service account predefinito di Compute Engine le autorizzazioni richieste tramite ruoli personalizzati o altri ruoli predefiniti.
Se hai l'autorizzazione per concedere ruoli, puoi concederli durante il deployment dell'applicazione.
Crea un prompt con variabili del prompt
Vai alla pagina di creazione dei prompt di Agent Studio, quindi fai clic su Aggiungi variabile nella casella di immissione del prompt.
Nella finestra di dialogo Gestisci variabili del prompt, inserisci un nome per la variabile e assegnale un valore. Quindi, fai clic su Applica.
Nella casella di immissione del prompt, componi il prompt utilizzando la variabile e poi regola gli altri parametri. Ad esempio, puoi attivare il grounding con la Ricerca Google e impostare "Ottieni sempre il meteo attuale dal web" come istruzioni di sistema.
Esegui il deployment del prompt come applicazione web
Per eseguire il deployment del prompt come applicazione web, fai clic su , quindi su Esegui il deployment come app.
Salva il prompt
Verrà visualizzata la finestra di dialogo per il salvataggio del prompt, poiché il salvataggio è obbligatorio prima di poter eseguire il deployment di un prompt. La finestra di dialogo di deployment si aprirà automaticamente dopo il salvataggio del prompt.
Abilita le API per il primo deployment e concedi le autorizzazioni
- Una volta salvato il prompt, il processo di deployment continuerà. Se è il tuo primo deployment, vedrai una finestra di dialogo per abilitare le API richieste. Fai clic su Abilita le API richieste.
-
Dopo aver abilitato le API, verrà visualizzata la finestra di dialogo Crea un'app web. Puoi scegliere Richiedi autenticazione (tramite Identity-Aware Proxy) o Consenti accesso pubblico.
- Se scegli l'autenticazione obbligatoria, segui la guida per concedere l'accesso (includi anche te).
- Se selezioni Consenti l'accesso pubblico, significa che chiunque può accedere all'app. Pertanto, non includere informazioni sensibili o che consentono l'identificazione personale (PII) nel prompt. Seleziona la casella di controllo Sono consapevole che il deployment di questa app sarà eseguito pubblicamente per confermare.
- Fai clic su Crea app per avviare il deployment.
- Se si tratta del tuo primo deployment, verrà visualizzata un'altra finestra di dialogo che ti chiederà di concedere i ruoli richiesti al account di servizio. Fai clic su Concedi tutto per procedere.
Deployment avviato
Agent Studio creerà un file ZIP contenente il codice sorgente dell'applicazione web e lo caricherà in un bucket Cloud Storage. Dopo l'avvio del deployment, verrà visualizzata la finestra di dialogo Gestisci app web con informazioni sul deployment, ad esempio il nome dell'applicazione, l'ultimo deployment, lo stato del deployment e altro ancora.
Monitoraggio dello stato del deployment
Il deployment richiede 2-3 minuti e lo stato del deployment viene visualizzato nella colonna Stato della finestra di dialogo Gestisci app web. Se chiudi la finestra di dialogo Gestisci app web, puoi riaprirla dal menu sotto il pulsante Crea con il codice.
Al termine del deployment, la colonna dello stato diventerà Pronto e accanto al nome dell'applicazione verrà visualizzato il pulsante Apri.
Controllo degli accessi e chiave segreta
Il deployment dell'applicazione web viene eseguito con controllo dell'accesso Consenti non autenticato abilitato per impostazione predefinita. Puoi disattivarla facendo clic sul pulsante con l'icona a forma di matita . Per saperne di più, consulta la sezione sulla disattivazione dell'accesso pubblico.
Per fornire una protezione di base, l'applicazione web richiede l'aggiunta di una chiave segreta all'URL per l'invio del prompt. Puoi trovare la chiave segreta nella colonna Chiave segreta. Se apri l'applicazione web da Agent Studio, la chiave verrà aggiunta all'URL per te.
Apri l'applicazione web e invia il prompt
Fai clic su Apri nella finestra di dialogo Gestisci app web per accedere all'applicazione di cui è stato eseguito il deployment. L'applicazione deve essere aperta con la chiave segreta aggiunta all'URL nel formato ?key=SECRET_KEY.
Inserisci un valore per la variabile e poi fai clic su Invia. Dovresti riuscire a vedere i risultati sulla destra.
Apri l'applicazione web dal menu del pulsante Crea con il codice
Se l'applicazione web è pronta, puoi anche aprirla dal menu del pulsante Crea con il codice.
Cloud Run è un servizio serverless, il che significa che il container per l'applicazione verrà arrestato se non viene utilizzato attivamente. Pertanto, a volte l'applicazione web può richiedere alcuni secondi per caricarsi o un invio non funzionerà se hai lasciato l'applicazione web inattiva per troppo tempo. L'aggiornamento della pagina dovrebbe risolvere il problema.
Monitoraggio dello stato dalla campanella di notifica
Puoi anche monitorare lo stato dal menu Notifiche facendo clic sull'icona a forma di campana. L'icona a forma di campana interromperà l'animazione di caricamento e mostrerà un cerchio verde se il deployment è stato completato correttamente.
Se fai clic sulla notifica, verrai reindirizzato alla pagina Cloud Run. All'URL nella pagina Cloud Run non è aggiunta la chiave segreta. Dovrai aggiungerlo manualmente nel formato ?key=SECRET_KEY.
Aggiorna e riesegui il deployment del prompt
Puoi modificare ulteriormente il prompt in Agent Studio e trasformarlo in una conversazione. Poi fai clic sul pulsante Crea con il codice e su Gestisci app per aprire la finestra di dialogo Gestisci app web. Fai clic su Aggiorna app per eseguire nuovamente il deployment dell'applicazione web con il prompt aggiornato.
Viene visualizzata una finestra di dialogo di conferma. Ti informa che, se rifai il deployment, perderai tutte le modifiche apportate all'applicazione web di cui è stato eseguito il deployment al di fuori di Agent Studio (ad esempio nell'editor del codice sorgente di Cloud Run). Fai clic su Conferma per procedere.
Verrà visualizzata di nuovo la finestra di dialogo Gestisci app web. La procedura è simile al deployment iniziale. Puoi monitorare l'avanzamento nello stesso modo del primo deployment.
Al termine dell'aggiornamento, puoi riaprire l'applicazione web. Vedrai la UI della conversazione con la variabile del prompt. Inserisci il valore e digita un contenuto non vuoto per continuare la conversazione.
Inserisci contenuti multimodali
Puoi inserire input come immagini, video, audio e documenti nell'interfaccia utente della conversazione. Gli input supportati dipendono dal modello selezionato per il prompt. Consulta la documentazione per il supporto multimodale per ciascun modello.
Per inserire un file, fai clic sul pulsante con l'icona della graffetta nella casella di immissione della conversazione.
Potrai interagire con il modello con l'input che fornisci.
Argomenti avanzati
Una volta acquisita familiarità con il processo di deployment, puoi prendere in considerazione le seguenti azioni.
Modifica il codice sorgente in Cloud Run
Se vuoi personalizzare l'applicazione web, puoi apportare modifiche al codice sorgente in Cloud Run. Apri la pagina del codice sorgente di Cloud Run dalla finestra di dialogo Gestisci app web facendo clic sul pulsante con l'icona Altro alla fine della riga.
In alternativa, puoi anche accedere alla pagina della sicurezza dall'applicazione web facendo clic sul link editor di codice sorgente.
Nella pagina del codice sorgente di Cloud Run, fai clic su Modifica origine per avviare la modalità di modifica. Al termine, fai clic su Salva ed esegui di nuovo il deployment.
Al termine del nuovo deployment, devi aprire l'applicazione da Agent Studio. Puoi accedere alla pagina Agent Studio dal link nel badge Deployment eseguito da Agent Platform.
Concedi l'accesso
Per concedere l'accesso all'app a utenti o gruppi:
- Apri la finestra di dialogo Gestisci app web.
- Fai clic sull'icona a forma di matita nella colonna Controllo degli accessi. Si apre la pagina Sicurezza di Cloud Run in una nuova scheda.
- Nella pagina Sicurezza di Cloud Run, individua la casella di controllo per Identity-Aware Proxy (IAP). Assicurati che sia selezionata, quindi fai clic su Modifica policy.
-
Verrà visualizzata un'attività secondaria per consentirti l'accesso in modifica. Inserisci gli indirizzi email degli utenti o dei gruppi nel campo Entità.
Se sei un utente di un'organizzazione, puoi aggiungere solo utenti della stessa organizzazione.
- Lascia vuoto il campo dei livelli di accesso.
- Fai clic su Salva.
-
Dopo aver chiuso l'attività secondaria, fai di nuovo clic su Salva nella pagina Cloud Run.
Disattiva l'accesso pubblico
Quando non è necessario che l'applicazione web sia accessibile pubblicamente, puoi disattivarla in Cloud Run. Apri la finestra di dialogo Gestisci app web e fai clic sull'icona a forma di matita nella colonna Controllo degli accessi. La pagina Sicurezza di Cloud Run si aprirà in una nuova scheda.
Puoi anche accedere alla pagina della sicurezza dall'applicazione web facendo clic sul link Impostazioni di sicurezza.
Nella pagina Sicurezza del servizio Cloud Run corrispondente della tua applicazione web, seleziona Utilizza Cloud IAM per autenticare le richieste in entrata e scegli Richiedi autenticazione. Fai clic su Salva.
Di conseguenza, la tua applicazione web non sarà più accessibile tramite l'URL. Se provi ad accedervi, verrà visualizzata la pagina Errore: accesso negato.
Riattiva l'accesso pubblico
Se vuoi riattivare l'accesso pubblico, deseleziona la casella di controllo Utilizza Cloud IAM per autenticare le richieste in entrata e salva. Se scegli Consenti chiamate non autenticate, non funzionerà se il tuo progetto si trova in un'organizzazione. Per ulteriori dettagli, consulta Autenticazione in Cloud Run.
Configura l'accesso locale per lo sviluppo
In Anteprima pubblica, il controllo dell'accesso non è ancora supportato. Pertanto, una volta disattivato l'accesso pubblico, l'unico modo per accedere all'applicazione web è configurare un proxy locale. Puoi farlo tramite i comandi gcloud. Innanzitutto, apri Cloud Shell tramite il pulsante con l'icona del terminale nell'angolo in alto a destra della console Google Cloud . Ti verrà chiesto di autorizzare Cloud Shell. Fai clic su Autorizza per continuare.
Al termine, apri la finestra di dialogo Gestisci app web e fai clic sul pulsante con l'icona Altro alla fine della riga per visualizzare altre azioni. Fai clic su Configura l'accesso locale tramite Cloud Shell.
Un comando verrà aggiunto a Cloud Shell. Premi Invio e attendi il completamento della stampa. Fai clic sul link nella riga che inizia con Click on the
link to preview. Potrai visualizzare la tua richiesta. Questo link funziona solo quando è in esecuzione il comando gcloud.
Problemi comuni
Errore di autenticazione: nessuna chiave segreta
Se visualizzi il seguente errore, significa che all'URL non è stata aggiunta alcuna chiave secret. Segui le istruzioni per aprire l'applicazione web da Agent Studio o copia la chiave segreta dalla finestra di dialogo Gestisci app e aggiungila all'URL nel formato ?key=SECRET_KEY.
Errore di autenticazione: codice segreto non valido
Il seguente errore indica che la chiave aggiunta all'URL non è valida. La chiave segreta è univoca per ogni prompt. Se hai una chiave segreta di un altro prompt, non funzionerà. Segui le istruzioni per aprire correttamente l'applicazione web.
400 Argomento non valido: input vuoto
Il seguente errore si verifica quando hai input nella variabile del prompt, ma la chat è vuota; verrà visualizzato un messaggio di errore 400. Per risolvere il problema, digita un testo non vuoto e invia di nuovo.
400 Invalid argument: mimeType is not supported
Se scegli un tipo di file non supportato dal modello, verrà restituito un errore 400. Questo è il comportamento previsto e dovrai utilizzare altri tipi di file supportati dal modello. Consulta la documentazione per il supporto multimodale per ogni modello.
Passaggi successivi
Guida rapida di Agent Studio: invia prompt testuali a Gemini
Scopri come inviare prompt testuali a Gemini utilizzando Agent Studio.