Aloja un agente de A2UI con Cloud Run

En este instructivo, se explica cómo implementar un agente de Agent-to-Agent (A2A), compilado 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/Directorio Descripción
examples/0.8/ 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 ficticios)
deploy.sh Secuencia de comandos para compilar y, luego, implementar el agente en Cloud Run
main.py El punto de entrada principal de la aplicación (app de FastAPI)
prompt_builder.py Ayuda a construir mensajes 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 Crea una app.

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

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

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 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 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 MODEL y la AGENT_URL pública 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, 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": "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: 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.

Usa 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 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 y 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 Agents.
  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 muestre 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