Aloja un agente de A2UI con Cloud Run

En este instructivo, se explica cómo implementar un agente de agente a agente (A2A), creado con el Kit de desarrollo de agentes (ADK) y la extensión A2UI, en Cloud Run. También aprenderás a registrar el agente implementado en Gemini Enterprise.

En este ejemplo, se usa código de muestra disponible públicamente. El código de muestra de este instructivo tiene la siguiente estructura de carpetas.

Estructura de carpetas del instructivo

El proyecto tiene la siguiente estructura de carpetas:

Archivo/Directorio Descripción
/samples/community/agent/adk/gemini_enterprise/v0_9 Directorio que contiene datos y configuraciones de ejemplo para este instructivo
__init__.py Marca el directorio como un paquete de Python.
__main__.py Es el punto de entrada para ejecutar el agente de forma local.
agent.py Define el agente, sus habilidades y su comportamiento.
agent_executor.py Administra el flujo de ejecución y las interacciones de herramientas.
deploy.sh Secuencia de comandos para compilar y, luego, implementar el agente en Cloud Run.
examples/ Directorio que contiene ejemplos de plantillas de componentes.
gemini_enterprise_composite_catalog.json Catálogo de componentes que define los componentes estándar de Material y los componentes personalizados de Gemini Enterprise.
main.py Es el punto de entrada principal de la aplicación (app de FastAPI).
prompt_builder.py Es una herramienta auxiliar para construir instrucciones para el modelo.
pyproject.toml Configuración y dependencias del proyecto.
examples/0.9/material_table_orders.json Plantilla de IU de muestra que contiene el diseño y los datos simulados para la demostración de pedidos recientes.
tools.py Define las herramientas (funciones) que puede usar el agente.

Antes de comenzar

Antes de comenzar, asegúrate de tener lo siguiente:

  • El rol de administrador de Discovery Engine

  • Una app de Gemini Enterprise existente. Para crear una app, consulta Crea una app.

  • Clona el repositorio y navega al directorio de muestra v0_9:

    git clone https://github.com/a2ui-project/a2ui.git
cd a2ui/samples/community/agent/adk/gemini_enterprise/v0_9

Habilita las APIs

Habilita las siguientes APIs para tu proyecto:

Console

Habilita las siguientes APIs:

  • La API de Vertex AI
  • API de Cloud Build
  • API de Artifact Registry
  • API de Cloud Run
  • API de Cloud Logging
  • API de Discovery Engine
  • API de Cloud Storage
  • API de Identity and Access Management (IAM)

Habilita las APIs

REST

Puedes habilitar estas APIs desde la Google Cloud consola de o con el siguiente comando de gcloud CLI:

gcloud services enable aiplatform.googleapis.com cloudbuild.googleapis.com artifactregistry.googleapis.com run.googleapis.com logging.googleapis.com discoveryengine.googleapis.com storage.googleapis.com iam.googleapis.com

Otorga permisos

Otorga permiso al rol Invocador de Cloud Run (roles/run.invoker).

gcloud projects add-iam-policy-binding PROJECT_ID \
   --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-discoveryengine.iam.gserviceaccount.com" \
   --role="roles/run.invoker"

Reemplaza lo siguiente:

  • PROJECT_ID : el ID de tu proyecto.
  • PROJECT_NUMBER: Tu Google Cloud número de proyecto.

Implementa el agente

La secuencia de comandos deploy.sh automatiza el proceso de implementación. Para implementar tu agente, ejecuta la secuencia de comandos desde el directorio del proyecto con tu Google Cloud ID y un nombre para tu nuevo servicio. También puedes especificar el modelo de Gemini que deseas usar.

La secuencia de comandos realiza las siguientes acciones:

  1. Compila una imagen de contenedor a partir de tu código fuente.
  2. Envía la imagen a Artifact Registry.
  3. Implementa la imagen en Cloud Run.
  4. Establece variables de entorno, incluidas la MODEL y la AGENT_URL pública del servicio.
chmod +x deploy.sh
./deploy.sh PROJECT_ID a2ui-demo-agent MODEL_NAME

Reemplaza lo siguiente:

  • PROJECT_ID: el ID de tu proyecto.
  • MODEL_NAME: Opcional. Este es el tercer argumento de la secuencia de comandos. Los valores admitidos son gemini-2.5-pro y gemini-2.5-flash. Si no se proporciona, la secuencia de comandos usa gemini-2.5-flash de forma predeterminada.

