Progetta agenti in Agent Studio

Questa pagina fornisce una panoramica su come utilizzare Agent Studio nella consoleGoogle Cloud .

Agent Studio è uno strumento di progettazione visiva low-code all'interno della console Google Cloud che semplifica lo sviluppo degli agenti. Puoi mappare visivamente gli Agentic Workflows, testare le risposte in tempo reale e sperimentare diverse configurazioni prima del deployment o della transizione al codice.

Questo documento fornisce una panoramica di Agent Studio e spiega come configurare l'ambiente, creare e testare gli agenti ed eseguirne il deployment direttamente in un runtime di produzione.

Configura l'ambiente

Prima di utilizzare Agent Studio, configura Google Cloud.

Ottenere i ruoli richiesti

Per ottenere le autorizzazioni necessarie per utilizzare Agent Studio, chiedi all'amministratore di concederti il ruolo IAM Agent Platform User (roles/aiplatform.user) nel progetto. 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.

Crea un agente

Puoi creare un agente in Agent Studio utilizzando i prompt o il Flow Builder.

Crea un agente utilizzando i prompt

Per creare un agente utilizzando i prompt:

  1. Nella console Google Cloud , vai alla pagina Agenti.

    Vai ad Agenti

  2. Fai clic su Crea agente per aprire il canvas di Agent Studio per un nuovo agente.

  3. Nella casella di chat, inserisci un prompt che descriva lo scopo e il comportamento previsto dell'agente.

  4. Fai clic su .

  5. A seconda del prompt, si verifica una delle seguenti situazioni:

    • Operazione riuscita: il generatore di flussi si aggiorna immediatamente per mostrare l'anteprima live dell'agente e la chat fornisce un riepilogo delle modifiche apportate. Tutte le modifiche vengono salvate automaticamente.

    • Chiarimento necessario: se il prompt è ambiguo, l'assistente pone una domanda di chiarimento nella chat per capire meglio cosa vuoi creare.

    • Errore:se l'assistente non riesce ad applicare il prompt, un messaggio di errore ti invita a riformulare la richiesta.

  6. Puoi continuare ad aggiornare l'agente utilizzando i prompt o il generatore di flussi.

  7. Per salvare l'agente, fai clic su Salva nell'intestazione del canvas e segui le istruzioni. Per maggiori dettagli, vedi Salva un agente.

  8. Per testare le funzionalità e le risposte dell'agente durante la creazione, fai clic sulla scheda Anteprima e chatta con l'agente.

Limitazioni

Quando crei un agente utilizzando i prompt, si applicano le seguenti limitazioni:

Capacità Limitazione
Conoscenza Impossibile aggiungere la conoscenza a un agente. Puoi utilizzare l'interfaccia del Flow Builder per aggiungere conoscenze a un agente.

Crea un agente utilizzando il generatore di flussi

