Registra e gestisci gli agenti ADK ospitati su Agent Runtime

Questa pagina spiega come gli amministratori registrano gli agenti ADK da Agent Runtime per l'utilizzo nell'app web Gemini Enterprise.

Per gli agenti ADK di cui è stato eseguito il deployment su Agent Runtime, puoi utilizzare un singolo comando Agents CLI in Agent Platform per registrare gli agenti con Gemini Enterprise.

Quando registri gli agenti ADK ospitati su Agent Runtime con un'app Gemini Enterprise e li rendi disponibili agli utenti finali nell'app web Gemini Enterprise:

  • Il servizio Agent Runtime elabora le query dell'agente.

  • Si applicano i Termini per l'elaborazione ML di Agent Runtime. Per saperne di più, consulta Limitazioni di Agent Runtime.

La tabella seguente descrive come vengono gestiti gli agenti ADK per garantire un deployment e un utilizzo sicuri e controllati.

Governance degli agenti Descrizione
Comunicazione sicura La connessione tra Agent Runtime e Gemini Enterprise è conforme ai Controlli di servizio VPC (VPC-SC), garantendo uno scambio di dati sicuro.
Supporto degli agenti tra progetti Puoi collegare gli agenti ADK ospitati in un Google Clouddiverso. Gemini Enterprise utilizza il networking privato sicuro di Google Cloudper queste connessioni tra progetti. Per saperne di più, consulta Configura l'accesso dell'agente ADK tra progetti.
Interazioni personalizzate Gli agenti ADK ricevono l'indirizzo email dell'utente da Gemini Enterprise. In questo modo, gli agenti possono riconoscere i singoli utenti e fornire risposte personalizzate in base alla loro identità e alle loro autorizzazioni.

Prima di iniziare

Assicurati di disporre di quanto segue:

Configura i dettagli di autorizzazione (facoltativo)

Segui questi passaggi per ottenere i dettagli dell'autorizzazione.

  1. Nella console Google Cloud , nella pagina API e servizi, vai alla pagina Credenziali.

    Vai a credenziali

  2. Seleziona il progetto Google Cloud , che contiene l'origine dati a cui vuoi che l'agente acceda. Ad esempio, seleziona il progetto che contiene il set di dati BigQuery su cui vuoi che l'agente esegua query.

  3. Fai clic su Crea credenziali e seleziona ID client OAuth.

  4. In Tipo di applicazione, seleziona Applicazione web.

  5. Nella sezione URI di reindirizzamento autorizzati, aggiungi i seguenti URI:

    • https://vertexaisearch.cloud.google.com/oauth-redirect
    • https://vertexaisearch.cloud.google.com/static/oauth/oauth.html

  6. Fai clic su Crea.

  7. Nel riquadro Client OAuth creato, fai clic su Scarica JSON. Il file JSON scaricato include Client ID, Authorization URI, Token URI e Client secret per il progetto Google Cloud selezionato. Questi dettagli sono necessari per creare una risorsa di autorizzazione.

Registra un agente ADK con Gemini Enterprise

Puoi registrare l'agente ADK con Gemini Enterprise utilizzando la consoleGoogle Cloud o l'API REST. In questo modo, l'agente sarà disponibile per gli utenti all'interno di un'app Gemini Enterprise.

Console

