Registra y administra agentes de A2A

El protocolo Agent2Agent (A2A) es un protocolo de comunicación abierto y un lenguaje universal para los agentes. El protocolo permite que los agentes de diferentes creadores y plataformas se descubran, colaboren y deleguen tareas de forma segura. En este documento, se explica cómo los administradores de Gemini Enterprise pueden conectar agentes creados con A2A y alojados en cualquier plataforma a Gemini Enterprise, lo que los pone a disposición de los usuarios en la app web de Gemini Enterprise.

Antes de comenzar

Asegúrate de tener lo siguiente:

  • El rol de administrador de Gemini Enterprise

  • Habilita la API de Discovery Engine. Para habilitar la API de Discovery Engine para el proyecto de Google Cloud, en la consola de Google Cloud, ve a la página de la API de Discovery Engine. Google Cloud

    Ir a la API de Discovery Engine

  • Una app de Gemini Enterprise existente. Para crear una app, consulta Cómo crear una app.

  • Es un agente que usa el protocolo A2A.

    Gemini Enterprise admite el mecanismo de transmisión A2A v0.3.

    Si usas A2A v1.0.0 o una versión posterior, usa los paquetes de compatibilidad que proporciona el SDK para asegurarte de que tu agente funcione con el mecanismo anterior (por ejemplo, el paquete a2acompat/a2av0 para Go o el paquete a2a.compat.v0_3 para Python).

Configura los detalles de autorización (opcional)

En el caso de los agentes de A2A, puedes usar las credenciales de OAuth 2.0 para controlar el acceso de los usuarios finales a los agentes de A2A. Sin embargo, si el agente se ejecuta en Cloud Run y usa Identity and Access Management para el control de acceso, no se requieren las credenciales de OAuth 2.0.

  1. En la consola de Google Cloud , en la página APIs y servicios, ve a la página Credenciales.

    Ir a Credenciales

  2. Selecciona el proyecto Google Cloud que tiene la fuente de datos a la que quieres que acceda el agente. Por ejemplo, selecciona el proyecto que contiene el conjunto de datos de BigQuery que deseas que consulte el agente.

  3. Haz clic en Crear credenciales y, luego, selecciona ID de cliente OAuth.

  4. En Tipo de aplicación, selecciona Aplicación web.

  5. En la sección URI de redireccionamiento autorizados, agrega los siguientes URI:

    • https://vertexaisearch.cloud.google.com/oauth-redirect
    • https://vertexaisearch.cloud.google.com/static/oauth/oauth.html

  6. Haz clic en Crear.

  7. En el panel Se creó el cliente de OAuth, haz clic en Descargar JSON. El archivo JSON descargado incluye Client ID, Authorization URI, Token URI y Client secret para el proyectoGoogle Cloud seleccionado. Necesitas estos detalles para crear un recurso de autorización.

Registra un agente A2A en Gemini Enterprise

Puedes registrar tu agente A2A en Gemini Enterprise con la consola deGoogle Cloud o la API de REST. Esto hace que el agente esté disponible para los usuarios dentro de una app de Gemini Enterprise.

Console

Para registrar un agente de A2A con la consola de Google Cloud , sigue estos pasos:

  1. En la consola de Google Cloud , ve a la página Gemini Enterprise.

    Gemini Enterprise

  2. Haz clic en el nombre de la app con la que deseas registrar el agente.

  3. Haz clic en Agentes > Agregar agentes.

  4. En la sección Elige un tipo de agente, haz clic en Agregar para Agente personalizado a través de A2A.

  5. En el campo JSON de la tarjeta del agente, ingresa los detalles de la tarjeta del agente en formato JSON. Para obtener una lista completa de los campos disponibles, consulta la Especificación oficial del protocolo Agent2Agent (A2A). En el siguiente ejemplo, solo se usan los campos obligatorios.

    Por ejemplo:

    {
  "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. Haz clic en Preview agent details > Next.

  7. Completa la configuración con uno de los siguientes métodos:

    • Si quieres que el agente acceda a Google Cloud recursos en tu nombre, sigue estos pasos:

      1. Ingresa el ID de cliente, el secreto de cliente, el URI de autorización y el URI de token que generaste en la sección Obtén detalles de autorización.

      2. Ingresa los permisos.

      3. Haz clic en Finalizar.

    • Si no quieres que el agente acceda a los recursos Google Cloud en tu nombre, haz clic en Omitir y finalizar.

REST

Para registrar un agente de A2A con la API de REST, sigue estos pasos:

Agrega el recurso de autorización a Gemini Enterprise (opcional)

Si el agente debe acceder a recursos Google Cloud en nombre de un usuario, ejecuta el siguiente comando para registrar el recurso de autorización que creaste en la sección Configura los detalles de autorización (opcional) 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"
      }
   }'

