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 di 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 il progettoGoogle Cloud 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 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 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. 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_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 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.

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

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