Una vez que se complete la secuencia de comandos, imprimirá la URL de servicio de tu agente implementado. Necesitarás esta URL de servicio en el siguiente paso.

Registra el agente en Gemini Enterprise

Ahora que tu agente está implementado, debes registrarlo en Gemini Enterprise para que se pueda detectar.

Ejecuta el siguiente comando curl y reemplaza los marcadores de posición por tus propios valores:

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_NUMBER/locations/LOCATION/collections/default_collection/engines/ENGINE_ID/assistants/default_assistant/agents -d '{
  "name": "a2ui-demo-agent",
  "displayName": "A2UI v0.9 Demo Agent",
  "description": "A demo agent that showcases A2UI v0.9 UI templates.",
  "a2aAgentDefinition": {
      "jsonAgentCard": "{\"protocolVersion\": \"0.3.0\", \"name\": \"A2UI v0.9 Demo\", \"description\": \"A demo agent that showcases A2UI v0.9 UIs built from the Material component catalog and Gemini Enterprise custom components (Canvas, Iframe). Ask it what can you do? to see the available demos.\", \"url\": \"AGENT_URL\", \"version\": \"1.0.0\", \"capabilities\": {\"streaming\": true, \"preferredTransport\": \"JSONRPC\", \"extensions\": [{\"uri\": \"https://a2ui.org/a2a-extension/a2ui/v0.9\", \"description\": \"Ability to render A2UI v0.9\", \"required\": false, \"params\": {\"supportedCatalogIds\": [\"https://www.gstatic.com/vertexaisearch/a2ui/v0_9/gemini_enterprise_composite_catalog.json\"]}}]}, \"skills\": [{\"id\": \"a2ui_demo\", \"name\": \"A2UI v0.9 Component Demo\", \"description\": \"Demonstrates A2UI v0.9 UIs built from the Material catalog and Gemini Enterprise custom components: cards, forms & inputs, tabs, tables, progress indicators, dialogs & menus, the Canvas side panel, and the Iframe (IFrameSrcdoc / IFrameUrl) components.\"}], \"defaultInputModes\": [\"text/plain\"], \"defaultOutputModes\": [\"text/plain\"]}"
    }
}'

Reemplaza lo siguiente:

  • PROJECT_NUMBER: Tu Google Cloud número de proyecto.
  • LOCATION: Es la multirregión de tu almacén de datos: global, us o eu.
  • ENGINE_ID: Es el ID de la app con la que deseas registrar el agente.
  • AGENT_URL: Es la URL de servicio de tu agente implementado.

Anula el registro del agente (opcional)

Si deseas anular el registro del agente, ejecuta el siguiente comando curl:

curl -X DELETE -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_NUMBER/locations/LOCATION/collections/default_collection/engines/ENGINE_ID/assistants/default_assistant/agents/AGENT_ID

Reemplaza lo siguiente:

  • PROJECT_NUMBER: Tu Google Cloud número de proyecto.
  • LOCATION: Es la multirregión de tu almacén de datos: global, us o eu.
  • ENGINE_ID: Es el ID de la app con la que está registrado el agente.
  • AGENT_ID: Es el ID del agente que deseas borrar.

Usa el agente en la app web de Gemini Enterprise

Después de crear y registrar un agente, puedes comenzar a usarlo e interactuar con él en la app web de Gemini Enterprise.

Obtén la URL de la app web

Para usar el agente, primero debes obtener la URL de la app web. Un administrador de Gemini Enterprise puede obtener y compartir la URL de la app web siguiendo estos pasos:

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

    Gemini Enterprise

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

  3. Haz clic en Integrations.

  4. Copia el vínculo a tu app web y compártelo con los usuarios de la organización.

Usa el agente

Para usar el agente e interactuar con él, haz lo siguiente:

  1. Abre la URL de la app web en una nueva pestaña del navegador.
  2. En el menú de navegación de la app web, haz clic en Agentes.
  3. Ve a la sección De tu organización y haz clic en el agente que creaste.
  4. Se abrirá la interfaz conversacional del agente. Comienza a hacer preguntas e interactuar con el agente.

Por ejemplo, puedes usar una instrucción como Show me the recent orders table para obtener información sobre los pedidos recientes que forman parte de los datos de muestra. El agente recupera la información del pedido de material_table_orders.json y renderiza la lista en el chat con componentes de IU personalizados, como se muestra en el siguiente ejemplo:

Ejemplo de tabla de pedidos recientes