Registrare e gestire gli agenti A2A

Il protocollo Agent2Agent (A2A) è un protocollo di comunicazione aperto e un linguaggio universale per gli agenti. Il protocollo consente agli agenti di diversi builder e piattaforme di scoprirsi a vicenda, collaborare e delegare in modo sicuro le attività. Questo documento spiega come gli amministratori di Gemini Enterprise possono connettere gli agenti creati utilizzando A2A e ospitati su qualsiasi piattaforma a Gemini Enterprise, rendendoli disponibili agli utenti nell'app web Gemini Enterprise.

Prima di iniziare

Assicurati di disporre di quanto segue:

  • Il ruolo Amministratore di Gemini Enterprise.

  • 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, consulta Crea un'app.

  • Un agente che utilizza il protocollo A2A.

    Gemini Enterprise supporta il meccanismo di streaming A2A v0.3.

    Se utilizzi A2A v1.0.0 o versioni successive, utilizza i pacchetti di compatibilità forniti dall'SDK per assicurarti che le funzioni dell'agente con il meccanismo precedente (ad esempio, il pacchetto a2acompat/a2av0 per Go o il pacchetto a2a.compat.v0_3 per Python).

Configurare i dettagli di autorizzazione (facoltativo)

Per gli agenti A2A, puoi utilizzare le credenziali OAuth 2.0 per controllare l'accesso degli utenti finali agli agenti A2A. Tuttavia, se l'agente viene eseguito su Cloud Run e utilizza Identity and Access Management percontrollo dell'accessoi, le credenziali OAuth 2.0 non sono necessarie.

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

Registrare un agente A2A con Gemini Enterprise

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

Console

Per registrare un agente A2A 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 A2A.

  5. Nel campo JSON della scheda dell'agente, inserisci i dettagli della scheda dell'agente in formato JSON. Per un elenco completo dei campi disponibili, consulta la specifica ufficiale del protocollo Agent2Agent (A2A). Il seguente esempio utilizza solo i campi obbligatori.

    Ad esempio:

    {
  "protocolVersion": "0.3",
  "name": "Hello World Agent",
  "description": "Just a hello world agent",
  "url": "https://example.com/myagent",
  "iconUrl": "data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iOTkiIGhlaWdodD0iOTkiIHN0eWxlPSJiYWNrZ3JvdW5kLWNvbG9yOmdyYXk7IiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciPjxwYXRoIGQ9Ik0zMyAwaDMzdjMzSDMzeiBNMCAzM2gzM3YzM0gweiBNNjYgMzNoMzN2MzNINjZ6IE0zMyA2NmgzM3YzM0gzM3oiIGZpbGw9ImJsdWUiLz48L3N2Zz4=",
  "version": "1.0.0",
  "capabilities": {
  },
  "skills": [
    {
      "id": "data-analysis",
      "name": "Data Analysis",
      "description": "Data analysis",
      "tags": []
    }
  ],
  "defaultInputModes": [
    "text/plain"
  ],
  "defaultOutputModes": [
    "text/plain"
  ]
}

  6. Fai clic su Visualizza dettagli agente > Avanti.

  7. Completa la configurazione utilizzando uno dei seguenti metodi:

    • Se vuoi che l'agente acceda alle risorse Google Cloud per tuo conto, segui questi passaggi:

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

      2. Inserisci gli ambiti.

      3. Fai clic su Fine.

    • Se non vuoi che l'agente acceda alle risorse Google Cloud per tuo conto, fai clic su Ignora e termina.

REST

Per registrare un agente A2A 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 comando seguente per registrare la risorsa di autorizzazione che hai creato nella sezione (Facoltativo) Configura i dettagli di autorizzazione 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 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 multi-regione per il datastore.
  • LOCATION: la regione multipla 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 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 modello 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 in 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 quando hai creato le 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 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

Elenca gli ambiti dell'API 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 in sola lettura a Google Docs, 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 avere code per ricevere un codice di autorizzazione.
access_type Imposta su offline per assicurarti di ricevere un token di aggiornamento.
prompt Impostato su consent per contribuire a garantire che all'utente venga sempre mostrata una schermata per il consenso.

Registrare l'agente A2A

Per creare e registrare un agente con Gemini Enterprise, utilizza il metodo agents.create. Il seguente comando utilizza solo i campi obbligatori. Per un elenco completo dei campi disponibili, consulta la specifica ufficiale del protocollo Agent2Agent (A2A).

Esegui questo comando per registrare l'agente A2A con Gemini Enterprise:

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents \
-d '
{
  "name": "AGENT_NAME",
  "displayName": "AGENT_DISPLAY_NAME",
  "description": "AGENT_DESCRIPTION",
  "a2aAgentDefinition": {
    "jsonAgentCard": "{\"protocolVersion\":\"PROTOCOLVERSION\",\"name\":\"AGENT_NAME\",\"description\":\"AGENT_DESCRIPTION\",\"url\":\"AGENT_URL\",\"version\":\"AGENT_VERSION\",\"defaultInputModes\":[\"INPUT_MODE\"],\"defaultOutputModes\":[\"OUTPUT_MODE\"],\"capabilities\":{ CAPABILITIES },\"skills\":[SKILLS]}"
  },
  "authorizationConfig": {
    "agentAuthorization": "projects/PROJECT_ID/locations/LOCATION/authorizations/AUTH_ID"
  }
}
'