Per registrare un agente ADK utilizzando la console Google Cloud , segui questi passaggi:

  1. Nella console Google Cloud , vai alla pagina Gemini Enterprise.

    Gemini Enterprise

  2. Fai clic sul nome dell'app con cui vuoi registrare l'agente.

  3. Fai clic su Agenti. Viene visualizzata la pagina Agenti.

  4. Fai clic su Aggiungi agente. Viene visualizzato il riquadro Aggiungi un agente.

  5. Fai clic su Aggiungi per Agente personalizzato tramite Agent Runtime. Viene visualizzata la pagina Autorizzazioni.

  6. Se vuoi che l'agente acceda alle risorse Google Cloud per tuo conto, ogni risorsa deve essere autorizzata. Per configurare un'autorizzazione per una singola risorsa, segui questi passaggi:

    1. Fai clic su Aggiungi autorizzazione.

    2. Inserisci un valore univoco per Nome autorizzazione. Viene generato un ID in base al nome, che non può essere modificato in un secondo momento.

    3. Inserisci i valori generati in Configura i dettagli di autorizzazione (facoltativo) nei seguenti campi:

      1. Inserisci il valore nel campo ID client.

      2. Inserisci il valore nel campo Client secret.

      3. Inserisci il valore nel campo URI token.

      4. Inserisci il valore nel campo URI di autorizzazione. Crea l'URI di autorizzazione utilizzando i dettagli del file JSON delle credenziali OAuth. Copia il seguente template e sostituisci i segnaposto con i tuoi valori specifici.

        https://accounts.google.com/o/oauth2/v2/auth?client_id=YOUR_CLIENT_ID&redirect_uri=https%3A%2F%2Fvertexaisearch.cloud.google.com%2Fstatic%2Foauth%2Foauth.html&scope=YOUR_CUSTOM_SCOPES&include_granted_scopes=true&response_type=code&access_type=offline&prompt=consent

      5. Fai clic su Fine.

  7. Fai clic su Avanti.

  8. Per configurare l'agente, segui questi passaggi:

    1. Inserisci un nome nel campo Nome agente. Questo valore viene visualizzato nell'app web Gemini Enterprise come nome visualizzato dell'agente.

    2. Inserisci una descrizione nel campo Descrivi il tuo agente. Questo valore viene utilizzato da un LLM per determinare se richiamare l'agente in risposta a una query dell'utente.

    3. Inserisci il percorso della risorsa Agent Runtime. Il percorso della risorsa ha il seguente formato:

       projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID

      Per saperne di più su come elencare gli agenti ospitati su Agent Runtime e ottenere il percorso della risorsa, consulta Elenca gli agenti di cui è stato eseguito il deployment.

    4. Fai clic su Crea.

REST

Per registrare un agente ADK utilizzando l'API REST, segui questi passaggi:

(Facoltativo) Aggiungi la risorsa di autorizzazione a Gemini Enterprise

Se l'agente deve accedere alle risorse Google Cloud per conto di un utente, esegui il seguente comando per registrare la risorsa di autorizzazione creata nella sezione Configura i dettagli di autorizzazione (facoltativo) con Gemini Enterprise:

curl -X POST \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   -H "X-Goog-User-Project: PROJECT_ID" \
   "https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_NUMBER/locations/LOCATION/authorizations?authorizationId=AUTH_ID" \
   -d '{
      "name": "projects/PROJECT_NUMBER/locations/LOCATION/authorizations/AUTH_ID",
      "serverSideOauth2": {
         "clientId": "OAUTH_CLIENT_ID",
         "clientSecret": "OAUTH_CLIENT_SECRET",
         "authorizationUri": "OAUTH_AUTH_URI",
         "tokenUri": "OAUTH_TOKEN_URI"
      }
   }'

Sostituisci quanto segue:

  • PROJECT_ID: l'ID progetto.
  • PROJECT_NUMBER: il numero del tuo progetto Google Cloud .
  • ENDPOINT_LOCATION: la località multiregionale per la richiesta API. Specifica uno dei seguenti valori:
    • us per la multi-regione Stati Uniti
    • eu per la multi-regione UE
    • global per la località globale
    Per saperne di più, consulta Specifica una multi-regione per il datastore.
  • LOCATION: la località multiregionale del datastore: global, us o eu
  • AUTH_ID: l'ID della risorsa di autorizzazione. Si tratta di un ID alfanumerico arbitrario definito da te. Dovrai fare riferimento a questo ID in un secondo momento, quando registrerai un agente che richiede il supporto di OAuth.
  • OAUTH_CLIENT_ID: l'identificatore client OAuth 2.0 che hai ottenuto quando hai creato le credenziali OAuth.
  • OAUTH_CLIENT_SECRET: il client secret OAuth 2.0 che hai ottenuto quando hai creato le credenziali OAuth.

  • OAUTH_AUTH_URI: l'URI di autorizzazione. Per autorizzare la tua app, crea un URI di autorizzazione specifico utilizzando i dettagli del file JSON delle credenziali OAuth. Copia il seguente template e sostituisci i segnaposto con i tuoi valori specifici.

    https://accounts.google.com/o/oauth2/v2/auth?client_id=OAUTH_CLIENT_ID&redirect_uri=https%3A%2F%2Fvertexaisearch.cloud.google.com%2Fstatic%2Foauth%2Foauth.html&scope=YOUR_CUSTOM_SCOPES&include_granted_scopes=true&response_type=code&access_type=offline&prompt=consent

    • YOUR_CUSTOM_SCOPES: puoi aggiungere gli ambiti di cui hai bisogno. Ad esempio, la seguente stringa di ambito OAuth richiede l'accesso di sola lettura a Google Drive e Documenti Google.

      scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdrive.readonly%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdocuments.readonly

  • OAUTH_TOKEN_URI: l'URI del token ottenuto durante la creazione delle credenziali OAuth.

