Aloja un agente de A2UI con Cloud Run

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

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 o directorio Descripción
examples/0.8/ Es el directorio que contiene datos o configuraciones de ejemplo.
__init__.py Marca el directorio como un paquete de Python.
agent.py Define el agente, sus habilidades y su comportamiento.
agent_executor.py Administra el flujo de ejecución y las interacciones de herramientas.
contact_data.json Datos de muestra que usa el agente (por ejemplo, contactos simulados).
deploy.sh Es una secuencia de comandos para compilar e implementar el agente en Cloud Run.
main.py Es el punto de entrada principal de la aplicación (app de FastAPI).
prompt_builder.py Es un asistente para crear instrucciones para el modelo.
pyproject.toml Configuración y dependencias del proyecto
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 Cómo crear una app.

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

    git clone https://github.com/google/A2UI.git
cd A2UI/samples/agent/adk/gemini_enterprise/cloud_run

Habilita las APIs

Habilita las siguientes APIs para tu proyecto:

Console

Habilita las siguientes APIs:

  • API de Agent Platform
  • 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 administración de identidades y accesos (IAM)

Habilita las API

REST

Puedes habilitar estas APIs desde la consola de Google Cloud 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

Otorgar permisos

Otorga permiso al rol de Cloud Run Invoker (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 : Es el ID de tu proyecto.
  • PROJECT_NUMBER: Es el número de tu proyecto de Google Cloud .

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 ID de Google Cloud y un nombre para tu nuevo servicio. También puedes especificar de forma opcional el modelo de Gemini que se 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 MODEL y AGENT_URL públicas del servicio.
chmod +x deploy.sh
./deploy.sh YOUR_PROJECT_ID contacts-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, el script usa gemini-2.5-flash de forma predeterminada.

Una vez que se complete la secuencia de comandos, se imprimirá la URL de servicio del 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": "contacts-agent",
"displayName": "Contacts Agent",
"description": "This is a test agent which lists the contacts.",
"a2aAgentDefinition": {
  "jsonAgentCard": "{\"protocolVersion\": \"0.3.0\", \"name\": \"contacts-agent\", \"description\": \"This is a test agent which lists the contacts.\", \"url\": \"AGENT_URL\", \"version\": \"1.0.0\", \"capabilities\": {\"streaming\": true, \"extensions\": [{\"uri\": \"https://a2ui.org/a2a-extension/a2ui/v0.8\", \"description\": \"Ability to render A2UI\", \"required\": false, \"params\": {\"supportedCatalogIds\": [\"https://a2ui.org/specification/v0_8/standard_catalog_definition.json\"]}}]}, \"skills\": [], \"defaultInputModes\": [\"text/plain\"], \"defaultOutputModes\": [\"text/plain\"]}"
}
}'

Reemplaza lo siguiente:

  • PROJECT_NUMBER: Es el número de tu proyecto de Google Cloud .
  • 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 del servicio de tu agente implementado.

Cómo usar el agente en la app web de Gemini Enterprise

Después de crear y registrar un agente, puedes comenzar a usarlo y a 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 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 registraste el agente.

  3. Haz clic en Integrations.

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

Cómo usar el agente

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

  1. Abre la URL de la app web en una pestaña nueva 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 y a interactuar con el agente.

Por ejemplo, puedes pedirle al agente que enumere todos los contactos. El agente usa la herramienta list_contacts para recuperar los contactos de contact_data.json y renderiza la lista en el chat con elementos de IU personalizados, como se muestra en el siguiente ejemplo:

Ejemplo de Contacts Agent