Per progettare e testare un agente utilizzando il generatore di flussi:

  1. Nella console Google Cloud , vai alla pagina Agenti.

    Vai ad Agenti

  2. Fai clic su Crea agente per aprire il canvas di Agent Studio per un nuovo agente.

  3. Progetta e salva l'agente nel canvas di Agent Studio. Puoi creare un agente principale e aggiungere agenti secondari. L'agente principale è sempre un agente locale. I subagenti possono essere agenti locali o agenti di Agent Registry:

    • Agente locale:un agente le cui istruzioni, modello e strumenti sono creati e configurati direttamente all'interno del canvas di Agent Studio.
    • Agente Agent Registry:un agente registrato e pubblicato in Agent Registry. Puoi utilizzare questi agenti come subagenti remoti all'interno del flusso dell'agente principale.

    Durante la progettazione, puoi passare da una scheda all'altra tra Flusso e Anteprima:

    Flow

    Crea l'agente principale e i subagenti utilizzando una rappresentazione visiva del workflow e della logica di controllo dell'agente.

    1. Fai clic su un agente per aprire il riquadro Dettagli corrispondente. Puoi anche fare clic su Aggiungi un subagente (+) per aggiungere subagenti.

    2. Configura l'agente principale e i subagenti nel riquadro Dettagli:

      Per l'agente principale e i subagenti locali:

      1. Nome:aggiungi un nome per identificare l'agente.
      2. Descrizione:un riepilogo dello scopo dell'agente.
      3. Istruzioni:aggiungi istruzioni per guidare l'agente.
      4. Modello:seleziona il modello per potenziare l'agente.
      5. Strumenti: fai clic su Aggiungi strumenti (+) per aggiungere strumenti che consentono all'agente di completare le attività. Per saperne di più, vedi Configurare e aggiungere strumenti.

      Per i subagenti (locali o del Registro degli agenti):

      1. Origine del subagente:seleziona l'origine del subagente:

        • Locale:crea le istruzioni, il modello e gli strumenti del subagente direttamente sul canvas.
        • Agent Registry: seleziona un agente registrato da Agent Registry come subagente remoto. Questa opzione è disponibile solo dopo aver salvato l'agente. Per maggiori dettagli, vedi Salva un agente.

        Quando selezioni un agente registrato, il nome e la descrizione vengono importati dal registry e diventano di sola lettura nel canvas. L'agente principale indirizza le attività a questo subagente in base alla sua scheda dell'agente.

        Per eseguire o eseguire il deployment dell'agente parent, l'identità dell'agente parent deve disporre delle autorizzazioni per rilevare e richiamare i subagenti A2A. La finestra di dialogo delle autorizzazioni gestisce automaticamente questa azione. Se devi gestire le autorizzazioni manualmente, consulta Concedi l'accesso per la delega agente-agente (A2A).

    3. Per salvare l'agente, fai clic su Salva nell'intestazione del canvas e segui le istruzioni. Per maggiori dettagli, vedi Salvare un agente.

    Anteprima

    Chatta con l'agente nel riquadro di anteprima per testarne le funzionalità e le risposte.

  4. Fai clic su Ottieni codice per visualizzare il codice agente. Se vuoi continuare a sviluppare il tuo agente altrove, puoi copiare il codice e incollarlo in un editor di codice a tua scelta.

    Se l'agente utilizza un subagente remoto di Agent Registry, il codice Python generato include una chiamata a AgentRegistry.get_remote_a2a_agent per risolvere dinamicamente il subagente in fase di runtime.

Una volta completato l'agente, puoi eseguirne il deployment direttamente da Agent Studio. Per saperne di più, consulta Esegui il deployment di un agente da Agent Studio.

Crea un agente utilizzando il pulsante di attivazione/disattivazione della modalità Agenti nel prompt di Studio

Puoi iniziare a creare agenti direttamente dal prompt di benvenuto di Agent Studio attivando la modalità Agenti. Se l'opzione è attiva, l'invio del prompt direttamente avvia la creazione dell'agente all'interno del canvas di Agent Designer.

Per creare un agente dal prompt di Studio:

  1. Nella console Google Cloud , vai ad Agent Studio.

  2. Nell'area di input del prompt principale dello spazio di lavoro di benvenuto, individua l'opzione di attivazione/disattivazione della modalità.

  3. Imposta l'opzione sulla modalità Agenti.

  4. Inserisci un prompt che descriva lo scopo, il flusso di lavoro e il comportamento dell'agente che vuoi progettare.

  5. Fai clic su .

Agent Studio avvia direttamente il lavoro di creazione dell'agente nel canvas di progettazione dell'agente, precompilando il flusso e la configurazione dell'agente in base al prompt. Puoi quindi continuare a modificare le istruzioni, selezionare i modelli e aggiungere strumenti o subagenti.

Ispeziona gli eventi dell'agente

L'ispezione degli eventi ti aiuta a eseguire il debug del comportamento dell'agente, nonché a risolvere i problemi e a tracciare il processo di ragionamento e le richieste del modello dell'agente.

Puoi eseguire il debug dell'esecuzione dell'agente esaminando gli eventi dell'agente nella scheda Anteprima di Agent Studio. Questa azione ti consente di diagnosticare i problemi nei singoli eventi prodotti dall'agente durante un'esecuzione.

