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:

Configura i dettagli dell'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 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 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. Assegna uno dei seguenti valori:
    • us- per la multiregione 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, quando registri 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 ottenuto quando hai creato le credenziali OAuth. Ha il seguente formato: https://accounts.google.com/o/oauth2/v2/auth?client_id=CLIENT_ID&redirect_uri=https%3A%2F%2Fvertexaisearch.cloud.google.com%2Fstatic%2Foauth%2Foauth.html&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fbigquery&include_granted_scopes=true&response_type=code&access_type=offline&prompt=consent
  • 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 > Aggiungi agenti.

  4. Nella sezione Scegli un tipo di agente, fai clic su Aggiungi per Agente personalizzato tramite Agent Engine.

  5. Se vuoi che l'agente acceda alle risorse Google Cloud per tuo conto, 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 e non può essere modificato in un secondo momento.

    3. Inserisci ID client, Client secret, URI di autorizzazione e URI token che hai generato nella sezione Ottieni dettagli di autorizzazione.

    4. Fai clic su Aggiungi autorizzazione.

  6. Fai clic su Avanti.

  7. 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. Configura le impostazioni dello strumento:

      1. Inserisci una descrizione per il campo Descrizione dello strumento. Questa descrizione viene utilizzata dal modello LLM per comprendere lo scopo dello strumento e decidere quando utilizzarlo.

      2. Inserisci il nome nel campo Nome parametro di input. Questo è il nome del parametro per la chiamata di funzione. Questo nome del parametro suggerisce all'LLM il tipo di input previsto, ad esempio un question, command o search_query.

      3. Inserisci la descrizione per il campo Descrizione del parametro di input. Questa descrizione del parametro fornisce all'LLM maggiori informazioni sul parametro, ad esempio i contenuti previsti e le azioni da eseguire.

    5. 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_ID/locations/global/authorizations/AUTH_ID"
   ]
   }
   }'

Sostituisci le variabili con i valori:

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

    • us- per la multiregione 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.

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

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. Assegna uno dei seguenti valori:
    • us- per la multiregione 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 multiregione 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. Assegna uno dei seguenti valori:
    • us- per la multiregione 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 multiregione 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 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.

  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. Assegna uno dei seguenti valori:

    • us- per la multiregione 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 ciò che 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. Assegna uno dei seguenti valori:
    • us- per la multiregione 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.

Località del motore di ragionamento

Per effettuare la chiamata API alla posizione corretta del motore di ragionamento, utilizza il seguente grafico:

Località cloud che stai chiamando Posizione del motore di ragionamento
us us-central1
eu europe-west1
altri (incluso global) us-central1