Reemplaza lo siguiente:

  • PROJECT_ID: el ID de tu proyecto.
  • PROJECT_NUMBER: Es el número de tu proyecto de Google Cloud .
  • ENDPOINT_LOCATION: Es la región múltiple para tu solicitud a la API. Especifica uno de los siguientes valores:
    • us para la multirregión de EE.UU.
    • eu para la multirregión de la UE
    • global para la ubicación global
    Para obtener más información, consulta Cómo especificar una región múltiple para tu almacén de datos.
  • LOCATION: Es la multirregión de tu almacén de datos: global, us o eu.
  • AUTH_ID: Es el ID del recurso de autorización. Es un ID alfanumérico arbitrario que defines. Deberás hacer referencia a este ID más adelante cuando registres un agente que requiera compatibilidad con OAuth.
  • OAUTH_CLIENT_ID: Es el identificador de cliente de OAuth 2.0 que obtuviste cuando creaste las credenciales de OAuth.
  • OAUTH_CLIENT_SECRET: El secreto del cliente de OAuth 2.0 que obtuviste cuando creaste las credenciales de OAuth.

  • OAUTH_AUTH_URI: Es el URI de autorización. Para autorizar tu app, crea un URI de autorización específico con los detalles de tu archivo JSON de credenciales de OAuth. Copia la siguiente plantilla y reemplaza los marcadores de posición por tus valores específicos.

    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: Puedes agregar los alcances que necesites. Por ejemplo, la siguiente cadena de permisos de OAuth solicita acceso de solo lectura a tu Google Drive y Documentos de Google.

      scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdrive.readonly%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdocuments.readonly

  • OAUTH_TOKEN_URI: Es el URI del token que obtuviste cuando creaste las credenciales de OAuth.

Obtén más información sobre los parámetros del URI de autorización.

Para asegurarte de que el URI funcione correctamente, verifica los siguientes campos:

Parámetro Valor o acción
client_id Reemplaza client_id por el valor que se encuentra en el archivo JSON que descargaste.
redirect_uri No cambiar Debe ser https://vertexaisearch.cloud.google.com/static/oauth/oauth.html.
scope

Enumera los alcances de la API de Google a los que tu app necesita acceder en nombre del usuario. Por ejemplo, para otorgar acceso a BigQuery, usa el alcance https://www.googleapis.com/auth/bigquery y, para otorgar acceso de solo lectura a Documentos de Google, usa https://www.googleapis.com/auth/documents.readonly.

Si usas varios permisos, sepáralos con un espacio, que se convierte en %20 en la URL.
include_granted_scopes Debe ser true.
response_type Debe ser code para recibir un código de autorización.
access_type Se establece en offline para garantizar que recibas un token de actualización.
prompt Se establece en consent para garantizar que siempre se muestre una pantalla de consentimiento al usuario.

Registra tu agente A2A

Para crear y registrar un agente con Gemini Enterprise, usa el método agents.create. El siguiente comando solo usa los campos obligatorios. Para obtener una lista completa de los campos disponibles, consulta la Especificación oficial del protocolo Agent2Agent (A2A).

Ejecuta este comando para registrar tu agente de A2A en 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"
  }
}
'