Per esaminare gli eventi dell'agente, segui questi passaggi:

  1. Apri l'agente nel canvas di Agent Studio e apri la scheda Anteprima.
  2. Avvia una chat con l'agente nel riquadro di anteprima per iniziare una corsa.

  3. Seleziona un evento nella conversazione per aprirne i dettagli. I dettagli disponibili dipendono dall'evento e possono includere:

    • Autore:l'agente o il subagente che ha generato l'evento. Utilizza l'autore per identificare quale subagente ha eseguito un passaggio in un flusso di lavoro multi-agente.
    • Richiesta e risposta: il payload inviato al modello e la risposta restituita.
    • Chiamate di strumenti: gli argomenti passati agli strumenti durante l'esecuzione dell'agente.
    • Metadati:informazioni diagnostiche aggiuntive, come il nome del modello, l'utilizzo dei token e il timestamp.

Se l'agente restituisce un errore durante l'anteprima, l'errore viene visualizzato nella scheda Anteprima per consentirti di diagnosticare il problema.

Salvare un agente

Devi salvare un agente prima di poterlo visualizzare in anteprima, eseguirne il deployment o caricare file di conoscenza, perché un agente non salvato non ha ancora un'identità. Questo requisito si applica anche ai sub-agenti di Agent Registry.

Inoltre, devi salvare un agente prima di aggiungere i server MCP pubblicati in Agent Registry come strumenti a livello di nodo.

Per salvare un agente per la prima volta:

  1. Nel canvas di Agent Studio, fai clic su Salva.

  2. Nella finestra di dialogo Salva agente, inserisci un nome agente.

  3. Fai clic su Salva.

Dopo il primo salvataggio, Agent Studio salva automaticamente tutte le modifiche successive che apporti. Se provi a uscire dal canvas prima di salvare un nuovo agente, Agent Studio ti chiede di salvarlo.

Aggiorna un agente

Per aggiornare un agente:

  1. Nella console Google Cloud , vai alla pagina Agenti.

    Vai ad Agenti

  2. Fai clic su in corrispondenza dell'agente da aggiornare, quindi su Modifica.

  3. Aggiorna l'agente utilizzando i prompt o il generatore di flussi.

Agent Studio salva automaticamente le modifiche.

Configura e aggiungi strumenti in Agent Studio

Puoi configurare i seguenti strumenti per l'agente:

  • Ricerca Google:consente all'agente di eseguire ricerche sul web utilizzando la Ricerca Google. Attivata per impostazione predefinita.

  • Contesto URL:consente al modello di analizzare gli URL dai prompt inviati all'agente. Attivata per impostazione predefinita.

  • Server MCP da Agent Registry:collega un server MCP pubblicato in Agent Registry come strumento a livello di nodo. Questa opzione è disponibile solo dopo aver salvato l'agente. Per maggiori dettagli, vedi Salvare un agente.

    1. Fai clic su Aggiungi (+) accanto a Server MCP da Agent Registry.
    2. Località:seleziona la regione per filtrare gli strumenti registrati.
    3. Server MCP:seleziona il server Google MCP registrato dall'elenco.
    4. Configurazione autenticazione: seleziona Nessuna per utilizzare l'accesso standard ai servizi risolto tramite le associazioni IAM.
    5. Fai clic su Aggiungi.
    6. Se salvi l'agente per la prima volta, fai clic su Salva nell'intestazione del canvas. Le modifiche successive vengono salvate automaticamente.

    L'agente può utilizzare tutti gli strumenti nel server MCP connesso.

Esegui la migrazione degli strumenti legacy

Per contribuire a garantire la sicurezza e standardizzare la gestione degli strumenti tramite Agent Registry, Agent Studio ritira l'integrazione diretta con i datastore di Vertex AI Search e i server Model Context Protocol (MCP) diretti.

Per gli agenti esistenti, questi strumenti ritirati sono di sola lettura. Per mantenere la piena funzionalità, esegui la migrazione a un server MCP da Agent Registry.

Esegui la migrazione dai datastore Vertex AI Search legacy

Se il tuo agente utilizza uno strumento datastore di ricerca della piattaforma per agenti ritirato, esegui la migrazione al server MCP di Agent Search disponibile in Agent Registry. Questo strumento viene visualizzato come discoveryengine.googleapis.com in Agent Registry.

