Registrare e gestire gli agenti ADK ospitati su Vertex AI Agent Engine

Questa pagina descrive come gli amministratori di Gemini Enterprise possono registrare gli agenti dell'Agent Development Kit (ADK) ospitati su Vertex AI Agent Engine in modo che possano essere resi disponibili agli utenti nell'app web Gemini Enterprise.

Prima di iniziare

Assicurati di disporre di quanto segue:

  • Il ruolo Discovery Engine Admin.

  • Abilita l'API Discovery Engine. Per abilitare l'API Discovery Engine per il progetto Google Cloud, nella console Google Cloud , vai alla pagina API Discovery Engine.

    Vai all'API Discovery Engine

  • Un'app Gemini Enterprise esistente. Per creare un'app, vedi Crea un'app.

  • Un agente ADK ospitato su Vertex AI Agent Engine. Per saperne di più, consulta la panoramica dell'Agent Development Kit.

Configura i dettagli di autorizzazione

Crea credenziali OAuth 2.0 per l'agente per accedere alle risorse Google Cloud , come le tabelle BigQuery, per conto di un utente.

Ottenere i dettagli dell'autorizzazione

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 Google Cloud progetto 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 OAuth client created (Client OAuth creato), fai clic su Download JSON (Scarica JSON). Il file JSON scaricato include Client ID, Authorization URI, Token URI e Client secret per ilGoogle Cloud progetto selezionato. Questi dettagli sono necessari per creare una risorsa di autorizzazione:

Aggiungere una risorsa di autorizzazione a Gemini Enterprise

Esegui questo comando per registrare una risorsa di autorizzazione con Gemini Enterprise:

REST

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/LOCATION/authorizations?authorizationId=AUTH_ID" \
   -d '{
      "name": "projects/PROJECT_ID/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.
  • ENDPOINT_LOCATION: la multiregione per la tua richiesta API. Specifica uno dei seguenti valori:
    • us per la multi-regione Stati Uniti
    • eu per la multiregione EU
    • global per la località globale
    Per saperne di più, consulta Specifica una regione multipla per il datastore.
  • LOCATION: la multiregione 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 durante la registrazione di un agente che richiede il supporto 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 modello 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

    Suddivisione dei parametri

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

    Parametro Valore o azione
    client_id Sostituisci con client_id che si trova nel file JSON scaricato.
    redirect_uri Non modificare. Deve essere https://vertexaisearch.cloud.google.com/static/oauth/oauth.html.
    scope Azione richiesta: elenca gli ambiti delle API di Google di cui la tua app ha bisogno (ad esempio, https://www.googleapis.com/auth/bigquery). Se utilizzi più ambiti, separali con uno spazio, che diventa %20 nell'URL.
    include_granted_scopes Deve essere true.
    response_type Devi avere code per ricevere un codice di autorizzazione.
    access_type Imposta su offline per assicurarti di ricevere un token di aggiornamento.
    prompt Imposta su consent per assicurarti che all'utente venga sempre mostrata una schermata di consenso.

  • OAUTH_TOKEN_URI: l'URI del token ottenuto quando hai creato le credenziali OAuth.

Registrare un agente ADK con Gemini Enterprise

Puoi registrare il tuo agente ADK con Gemini Enterprise utilizzando la consoleGoogle Cloud o l'API REST. In questo modo, l'agente diventa 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 motore agente. Viene visualizzata la pagina Autorizzazioni.

  6. Se vuoi che l'agente acceda alle risorse Google Cloud per tuo conto, ogni risorsa richiede un'autorizzazione. Per configurare un'autorizzazione per una singola risorsa:

    1. Fai clic su Aggiungi autorizzazione.

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

    3. Inserisci i valori che hai generato nella sezione Ottieni dettagli dell'autorizzazione 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. Fai clic su Fine.

  7. Fai clic su Avanti.

  8. Per configurare l'agente:

    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 il tuo agente in risposta a una query dell'utente.

    3. Inserisci il percorso della risorsa del motore di ragionamento di Agent Engine. Il percorso della risorsa ha il seguente formato:

          https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/ADK_RESOURCE_ID

      Per ulteriori informazioni su come elencare gli agenti ospitati su Vertex AI Agent Engine e ottenere il percorso della risorsa, consulta Elenca gli agenti di cui è stato eseguito il deployment.

    4. Fai clic su Crea.

REST

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"
      },
      "adk_agent_definition": {
         "provisioned_reasoning_engine": {
            "reasoning_engine":
            "projects/PROJECT_ID/locations/REASONING_ENGINE_LOCATION/reasoningEngines/ADK_RESOURCE_ID"
         }
      },
   "authorization_config": {


   "tool_authorizations": [
   "projects/PROJECT_NUMBER/locations/global/authorizations/AUTH_ID"
   ]
   }
   }'