Reemplaza lo siguiente:

  • ENDPOINT_LOCATION: Es la región múltiple para tu solicitud a la API. Especifica uno de los siguientes valores:
    • us para la multirregión de EE.UU.
    • eu para la multirregión de la UE
    • global para la ubicación global
    Para obtener más información, consulta Cómo especificar una región múltiple para tu almacén de datos.
  • LOCATION: Es la multirregión de tu almacén de datos: global, us o eu.
  • PROJECT_ID: el ID de tu proyecto.
  • APP_ID: Es el ID de la app con la que deseas registrar el agente.
  • AGENT_NAME: Es el identificador único del agente.
  • AGENT_DISPLAY_NAME: Es el nombre del agente que se muestra en la app web.
  • AGENT_DESCRIPTION: Es la descripción de lo que puede hacer el agente.
  • PROTOCOLVERSION: Es la versión del protocolo A2A que admite el agente. Para obtener más información sobre las versiones compatibles, consulta las notas de la versión de A2A.
  • AGENT_URL: Es la URL del extremo del agente.
  • AGENT_VERSION: Es la versión del agente.
  • INPUT_MODE: Es el tipo de medio de entrada predeterminado. Por ejemplo, application/json o text/plain.
  • OUTPUT_MODE: Es el tipo de medio de salida predeterminado. Por ejemplo, text/plain" o image/png.
  • CAPABILITIES: Es un objeto JSON que contiene las funciones de A2A compatibles. Por ejemplo, \"streaming\": true o \"pushNotifications\": false.
  • SKILLS: Es una lista del objeto AgentSkill que ofrece el agente.
  • authorizationConfig: Si obtuviste los detalles de autorización y quieres que el agente acceda a los recursos de Google Cloud en nombre del usuario, agrega el campo authorization_config a tu recurso JSON.

Enumera los agentes conectados a una app

En la siguiente muestra de código, se muestra cómo puedes obtener los detalles de todos los agentes conectados a tu 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"

Reemplaza las variables por valores:

  • ENDPOINT_LOCATION: Es la región múltiple para tu solicitud a la API. Especifica uno de los siguientes valores:
    • us para la multirregión de EE.UU.
    • eu para la multirregión de la UE
    • global para la ubicación global
    Para obtener más información, consulta Cómo especificar una región múltiple para tu almacén de datos.
  • PROJECT_ID: Es el ID de tu proyecto de Google Cloud .
  • LOCATION: Es la multirregión de tu app: global, us o eu.
  • APP_ID: Es el ID de tu app de Gemini Enterprise.

Si Google no creó previamente tu agente, la respuesta incluirá un campo name en las primeras líneas. El valor de este campo contiene el ID del agente al final de la ruta. Por ejemplo, en la siguiente respuesta, el ID del agente es 12345678901234567890:

{
"name": "projects/123456/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant/agents/12345678901234567890",
...
}

Cómo ver los detalles de un agente de A2A

En el siguiente muestra de código, se muestra cómo puedes recuperar los detalles de un agente que se registró 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"

Reemplaza las variables por valores:

  • ENDPOINT_LOCATION: Es la región múltiple para tu solicitud a la API. Especifica uno de los siguientes valores:
    • us para la multirregión de EE.UU.
    • eu para la multirregión de la UE
    • global para la ubicación global
    Para obtener más información, consulta Cómo especificar una región múltiple para tu almacén de datos.
  • PROJECT_ID: Es el ID de tu proyecto de Google Cloud .
  • LOCATION: Es la multirregión de tu app: global, us o eu.
  • APP_ID: Es el ID de tu app de Gemini Enterprise.
  • AGENT_ID: Es el ID del agente. Puedes encontrar el ID del agente enumerando los agentes conectados a tu app.

Actualiza un agente de A2A

Puedes modificar los detalles de un agente de A2A existente registrado en Gemini Enterprise con la consola de Google Cloud o la API de REST.

Console