Quando connetti il server MCP di ricerca dell'agente, devi definire la configurazione di gestione di destinazione nelle istruzioni dell'agente. Inoltre, l'identità dell'agente richiede autorizzazioni di accesso.

Per eseguire la migrazione, segui questi passaggi:

  1. Apri l'agente nel canvas di Agent Studio.
  2. Individua lo strumento Datastore Vertex AI Search nel riquadro Strumenti.
  3. Prendi nota delle impostazioni dello strumento, come l'ID progetto, la località e l'ID datastore.
  4. Crea un nuovo agente e salvalo.
  5. Concedi il ruolo Discovery Engine Viewer (roles/discoveryengine.viewer) all'identità dell'agente. Ti consigliamo di concedere questo ruolo direttamente nel datastore o nell'applicazione di ricerca di destinazione. Tuttavia, per la risoluzione dei problemi, puoi concederlo al progetto. Per trovare l'entità di identità dell'agente e concedere il ruolo, consulta Gestisci i ruoli manualmente. L'agente deve anche disporre del ruolo Utente strumento MCP (roles/mcp.toolUser), che viene concesso automaticamente dalla finestra di dialogo delle autorizzazioni.
  6. Nel riquadro Strumenti, fai clic su Aggiungi (+) accanto a Server MCP da Agent Registry.
  7. Specifica quanto segue:
    1. Località:seleziona la regione in cui sono registrati i tuoi strumenti.
    2. Server MCP: seleziona Agent Search o discoveryengine.googleapis.com dall'elenco dei server MCP registrati.
    3. Configurazione di autenticazione:seleziona Nessuna. L'accesso viene risolto tramite le associazioni IAM standard.
    4. Fai clic su Aggiungi.

  8. Nelle istruzioni del nuovo agente, specifica la configurazione di pubblicazione target utilizzando i valori annotati nel passaggio 3. Ad esempio:

    Use the search tool to answer questions about YOUR_TOPIC.
When using the search tool, use this servingConfig:
projects/PROJECT_ID/locations/LOCATION/collections/default_collection/dataStores/DATA_STORE_ID/servingConfigs/default_search

    Per un'applicazione di ricerca, sostituisci dataStores/DATA_STORE_ID con engines/APP_ID. Per i formati e gli argomenti supportati, consulta MCP Tools Reference: discoveryengine.googleapis.com.

Esegui la migrazione dal server MCP diretto legacy

Se l'agente si connette direttamente a un server MCP utilizzando un URL endpoint, devi prima registrare il catalogo del server MCP in Agent Registry.

Per eseguire la migrazione dello strumento, segui questi passaggi:

  1. Assicurati che il server MCP sia registrato in Agent Registry.
  2. Aggiorna l'agente in Agent Studio:
    1. Apri l'agente nel canvas di Agent Studio.
    2. Individua e rimuovi la connessione diretta al server MCP legacy.
    3. Fai clic su Aggiungi (+) accanto a Server MCP da Agent Registry.
    4. Seleziona il tuo server MCP registrato dall'elenco.
    5. Fai clic su Aggiungi.
    6. Se stai salvando l'agente per la prima volta, fai clic su Salva nell'intestazione del canvas. Le modifiche successive vengono salvate automaticamente.

Mappa agenti con file di conoscenza

Carica documenti di riferimento statici per basare le risposte dell'agente in Agent Studio:

  1. Seleziona il nodo dell'agente parent nel canvas in cui vuoi allegare i file di riferimento. Tieni presente che non puoi allegare file di conoscenza agli agenti secondari.
  2. Nel riquadro Dettagli del nodo, individua la sezione Contesto. La sezione Conoscenza viene visualizzata solo dopo aver salvato l'agente per la prima volta. Per maggiori dettagli, vedi Salvare un agente.
  3. Fai clic sul componente di caricamento file e sfoglia per selezionare il file di riferimento. Puoi allegare fino a 10 file per agente. Le dimensioni del file non devono superare i 2 megabyte (2 MB). Il canvas di caricamento supporta i seguenti tipi di file:
    • PDF
    • Testo normale

  4. Se salvi l'agente per la prima volta, fai clic su Salva nell'intestazione del canvas per archiviare i file in un bucket Cloud Storage dedicato con un prefisso del percorso corrispondente a AGENT_ID dell'agente padre. Le modifiche successive vengono salvate automaticamente.

    La finestra di dialogo delle autorizzazioni concede il ruolo Visualizzatore oggetti Storage (roles/storage.objectViewer) all'identità dell'agente nel bucket.

  5. Vai alla scheda Anteprima e invia una query di test per verificare che l'agente basi la sua risposta sui contenuti del file senza generare informazioni false.

  6. (Facoltativo) Puoi fare clic su Ottieni codice per copiare il codice Python generato (agent.py) e ispezionare la configurazione del file di grounding. Puoi saltare questo passaggio.