Scopri di più sui parametri URI di autorizzazione.

Per assicurarti che l'URI funzioni correttamente, verifica i seguenti campi:

Parametro Valore o azione
client_id Sostituisci con il valore client_id che si trova nel file JSON scaricato.
redirect_uri Non cambiare. Deve essere https://vertexaisearch.cloud.google.com/static/oauth/oauth.html.
scope

Elenca gli ambiti delle API di Google a cui la tua app deve accedere per conto dell'utente. Ad esempio, per concedere l'accesso a BigQuery, utilizza l'ambito https://www.googleapis.com/auth/bigquery e per l'accesso di sola lettura a Documenti Google, utilizza https://www.googleapis.com/auth/documents.readonly.

Se utilizzi più ambiti, separali con uno spazio, che diventa %20 nell'URL.
include_granted_scopes Deve essere true.
response_type Devi essere code per ricevere un codice di autorizzazione.
access_type Impostalo su offline per assicurarti di ricevere un token di aggiornamento.
prompt Imposta su consent per assicurarti che all'utente venga sempre mostrata una schermata per il consenso.

Registra l'agente ADK

Questo esempio di codice mostra come registrare gli agenti ADK.

   curl -X POST \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      -H "Content-Type: application/json" \
      -H "X-Goog-User-Project: PROJECT_ID" \
      "https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents" \
      -d '{
         "displayName": "DISPLAY_NAME",
         "description": "DESCRIPTION",
         "icon": {
            "uri": "ICON_URI"
         },
         "adkAgentDefinition": {
            "provisionedReasoningEngine": {
               "reasoningEngine": "projects/PROJECT_ID/locations/RESOURCE_LOCATION/reasoningEngines/RESOURCE_ID"
            }
         },
         "authorizationConfig": {
            "toolAuthorizations": [
               "projects/PROJECT_NUMBER/locations/global/authorizations/AUTH_ID"
            ]
         }
      }'

Sostituisci le variabili con i valori:

  • ENDPOINT_LOCATION: la località multiregionale per la richiesta API. Specifica uno dei seguenti valori:

    • us per la multi-regione Stati Uniti
    • eu per la multi-regione UE
    • global per la località globale
    Per saperne di più, consulta Specifica una multi-regione per il datastore.

  • PROJECT_ID: l'ID del tuo progetto Google Cloud .

  • PROJECT_NUMBER: il numero del tuo progetto Google Cloud .

  • APP_ID: l'identificatore univoco dell'app Gemini Enterprise.

  • DESCRIPTION: la descrizione dell'agente visualizzata in Gemini Enterprise.

  • ICON_URI: l'URI pubblico dell'icona da visualizzare accanto al nome dell'agente. In alternativa, puoi trasmettere i contenuti del file immagine codificati in Base64 e, in questo caso, utilizzare icon.content.

    • RESOURCE_ID: l'ID dell'endpoint Agent Runtime in cui è stato eseguito il deployment dell'agente ADK. Per saperne di più su come elencare gli agenti ospitati su Agent Runtime e ottenere l'ID risorsa, consulta Elenca gli agenti di cui è stato eseguito il deployment.

    • RESOURCE_LOCATION: la località cloud dell'endpoint di Agent Runtime. Per saperne di più, consulta Località di Agent Runtime.

    • authorization_config: se hai ottenuto i dettagli di autorizzazione e vuoi che l'agente acceda alle risorse Google Cloud per conto dell'utente, aggiungi il campo authorization_config alla risorsa JSON.

Condividi gli agenti con gli utenti