Sostituisci quanto segue:

  • 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 multi-regione per il datastore.
  • LOCATION: la multiregione del datastore: global, us o eu
  • PROJECT_ID: l'ID progetto.
  • APP_ID: l'ID dell'app con cui vuoi registrare l'agente.
  • AGENT_NAME: l'identificatore univoco dell'agente.
  • AGENT_DISPLAY_NAME: il nome dell'agente visualizzato nell'app web.
  • AGENT_DESCRIPTION: la descrizione di ciò che l'agente può fare.
  • PROTOCOLVERSION: la versione del protocollo A2A supportata dall'agente. Per ulteriori informazioni sulle versioni supportate, consulta le note di rilascio di A2A.
  • AGENT_URL: l'URL dell'endpoint dell'agente.
  • AGENT_VERSION: la versione dell'agente.
  • INPUT_MODE: il tipo di supporto di input predefinito. Ad esempio, application/json o text/plain.
  • OUTPUT_MODE: il tipo di media di output predefinito. Ad esempio, text/plain" o image/png.
  • CAPABILITIES: un oggetto JSON contenente le funzionalità A2A supportate. Ad esempio: \"streaming\": true o \"pushNotifications\": false.
  • SKILLS: un elenco dell'oggetto AgentSkill offerto dall'agente.
  • 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.

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 multi-regione 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",
...
}

Visualizzare i dettagli di un agente A2A

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 multi-regione 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 A2A

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

Console

Per aggiornare un agente A2A 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 A2A (personalizzato) da aggiornare, quindi fai clic su Modifica.

  5. Nel campo JSON della scheda dell'agente, aggiorna i dettagli della scheda dell'agente in formato JSON. Per un elenco completo dei campi disponibili, consulta la specifica ufficiale del protocollo Agent2Agent (A2A). Il seguente esempio utilizza solo i campi obbligatori.

    Ad esempio:

    {
  "protocolVersion": "0.3",
  "name": "Hello World Agent",
  "description": "Just a hello world agent",
  "url": "https://example.com/myagent",
  "iconUrl": "data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iOTkiIGhlaWdodD0iOTkiIHN0eWxlPSJiYWNrZ3JvdW5kLWNvbG9yOmdyYXk7IiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciPjxwYXRoIGQ9Ik0zMyAwaDMzdjMzSDMzeiBNMCAzM2gzM3YzM0gweiBNNjYgMzNoMzN2MzNINjZ6IE0zMyA2NmgzM3YzM0gzM3oiIGZpbGw9ImJsdWUiLz48L3N2Zz4=",
  "version": "1.1.0",
  "capabilities": {
  },
  "skills": [
    {
      "id": "data-analysis",
      "name": "Data Analysis",
      "description": "Data analysis",
      "tags": []
    }
  ],
  "defaultInputModes": [
    "text/plain"
  ],
  "defaultOutputModes": [
    "text/plain"
  ]
}

  6. Fai clic su Salva.

REST

Per aggiornare i dettagli di un agente A2A registrato con Gemini Enterprise, utilizza il metodo agents.patch. Il seguente comando utilizza solo i campi obbligatori. Per un elenco completo dei campi disponibili, consulta le specifiche ufficiali del protocollo Agent2Agent (A2A).

Esegui questo comando per aggiornare l'agente A2A con Gemini Enterprise:

curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents/AGENT_ID \
-d '
{
  "name": "AGENT_NAME",
  "displayName": "AGENT_DISPLAY_NAME",
  "description": "AGENT_DESCRIPTION",
  "a2aAgentDefinition": {
    "jsonAgentCard": "{\"protocolVersion\":\"PROTOCOLVERSION\",\"name\":\"AGENT_NAME\",\"description\":\"AGENT_DESCRIPTION\",\"url\":\"AGENT_URL\",\"version\":\"AGENT_VERSION\",\"defaultInputModes\":[\"INPUT_MODE\"],\"defaultOutputModes\":[\"OUTPUT_MODE\"],\"capabilities\":{ CAPABILITIES },\"skills\":[SKILLS]}"
  },
  "authorizationConfig": {
    "agentAuthorization": "projects/PROJECT_ID/locations/LOCATION/authorizations/AUTH_ID"
  }
}
'

Sostituisci quanto segue:

  • 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 multi-regione per il datastore.
  • LOCATION: la multiregione del datastore: global, us o eu.
  • PROJECT_ID: l'ID progetto.
  • APP_ID: l'ID dell'app per cui vuoi registrare l'agente.
  • AGENT_ID: l'ID dell'agente. Puoi trovare l'ID agente elencando gli agenti connessi alla tua app.
  • AGENT_NAME: l'identificatore univoco dell'agente.
  • AGENT_DISPLAY_NAME: il nome dell'agente visualizzato nell'app web.
  • AGENT_DESCRIPTION: la descrizione di ciò che l'agente può fare.
  • PROTOCOLVERSION: la versione del protocollo A2A supportata dall'agente. Per ulteriori informazioni sulle versioni supportate, consulta le note di rilascio di A2A.
  • AGENT_URL: l'URL dell'endpoint dell'agente.
  • AGENT_VERSION: la versione dell'agente.
  • INPUT_MODE: il tipo di supporto di input predefinito. Ad esempio, application/json o text/plain.
  • OUTPUT_MODE: il tipo di media di output predefinito. Ad esempio, text/plain o image/png.
  • CAPABILITIES: un oggetto JSON contenente le funzionalità A2A supportate. Ad esempio: \"streaming\": true o \"pushNotifications\": false.
  • SKILLS: un elenco dell'oggetto AgentSkill offerto dall'agente.
  • 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.

Eliminare un agente A2A

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 multi-regione 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.

Passaggi successivi

  • Utilizza l'agente che hai registrato con Gemini Enterprise nell'app web.