Gestisci le autorizzazioni di Agent Identity

Ogni agente in Agent Studio ha un'identità univoca, che funge da entità IAM per accedere ad altre risorse Google Cloud .

Il formato dell'entità è:

principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/REASONING_ENGINE_ID

Sostituisci quanto segue:

  • ORGANIZATION_ID: l'ID numerico della tua organizzazione.
  • PROJECT_NUMBER: il numero del tuo progettoGoogle Cloud .
  • LOCATION: la regione in cui è stato eseguito il deployment dell'agente.
  • REASONING_ENGINE_ID: l'ID risorsa del tuo motore di ragionamento.

Per ulteriori informazioni sulle identità degli agenti, consulta Crea un agente con identità agente e Panoramica dell'identità agente.

Comportamento della finestra di dialogo delle autorizzazioni

Quando fai clic su Esegui il deployment o apri la scheda Anteprima per un agente salvato, Agent Studio verifica automaticamente se l'identità dell'agente dispone dell'insieme di ruoli IAM necessari per l'esecuzione corretta. Alcune autorizzazioni mancanti potrebbero causare un errore dell'agente se non sono configurate correttamente. La concessione di queste autorizzazioni all'identità dell'agente ne garantisce il corretto funzionamento.

Se il sistema rileva problemi di autorizzazione, nella finestra di dialogo delle autorizzazioni viene visualizzato un messaggio di errore.

  • Ruoli mancanti: se mancano i ruoli richiesti, viene visualizzata una finestra di dialogo che elenca i ruoli dettagliati. Fai clic su Concedi tutto nella finestra di dialogo per concedere automaticamente tutti i ruoli necessari all'identità dell'agente in un'unica azione. Per visualizzare l'anteprima o eseguire il deployment dell'agente senza concedere i ruoli, fai clic su Procedi comunque.
  • Tutti i ruoli concessi: se tutti i ruoli richiesti sono già stati concessi, la finestra di dialogo delle autorizzazioni non viene visualizzata.
  • Agenti non salvati:gli agenti non salvati non hanno ancora un'identità. La finestra di dialogo delle autorizzazioni non viene visualizzata e la scheda Anteprima e le opzioni di deployment sono disabilitate finché non salvi l'agente.

Ruoli obbligatori

La finestra di dialogo delle autorizzazioni concede automaticamente il seguente elenco di ruoli:

  • roles/storage.objectViewer: obbligatorio se l'agente utilizza file caricati. Questo ruolo deve essere concesso nel bucket Cloud Storage specifico per i file dell'agente (ad esempio {projectNumber}_{location}_agent_studio_files).
  • roles/mcp.toolUser: obbligatorio se l'agente utilizza uno strumento MCP di Agent Registry.
  • roles/agentregistry.viewer: obbligatorio se l'agente utilizza uno strumento o un subagente MCP di Agent Registry.
  • roles/iamconnectors.user: obbligatorio se uno strumento MCP di Agent Registry specifica un authProviderName.
  • roles/aiplatform.viewer: obbligatorio se l'agente richiama subagenti remoti tramite la delega Agent-to-Agent (A2A).

Gestire i ruoli manualmente nella console Google Cloud