Per consentire agli utenti di accedere a un agente utilizzando l'app web Gemini Enterprise, consulta Condividi un agente.

Elenca gli agenti connessi a un'app

Il seguente esempio di codice mostra come ottenere i dettagli di tutti gli agenti connessi alla tua app:

REST 

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents"

Sostituisci le variabili con i valori:

  • ENDPOINT_LOCATION: la località multiregionale per la richiesta API. Specifica uno dei seguenti valori:
    • us per la multi-regione Stati Uniti
    • eu per la multi-regione UE
    • global per la località globale
    Per saperne di più, consulta Specifica una multi-regione per il datastore.
  • PROJECT_ID: l'ID del tuo progetto Google Cloud .
  • LOCATION: la località multiregionale della tua app: global, us o eu.
  • APP_ID: l'ID della tua app Gemini Enterprise.

Se l'agente non è predefinito da Google, la risposta include un campo name nelle prime righe. Il valore di questo campo contiene l'ID agente alla fine del percorso. Ad esempio, nella seguente risposta, l'ID agente è 12345678901234567890:

{
"name": "projects/123456/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant/agents/12345678901234567890",
...
}

Visualizza i dettagli di un agente ADK

Il seguente esempio di codice mostra come recuperare i dettagli di un agente registrato con Gemini Enterprise:

REST 

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents/AGENT_ID"

Sostituisci le variabili con i valori:

  • ENDPOINT_LOCATION: la località multiregionale per la richiesta API. Specifica uno dei seguenti valori:
    • us per la multi-regione Stati Uniti
    • eu per la multi-regione UE
    • global per la località globale
    Per saperne di più, consulta Specifica una multi-regione per il datastore.
  • PROJECT_ID: l'ID del tuo progetto Google Cloud .
  • LOCATION: la località multiregionale della tua app: global, us o eu.
  • APP_ID: l'ID della tua app Gemini Enterprise.
  • AGENT_ID: l'ID dell'agente. Puoi trovare l'ID agente elencando gli agenti collegati alla tua app.

Aggiorna un agente ADK

Puoi modificare i dettagli di un agente esistente registrato con Gemini Enterprise utilizzando la console Google Cloud o l'API REST.

Console

Per aggiornare l'agente utilizzando la console Google Cloud , segui questi passaggi:

  1. Nella console Google Cloud , vai alla pagina Gemini Enterprise.

    Gemini Enterprise

  2. Fai clic sul nome dell'app che include l'agente che vuoi aggiornare.

  3. Fai clic su Agenti.

  4. Fai clic sul nome dell'agente Agent Runtime che vuoi aggiornare, quindi fai clic su Modifica.

  5. Aggiorna il Nome visualizzato, la Descrizione o il Motore di ragionamento di Agent Runtime.

    Il percorso della risorsa ha il seguente formato:

    projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID

    Per saperne di più su come elencare gli agenti ospitati su Agent Runtime e ottenere il percorso della risorsa, consulta Elenca gli agenti di cui è stato eseguito il deployment.

  6. Fai clic su Salva.

REST

Puoi aggiornare tutti i campi durante la registrazione dell'agente. Tuttavia, i seguenti campi devono essere aggiornati:

  • displayName
  • description

  • reasoningEngine

    Questo esempio di codice mostra come aggiornare la registrazione di un agente ADK esistente:

    curl -X PATCH \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   -H "X-Goog-User-Project: PROJECT_ID" \
   "https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/AGENT_RESOURCE_NAME" \
   -d '{
         "displayName": "DISPLAY_NAME",
         "description": "DESCRIPTION",
         "adkAgentDefinition": {
         "provisionedReasoningEngine": {
            "reasoningEngine":
            "projects/PROJECT_ID/locations/RESOURCE_LOCATION/reasoningEngine
            s/RESOURCE_ID"
         },
      }
   }'

    Sostituisci le variabili con i valori:

  • ENDPOINT_LOCATION: la località multiregionale per la richiesta API. Specifica uno dei seguenti valori:

    • us per la multi-regione Stati Uniti
    • eu per la multi-regione UE
    • global per la località globale
    Per saperne di più, consulta Specifica una multi-regione per il datastore.

  • PROJECT_ID: l'ID del tuo progetto Google Cloud .

  • AGENT_RESOURCE_NAME: il nome della risorsa della registrazione dell'agente da aggiornare.

  • DISPLAY_NAME: obbligatorio. Il nome facile da usare per l'agente che viene visualizzato in Gemini Enterprise.

  • DESCRIPTION: obbligatorio. Una breve spiegazione di ciò che fa l'agente, visibile agli utenti in Gemini Enterprise.

  • RESOURCE_LOCATION: la località cloud dell'endpoint di Agent Runtime. Per saperne di più, consulta Località di Agent Runtime.

  • RESOURCE_ID: l'ID dell'endpoint Agent Runtime in cui è stato eseguito il deployment dell'agente ADK. Per saperne di più su come elencare gli agenti ospitati su Agent Runtime e ottenere l'ID risorsa, consulta Elenca gli agenti di cui è stato eseguito il deployment.