Para actualizar un agente de A2A con la consola de Google Cloud , sigue estos pasos:

  1. En la consola de Google Cloud , ve a la página Gemini Enterprise.

    Gemini Enterprise

  2. Haz clic en el nombre de la app que incluye el agente que deseas actualizar.

  3. Haz clic en Agentes.

  4. Haz clic en el nombre del agente de A2A (personalizado) que deseas actualizar y, luego, en Editar.

  5. En el campo JSON de la tarjeta del agente, actualiza los detalles de la tarjeta del agente en formato JSON. Para obtener una lista completa de los campos disponibles, consulta la Especificación oficial del protocolo Agent2Agent (A2A). En el siguiente ejemplo, solo se usan los campos obligatorios.

    Por ejemplo:

    {
  "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. Haz clic en Guardar.

REST

Para actualizar los detalles de un agente A2A registrado en Gemini Enterprise, usa el método agents.patch. El siguiente comando solo usa los campos obligatorios. Para obtener una lista completa de los campos disponibles, consulta la Especificación oficial del protocolo Agent2Agent (A2A).

Ejecuta este comando para actualizar tu agente de 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"
  }
}
'

Reemplaza lo siguiente:

  • ENDPOINT_LOCATION: Es la región múltiple para tu solicitud a la API. Especifica uno de los siguientes valores:
    • us para la multirregión de EE.UU.
    • eu para la multirregión de la UE
    • global para la ubicación global
    Para obtener más información, consulta Cómo especificar una región múltiple para tu almacén de datos.
  • LOCATION: Es la multirregión de tu almacén de datos: global, us o eu.
  • PROJECT_ID: el ID de tu proyecto.
  • APP_ID: Es el ID de la app en la que deseas registrar el agente.
  • AGENT_ID: Es el ID del agente. Puedes encontrar el ID del agente enumerando los agentes conectados a tu app.
  • AGENT_NAME: Es el identificador único del agente.
  • AGENT_DISPLAY_NAME: Es el nombre del agente que se muestra en la app web.
  • AGENT_DESCRIPTION: Es la descripción de lo que puede hacer el agente.
  • PROTOCOLVERSION: Es la versión del protocolo A2A que admite el agente. Para obtener más información sobre las versiones compatibles, consulta las notas de la versión de A2A.
  • AGENT_URL: Es la URL del extremo del agente.
  • AGENT_VERSION: Es la versión del agente.
  • INPUT_MODE: Es el tipo de medio de entrada predeterminado. Por ejemplo, application/json o text/plain.
  • OUTPUT_MODE: Es el tipo de medio de salida predeterminado. Por ejemplo, text/plain o image/png.
  • CAPABILITIES: Es un objeto JSON que contiene las funciones de A2A compatibles. Por ejemplo, \"streaming\": true o \"pushNotifications\": false.
  • SKILLS: Es una lista del objeto AgentSkill que ofrece el agente.
  • authorizationConfig: Si obtuviste los detalles de autorización y quieres que el agente acceda a los recursos de Google Cloud en nombre del usuario, agrega el campo authorization_config a tu recurso JSON.

Borra un agente de A2A

En la siguiente muestra de código, se indica cómo puedes borrar un agente conectado a tu 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"

Reemplaza las variables por valores:

  • ENDPOINT_LOCATION: Es la región múltiple para tu solicitud a la API. Especifica uno de los siguientes valores:
    • us para la multirregión de EE.UU.
    • eu para la multirregión de la UE
    • global para la ubicación global
    Para obtener más información, consulta Cómo especificar una región múltiple para tu almacén de datos.
  • PROJECT_ID: Es el ID de tu proyecto de Google Cloud .
  • LOCATION: Es la multirregión de tu app: global, us o eu.
  • APP_ID: Es el ID de tu app de Gemini Enterprise.
  • AGENT_ID: Es el ID del agente. Puedes encontrar el ID del agente enumerando los agentes conectados a tu app.

¿Qué sigue?

  • Usa el agente que registraste en Gemini Enterprise en la app web.