La finestra di dialogo delle autorizzazioni concede automaticamente i ruoli richiesti. Tuttavia, se preferisci gestire i ruoli manualmente o devi risolvere i problemi di autorizzazione, segui questi passaggi:

  1. Copia l'entità identità univoca dell'agente. Nell'intestazione del canvas di Agent Studio, fai clic sul menu a discesa accanto al nome dell'agente e copia la stringa dell'entità.

    Il formato del principal è simile al seguente esempio:

    principal://agents.global.org-ORG_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/REASONING_ENGINE_ID

  2. Nella console Google Cloud , vai a IAM:

    Vai a IAM

  3. Cerca l'entità Agent Identity nell'elenco delle entità. Puoi eseguire la ricerca utilizzando REASONING_ENGINE_ID dalla fine della stringa del principal. Per ottenere l'entità dell'identità dell'agente, hai una delle seguenti opzioni:

    • Se l'entità Agent Identity è già presente nell'elenco, fai clic su Modifica entità accanto ad Agent Identity.
    • Se l'entità Agent Identity non è presente nell'elenco, fai clic su Concedi l'accesso per aggiungerla come nuova entità.

  4. Aggiungi o modifica i ruoli richiesti per la configurazione, ad esempio roles/storage.objectViewer o roles/mcp.toolUser.

  5. Fai clic su Salva.

A seconda della configurazione, potrebbe essere necessario concedere manualmente ruoli aggiuntivi che la finestra di dialogo delle autorizzazioni non gestisce automaticamente. Ad esempio, se lo strumento MCP registrato accede ad altre risorse Google Cloud , ad esempio esegue query sui dati di BigQuery, devi concedere manualmente i ruoli necessari, ad esempio il ruolo BigQuery Data Viewer (roles/bigquery.dataViewer), all'identità dell'agente.

Eseguire il deployment di un agente da Agent Studio

Dopo aver creato e visualizzato l'anteprima di un agente, puoi eseguirne il deployment in produzione. Segui questi passaggi per eseguire il deployment di un agente da Agent Studio:

  1. Nella pagina dell'elenco Agenti, fai clic sull'agente di cui vuoi eseguire il deployment. Viene visualizzata la pagina dei dettagli dell'agente selezionato.

  2. Fai clic su Esegui il deployment per aprire la finestra di dialogo Esegui il deployment in un'istanza di Agent Runtime.

    Se l'identità dell'agente non dispone delle autorizzazioni richieste, viene visualizzata la finestra di dialogo delle autorizzazioni, che gestisce questa azione automaticamente. Se devi gestire le autorizzazioni manualmente, consulta Gestisci le autorizzazioni di Agent Identity e Concedi l'accesso per la delega agent-to-agent (A2A).

  3. Nella finestra di configurazione del deployment, configura le seguenti opzioni:

    • Nome visualizzato e Descrizione: modifica il nome visualizzato e, facoltativamente, aggiungi una descrizione per l'agente.
    • Fai il deployment come A2A: seleziona questa casella di controllo per eseguire il deployment dell'agente come asset Agent-to-Agent (A2A) che altri agenti possono riutilizzare. Per le applicazioni autonome, lascia deselezionata la casella di controllo per pacchettizzare l'agente come applicazione ADK standard.

  4. Seleziona una regione di deployment dall'elenco delle regioni disponibili, quindi fai clic su OK.

  5. Fai clic su Esegui il deployment.

Il deployment crea una nuova istanza di runtime e può richiedere fino a cinque minuti per essere completato. In caso di esito positivo, nella scheda Flusso del canvas di Agent Studio viene visualizzato un messaggio. Ora l'agente è disponibile in produzione e può integrarsi in modo sicuro con le tue app esterne.

Visualizza un agente di cui è stato eseguito il deployment

Per visualizzare l'agente di cui è stato eseguito il deployment:

  1. Nella console Google Cloud , vai alla pagina Deployment della piattaforma dell'agente.

    Vai a Deployment

  2. Utilizza l'elenco Regione per filtrare in base alla regione di deployment.

  3. Gli agenti di cui è stato eseguito il deployment che fanno parte del progetto selezionato vengono visualizzati nell'elenco.

  4. Fai clic sul nome dell'agente specificato. Si apre la pagina Metriche per l'agente.

  5. Seleziona la scheda Playground per testare l'agente.

  6. Inserisci una query di test nel riquadro della chat per verificare che l'agente venga eseguito correttamente.

Per ulteriori informazioni sulle metriche disponibili per l'agente, consulta Visualizzare le metriche per l'agente di cui è stato eseguito il deployment.