Elimina un agente ADK

Il seguente esempio di codice mostra come eliminare un agente connesso alla tua app:

REST 

curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents/AGENT_ID"

Sostituisci le variabili con i valori:

  • ENDPOINT_LOCATION: la località multiregionale per la richiesta API. Specifica uno dei seguenti valori:
    • us per la multi-regione Stati Uniti
    • eu per la multi-regione UE
    • global per la località globale
    Per saperne di più, consulta Specifica una multi-regione per il datastore.
  • PROJECT_ID: l'ID del tuo progetto Google Cloud .
  • LOCATION: la località multiregionale della tua app: global, us o eu
  • APP_ID: l'ID della tua app Gemini Enterprise.
  • AGENT_ID: l'ID dell'agente. Puoi trovare l'ID agente elencando gli agenti collegati alla tua app.

Località di Agent Runtime

Quando registri o aggiorni un agente, la località di Agent Runtime deve essere compatibile con quella dell'app Gemini Enterprise. Le località non corrispondenti generano un errore.

Per i requisiti di compatibilità, consulta la tabella seguente:

Posizione dell'app Gemini Enterprise Località di Agent Runtime consentite
global Qualsiasi regione Google Cloud supportata
us Qualsiasi regione che inizia con us-, ad esempio us-central1 o us-east4
eu Qualsiasi regione che inizia con europe-, ad esempio europe-west1 o europe-west3

Best practice per prestazioni e affidabilità

Per ridurre al minimo la latenza delle risposte ed evitare timeout delle richieste durante l'esecuzione degli agenti ADK ospitati su Agent Runtime in Gemini Enterprise, segui queste best practice:

  • Riduci al minimo i passaggi sequenziali tra più agenti e i riepiloghi ridondanti: ogni passaggio aggiuntivo tra sub-agenti o andata e ritorno dello strumento aggiunge latenza di inferenza del modello al turno. Evita catene di agenti sequenziali profonde e racchiudi gli agenti secondari con AgentTool(..., skip_summarization=True) quando l'agente parent non deve eseguire un passaggio aggiuntivo del modello per riassumere l'output di un agente secondario.
  • Configura la scalabilità e la contemporaneità del runtime per i workload multiutente: per evitare ritardi di avvio a freddo, accodamento delle richieste e arresti anomali per memoria esaurita (OOM) quando più utenti eseguono query contemporaneamente sull'agente, configura min_instances, resource_limits (cpu e memory) e container_concurrency durante il deployment in Agent Runtime. Per saperne di più, consulta Ottimizza e scala le prestazioni di Agent Runtime.
  • Fissa le versioni dei pacchetti corrispondenti tra la build locale e il runtime cloud: quando esegui il deployment di un agente in Agent Runtime, fissa le versioni esatte di google-adk, google-cloud-aiplatform e cloudpickle nell'elenco requirements del deployment che utilizzi nell'ambiente di build locale per evitare l'overhead di deserializzazione e i ritardi di inizializzazione.
  • Utilizza l'endpoint global per le chiamate ai modelli e i nuovi tentativi degli strumenti associati: quando l'agente ADK richiama i modelli Gemini su Vertex AI, utilizza l'endpoint global (o il throughput riservato) per ridurre la contesa della capacità regionale e configura timeout di connessione espliciti e limiti di nuovi tentativi limitati per le chiamate agli strumenti esterni, in modo che le dipendenze downstream lente non causino timeout dei turni a cascata.