Registrare e gestire gli agenti A2A

Agent-to-Agent (A2A) è un protocollo di comunicazione aperto e un linguaggio universale per gli agenti. 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 per gli 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, consulta Crea un'app.

  • Un agente che utilizza il protocollo A2A.

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 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 diventa 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). L'esempio seguente utilizza solo i campi obbligatori.

    Ad esempio:

    {
  "protocolVersion": "v1.0",
  "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 Scopi.

      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 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 le specifiche ufficiali 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. 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
  • 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 che l'agente offre.
  • 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. 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",
...
}

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. 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 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": "v3.0",
  "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. 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 tuo 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 che l'agente offre.
  • 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. 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.

Passaggi successivi

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