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 eseguire il deployment del prompt come applicazione web da condividere con i collaboratori o gli 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
- Testare l'invio di prompt con il supporto multimodale
Prima di iniziare
Se non hai mai utilizzato Agent Studio, puoi seguire un'altra guida rapida o il corso di 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 abilitata.
- I ruoli richiesti per 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.
Se vuoi, puoi anche assicurarti che il service account predefinito di Compute Engine disponga dei ruoli richiesti per il service account di deployment. Se disponi dell'autorizzazione per concedere i 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 di Agent Platform (
roles/aiplatform.user) -
Attiva 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 l'account di servizio predefinito di Compute Engine disponga delle autorizzazioni necessarie per eseguire le build per tuo conto, chiedi all'amministratore di concedere i seguenti ruoli IAM all'account di servizio predefinito di Compute Engine sul tuo progetto:
- Agent Platform 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 invece concederli durante il deployment dell'applicazione.
Crea un prompt con variabili del prompt
Vai alla pagina di creazione dei prompt di Agent Studio, poi 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. Poi fai clic su Applica.
Nella casella di input del prompt, componi il prompt utilizzando la variabile e poi regola gli altri parametri. Ad esempio, puoi attivare 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 sul pulsante Crea con il codice nell'angolo in alto a destra. Poi fai clic su Esegui il deployment come app.
Salva il prompt
Verrà visualizzata la finestra di dialogo di salvataggio, poiché il salvataggio è necessario prima che un prompt possa essere implementato. La finestra di dialogo del deployment si aprirà automaticamente dopo il salvataggio del prompt.
Abilitare le API per il primo deployment e concedere le autorizzazioni
- Una volta salvato il prompt, il processo di deployment continuerà. Se questo è il tuo primo deployment, vedrai una finestra di dialogo per l'attivazione delle API richieste. Fai clic su Abilita le API richieste.
-
Una volta abilitate le API, viene visualizzata la finestra di dialogo Crea un'app web. Puoi scegliere tra
Autenticazione obbligatoria (tramite Identity-Aware Proxy) o Consenti accesso pubblico.
- Se viene scelta l'autenticazione richiesta, segui la guida per concedere l'accesso (incluso te).
- Se selezioni Consenti l'accesso pubblico, chiunque può accedere all'app. Pertanto, non includere informazioni sensibili o che consentono l'identificazione personale (PII) nel prompt. Seleziona la casella di controllo Ho compreso che questa app verrà implementata pubblicamente per confermare.
- Fai clic su Crea app per avviare il deployment.
- Se questo è il tuo primo deployment, verrà visualizzata un'altra finestra di dialogo che ti chiede di concedere i ruoli richiesti al account di servizio. Fai clic su Concedi tutto per procedere.
Avvio del deployment
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, viene visualizzata la finestra di dialogo Gestisci app web con informazioni sul deployment, come il nome dell'applicazione, la data dell'ultimo deployment, lo stato del deployment e altro ancora.
Monitoraggio dello stato del deployment
Il deployment richiede 2-3 minuti e il relativo stato 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 cambierà in Pronto e accanto al nome dell'applicazione verrà visualizzato il pulsante Apri.
Controllo dell'accesso e chiave segreta
La tua applicazione web viene implementata con il controllo dell'accesso dell'accesso Consenti non autenticato attivato per impostazione predefinita. Puoi disattivarlo facendo clic sul pulsante a forma di matita. Per ulteriori informazioni, consulta la sezione Disattivare l'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.
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 la tua applicazione web è pronta, puoi aprirla anche dal menu del pulsante Crea con il codice.
Cloud Run è un servizio serverless, il che significa che il container per l'applicazione verrà chiuso se non viene utilizzato attivamente. Pertanto, a volte l'applicazione web potrebbe impiegare alcuni secondi per caricarsi o un invio non funzionerà se l'applicazione web è rimasta inattiva per troppo tempo. L'aggiornamento della pagina dovrebbe risolvere il problema.
Monitorare lo stato dalla campana delle notifiche
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 viene completato correttamente.
Se fai clic sulla notifica, verrà eseguito il reindirizzamento alla pagina Cloud Run. L'URL nella pagina Cloud Run non ha la chiave segreta aggiunta. Dovrai aggiungerla 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 riesegui 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 a quella del deployment iniziale. Puoi monitorare l'avanzamento nello stesso modo della prima implementazione.
Al termine dell'aggiornamento, puoi riaprire l'applicazione web. Vedrai l'interfaccia utente della conversazione con la variabile del prompt. Inserisci il valore e digita contenuti non vuoti per continuare la conversazione.
Inserire 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 sul 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 la procedura 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
Altro alla fine della riga.
In alternativa, puoi 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 sorgente per avviare la modalità di modifica. Al termine, fai clic su Salva e riesegui il deployment.
Al termine del nuovo deployment, devi aprire l'applicazione da Agent Studio. Puoi accedere alla pagina di Agent Studio dal link nel badge Deployment 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 accesso. La pagina Sicurezza di Cloud Run si apre in una nuova scheda.
- Nella pagina di sicurezza di Cloud Run, individua la casella di controllo per Identity-Aware Proxy (IAP). Assicurati che sia selezionata, poi fai clic su Modifica policy.
- Viene visualizzata un'attività secondaria che ti consente di modificare l'accesso. Inserisci le 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.
Disattivare l'accesso pubblico
Quando non hai bisogno 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 accesso. La pagina di 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, visualizzerai la pagina Errore: accesso negato.
Attivare di nuovo 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, l'operazione non funzionerà se il tuo progetto si trova in un'organizzazione. Per saperne di più, consulta Autenticazione in Cloud Run.
Configurare l'accesso locale per lo sviluppo
Nell'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 facendo clic sul 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 il simbolo 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 termine 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 è allegata alcuna chiave segreta. 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 sono presenti input nella variabile del prompt, ma la chat è vuota; viene visualizzato un messaggio di errore 400. Puoi risolvere il problema digitando un testo non vuoto e inviandolo di nuovo.
400 Argomento non valido: mimeType non è supportato
Se scegli un tipo di file non supportato dal modello, verrà restituito un errore 400. Questo è previsto e dovrai utilizzare altri tipi di file supportati dal modello. Consulta la documentazione sul supporto multimodale per ogni modello.
Passaggi successivi
Guida rapida di Agent Studio: invia prompt di testo a Gemini
Scopri come inviare prompt di testo a Gemini utilizzando Agent Studio.