Sostituisci le variabili con i valori:

  • ENDPOINT_LOCATION: la multiregione per la tua richiesta API. Specifica uno dei seguenti valori:

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

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

  • PROJECT_NUMBER: il numero del tuo Google Cloud progetto.

  • 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 vicino al nome dell'agente. In alternativa, puoi trasmettere i contenuti del file immagine codificati in Base64 e, in questo caso, utilizzare icon.content.

  • ADK_RESOURCE_ID: l'ID dell'endpoint del motore di ragionamento in cui è stato eseguito il deployment dell'agente ADK. Per ulteriori informazioni su come elencare gli agenti ospitati su Vertex AI Agent Engine e ottenere l'ID risorsa, consulta Elenca gli agenti di cui è stato eseguito il deployment.

  • REASONING_ENGINE_LOCATION: la posizione cloud del motore di ragionamento. Per saperne di più, consulta Posizione del motore di ragionamento.

  • authorizationConfig: 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.

     * <code><var>AUTH_ID</var></code>: the value that you used for
    <var>AUTH_ID</var> in the [Configure authorization details](#authorize-your-adk-agent)
    section.

Aggiungere utenti autorizzati

Per aggiungere utenti con autorizzazioni a un agente ADK utilizzando la console Google Cloud , vedi Aggiungere o modificare utenti e le relative autorizzazioni.

Elencare gli agenti connessi a un'app

L'esempio di codice seguente 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 multiregione per la tua richiesta API. Specifica uno dei seguenti valori:
    • us per la multi-regione Stati Uniti
    • eu per la multiregione EU
    • global per la località globale
    Per saperne di più, consulta Specifica una regione multipla per il datastore.
  • PROJECT_ID: l'ID del tuo Google Cloud progetto.
  • LOCATION: la regione multipla 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 multiregione per la tua richiesta API. Specifica uno dei seguenti valori:
    • us per la multi-regione Stati Uniti
    • eu per la multiregione EU
    • global per la località globale
    Per saperne di più, consulta Specifica una regione multipla per il datastore.
  • PROJECT_ID: l'ID del tuo Google Cloud progetto.
  • LOCATION: la regione multipla 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 connessi 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 da aggiornare.

  3. Fai clic su Agenti.

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

  5. Aggiorna il nome visualizzato, la descrizione o il motore di ragionamento di Agent Engine.

    Il percorso della risorsa ha il seguente formato:

      https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/ADK_RESOURCE_ID

    Per saperne di più su come elencare gli agenti ospitati su Vertex AI Agent Engine 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, devono essere aggiornati i seguenti campi:

  • 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/REASONING_ENGINE_LOCATION/reasoningEngine
            s/ADK_RESOURCE_ID"
         },
      }
}'

    Sostituisci le variabili con i valori:

  • ENDPOINT_LOCATION: la multiregione per la tua richiesta API. Specifica uno dei seguenti valori:

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

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

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

  • DISPLAY_NAME: obbligatorio. Il nome intuitivo dell'agente visualizzato in Gemini Enterprise.

  • DESCRIPTION: obbligatorio. Una breve spiegazione di cosa fa il tuo agente, visibile agli utenti di Gemini Enterprise.

  • REASONING_ENGINE_LOCATION: obbligatorio. La posizione cloud del motore di ragionamento in cui stai creando un agente. Per ulteriori informazioni, consulta Posizione del motore di ragionamento.

  • ADK_RESOURCE_ID: l'ID dell'endpoint del motore di ragionamento in cui è stato eseguito il deployment dell'agente ADK. Per ulteriori informazioni su come elencare gli agenti ospitati su Vertex AI Agent Engine e ottenere l'ID risorsa, consulta Elenca gli agenti di cui è stato eseguito il deployment.

Eliminare 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 multiregione per la tua richiesta API. Specifica uno dei seguenti valori:
    • us per la multi-regione Stati Uniti
    • eu per la multiregione EU
    • global per la località globale
    Per saperne di più, consulta Specifica una regione multipla per il datastore.
  • PROJECT_ID: l'ID del tuo Google Cloud progetto.
  • LOCATION: la multi-regione 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 connessi alla tua app.

Località del motore di ragionamento

Quando registri o aggiorni un agente ADK, la posizione della risorsa del motore di ragionamento sottostante deve essere compatibile con la posizione dell'agente. Le posizioni del motore di ragionamento dipendono dalla posizione dell'agente come segue:

  • Agenti globali:se il tuo agente si trova nella località global, puoi utilizzare un motore di ragionamento di cui è stato eseguito il deployment in qualsiasi regione supportata.

  • Agenti multiregionali:

    • Se il tuo agente si trova nella multiregione us, il motore di ragionamento deve essere implementato in una regione con sede negli Stati Uniti, ad esempio us-central1, us-east1 o us-west1.
    • Se il tuo agente si trova nella multiregione eu, il motore di ragionamento deve essere implementato in una regione europea, ad esempio europe-west1, europe-west2 o europe-central2. Ecco una tabella riepilogativa:
Posizione dell'agente Posizioni del motore di ragionamento consentite
global Qualsiasi Google Cloud regione 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

Le località non corrispondenti generano un errore durante la registrazione o l'aggiornamento dell'agente.