Administrar los agentes

Agent Registry te permite inspeccionar, actualizar y quitar agentes registrados para que tu registro refleje con precisión las capacidades activas en tu ecosistema de IA. Puedes enumerar y ver todos los agentes registrados, actualizar los metadatos o el extremo de los agentes registrados de forma manual y quitar los agentes que ya no se usan.

Antes de comenzar

  1. Configura el Registro de agentes.

  2. Obtén el ID del proyecto para el proyecto de administración en el que está habilitado el Registro de agentes.

  3. Registra tus agentes en Agent Registry.

  4. Para usar los comandos de Google Cloud CLI en este documento, configura tu entorno de gcloud CLI.

Roles obligatorios

Para obtener los permisos que necesitas para administrar agentes registrados en el Registro de agentes, pídele a tu administrador que te otorgue el rol de IAM de editor de la API del Registro de agentes (roles/agentregistry.editor) en el proyecto de administración en el que está habilitado el Registro de agentes. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Descubre los agentes disponibles

Después de registrar los agentes, puedes descubrirlos en tu entorno y ver sus configuraciones detalladas, como sus extremos, habilidades de A2A y metadatos asociados.

Enumera y visualiza todos los agentes

Puedes enumerar todos los agentes registrados en tu entorno y ver sus configuraciones detalladas, como sus extremos, habilidades de A2A y metadatos asociados:

Console

  1. En la consola de Google Cloud , ve a Agent Registry:

    Ir al registro de agentes

  2. En el selector de proyectos, elige el proyecto de Google Cloud en el que configuraste Agent Registry.

  3. Selecciona la pestaña Agentes.

    En la página, se muestra una lista de todos los agentes registrados. La lista incluye el nombre del agente, el identificador, el tipo, la descripción, la versión, el entorno de ejecución y la ubicación.

  4. Para ver los detalles completos de un agente, haz clic en su nombre.

gcloud

Para enumerar todos los agentes en una ubicación específica, ejecuta el comando gcloud agent-registry agents list:

gcloud agent-registry agents list \
    --project=PROJECT_ID \
    --location=REGION

Reemplaza lo siguiente:

  • PROJECT_ID: Es el ID del proyecto.
  • REGION: Es la región del registro.

Filtra los agentes registrados

Si tienes varios agentes o si quieres confirmar el registro de un agente específico, puedes filtrar la lista por los metadatos del agente:

Console

  1. En la consola de Google Cloud , ve a Agent Registry:

    Ir al registro de agentes

  2. En el selector de proyectos, selecciona el proyecto de Google Cloud en el que configuraste el Registro de agentes.

  3. Selecciona la pestaña Agentes.

    En la página, se muestra una lista de todos los agentes registrados. La lista incluye el nombre, el identificador, el tipo, la descripción, la versión, el entorno de ejecución y la ubicación del agente.

  4. Filtra la lista por la ubicación del agente o su recurso de entorno de ejecución:

    • Para filtrar por ubicación, haz clic en el menú Ubicación, selecciona las ubicaciones que deseas filtrar y haz clic en Aplicar.
    • Para filtrar por entorno de ejecución, haz clic en el menú Entorno de ejecución, selecciona los entornos de ejecución que deseas filtrar y haz clic en Aplicar.

    En la página, se muestra una lista filtrada de los agentes registrados para las condiciones que seleccionaste.

gcloud

Filtra tu lista de agentes para que solo se muestren los recursos que coincidan con metadatos específicos. Para ello, pasa la marca --filter al comando gcloud agent-registry agents list:

gcloud agent-registry agents list \
    --project=PROJECT_ID \
    --location=REGION \
    --filter="FILTER_EXPRESSION"

Reemplaza lo siguiente:

  • PROJECT_ID: Es el ID del proyecto.
  • REGION: Es la región del registro.
  • FILTER_EXPRESSION: Es la expresión de filtro para los agentes que deseas filtrar. Por ejemplo, puedes usar los siguientes filtros:
    • Para filtrar por nombre visible, usa displayName='DISPLAY_NAME'.
    • Para buscar por el identificador de agente (URN) único a nivel global, usa agentId='urn:agent:AGENT_URN'.

Terraform

Para recuperar un agente registrado específico filtrando sus metadatos, configura la fuente de datos google_agent_registry_agent con el argumento filter:

data "google_agent_registry_agent" "filtered_agent" {
  location = "REGION"
  filter   = "displayName=\"DISPLAY_NAME\""
}

Reemplaza lo siguiente:

  • REGION: Es la región del registro.
  • DISPLAY_NAME: Es el nombre legible por humanos del agente por el que se filtrará, por ejemplo, Support Agent.

Consulta los detalles de un agente

Consulta los detalles de un agente específico, incluidos sus protocolos, habilidades de A2A y su identidad:

Console

  1. En la consola de Google Cloud , ve a Agent Registry:

    Ir al registro de agentes

  2. En el selector de proyectos, selecciona el proyecto de Google Cloud en el que configuraste el Registro de agentes.

  3. Selecciona la pestaña Agentes.

    En la página, se muestra una lista de todos los agentes registrados. La lista incluye el nombre del agente, el identificador, el tipo, la descripción, la versión, el entorno de ejecución y la ubicación.

  4. Haz clic en el nombre del agente que deseas ver.

    La página de detalles incluye pestañas para los detalles del agente.

  5. Haz clic en la pestaña correspondiente para ver los detalles de un agente específico.

    La disponibilidad de las funciones depende del entorno de ejecución. Las pestañas como Sesiones, Playground, Memorias y Evaluación son funciones específicas que aparecen para los agentes creados en entornos de ejecución administrados, como Agent Runtime en Gemini Enterprise Agent Platform:

    • Descripción general: Son los detalles principales del agente, incluidos su nombre, identificador, ubicación, descripción y entorno de ejecución. En la descripción general, también se muestran las habilidades de A2A y la referencia del entorno de ejecución, que necesitas para compilar consultas en el grafo de topología.
    • Observabilidad: Estadísticas centradas en la aplicación, como la latencia, el tráfico, los errores y el gasto de tokens. Esta pestaña se integra en las herramientas de Google Cloud Observability para mostrar métricas de rendimiento en tiempo real y el uso a nivel del sistema para ayudarte a administrar los costos y la experiencia del usuario. Para obtener más información, consulta la descripción general de la observabilidad.
    • Seguimientos: Es la ruta exacta de una conversación paso a paso, incluido el formato detallado de los mensajes de entrada y del asistente para depurar bucles de razonamiento complejos de varios agentes o errores de invocación de herramientas en tiempo real. Para obtener más información, consulta Visualiza los seguimientos de agentes.
    • Seguridad: Hallazgos de Model Armor y Security Command Center, incluidos los incumplimientos de políticas de contenido, los riesgos de filtración de datos y las evaluaciones de cumplimiento. Para obtener más información sobre la seguridad, consulta Visualiza los hallazgos de seguridad.
    • Topología: Es un mapa visual de las relaciones y los flujos de tráfico entre un agente, su Agent Gateway asignada y los servidores de MCP con los que interactúa. Para obtener más información sobre Agent Gateway, consulta la descripción general de Agent Gateway. Para obtener más información sobre la topología, consulta Visualiza gráficos de un agente registrado.
    • Identidad: Es el principal del agente que se usa para aplicar la política. Usa esta identidad, por ejemplo, para configurar vinculaciones de proveedores de autenticación para la autenticación en herramientas y recursos.
    • Sesiones: historial de conversaciones persistente y seguimiento de las interacciones activas con el agente.
    • Zona de pruebas: Es una interfaz de chat directa para probar el comportamiento del agente.
    • Memorias: Son funciones de personalización a largo plazo que generan o recuerdan detalles de conversaciones anteriores con el agente para preservar el contexto entre las interacciones.
    • Evaluación: detalles de todas las tareas de evaluación de agentes. Esta pestaña te permite crear tareas de evaluación nuevas, subir métricas y evaluar el rendimiento cognitivo del agente y la confiabilidad del modelo en comparación con el tráfico en vivo o las simulaciones sintéticas.

gcloud

Para ver los metadatos detallados de un agente específico, ejecuta el comando gcloud agent-registry agents describe:

gcloud agent-registry agents describe AGENT_NAME \
    --project=PROJECT_ID \
    --location=REGION

Reemplaza lo siguiente:

  • AGENT_NAME: Es el nombre de tu agente, por ejemplo, my-custom-agent.
  • PROJECT_ID: Es el ID del proyecto.
  • REGION: Es la región del registro.

Terraform

Para recuperar detalles sobre un agente registrado específico con su ID, configura la fuente de datos google_agent_registry_agent:

data "google_agent_registry_agent" "my_agent" {
  location = "REGION"
  agent_id = "AGENT_ID"
}

output "agent_create_time" {
  description = "The timestamp when the agent was registered."
  value       = data.google_agent_registry_agent.my_agent.create_time
}

output "agent_update_time" {
  description = "The timestamp when the agent was last updated."
  value       = data.google_agent_registry_agent.my_agent.update_time
}

Reemplaza lo siguiente:

  • REGION: Es la región del registro.
  • AGENT_ID: Es el identificador único de tu agente, por ejemplo, my-custom-agent.

Actualiza los metadatos y los extremos del agente

Si cambia la URL del entorno de ejecución de tu agente o quieres anular su nombre visible, descripción o especificación, puedes actualizar los metadatos del agente.

En el Registro de agentes, los recursos Agent son recursos de descubrimiento de solo lectura. Para actualizar un agente registrado de forma manual, debes actualizar su recurso Service escribible directamente. En el caso de los agentes registrados automáticamente, actualiza el agente en su entorno de ejecución subyacente para que el Registro de agentes sincronice los cambios.

Console

Actualiza los detalles disponibles del agente desde la consola de Google Cloud :

  1. En la consola de Google Cloud , ve a Agent Registry:

    Ir al registro de agentes

  2. En el selector de proyectos, selecciona el proyecto de Google Cloud en el que configuraste el Registro de agentes.

  3. Selecciona la pestaña Agentes.

    En la página, se muestra una lista de todos los agentes registrados. La lista incluye el nombre, el identificador, el tipo, la descripción, la versión, el entorno de ejecución y la ubicación del agente.

  4. Haz clic en el nombre del agente que deseas actualizar.

  5. En la pestaña Descripción general del agente, haz clic en Editar.

  6. En el panel Editar servicio, ingresa la información actualizada de tu agente, como su nombre o descripción nuevos.

  7. Haz clic en Guardar.

gcloud

Ejecuta el comando gcloud agent-registry services update con marcas específicas para modificar los parámetros del agente:

  • Actualiza el nombre visible y la descripción: Usa las marcas --display-name y --description, por ejemplo:

    gcloud agent-registry services update AGENT_NAME \
    --project=PROJECT_ID \
    --location=REGION \
    --display-name="New display name" \
    --description="Updated description of the agent's purpose."

    Reemplaza lo siguiente:

    • AGENT_NAME: el nombre de tu agente, por ejemplo, my-support-agent.
    • PROJECT_ID: Es el ID del proyecto.
    • REGION: Es la región del registro.

  • Actualiza la URL del extremo: usa la marca --interfaces para especificar el extremo nuevo, por ejemplo:

    gcloud agent-registry services update AGENT_NAME \
    --project=PROJECT_ID \
    --location=REGION \
    --interfaces=url=ENDPOINT_URL,protocolBinding=PROTOCOL

    Reemplaza lo siguiente:

    • AGENT_NAME: el nombre de tu agente, por ejemplo, my-support-agent.
    • PROJECT_ID: Es el ID del proyecto.
    • REGION: Es la región del registro.
    • ENDPOINT_URL: Es la URL del nuevo extremo del agente, por ejemplo, https://new-api.example.com/agent.
    • PROTOCOL: Es la vinculación del protocolo para el extremo. Los valores válidos son http-json, grpc o jsonrpc.

  • Actualiza la especificación del agente: usa la marca --agent-spec-content, por ejemplo, si tienes una nueva tarjeta de agente:

    gcloud agent-registry services update AGENT_NAME \
    --project=PROJECT_ID \
    --location=REGION \
    --agent-spec-content=AGENT_SPEC_FILE

    Reemplaza lo siguiente:

    • AGENT_NAME: el nombre de tu agente, por ejemplo, my-support-agent.
    • PROJECT_ID: Es el ID del proyecto.
    • REGION: Es la región del registro.
    • AGENT_SPEC_FILE: Es la ruta de acceso al archivo de especificación del agente nuevo, por ejemplo, new-agent-card.json. El tamaño máximo del archivo de especificación es de 10 KB.

Terraform

Para actualizar los metadatos, la URL del extremo o la especificación de tu agente registrado, modifica los parámetros del recurso google_agent_registry_service existente en tu configuración y, luego, ejecuta terraform apply:

resource "google_agent_registry_service" "rest_agent" {
  location     = "REGION"
  service_id   = "AGENT_NAME"
  display_name = "New Display Name"
  description  = "Updated description of the agent's purpose."

  agent_spec {
    type = "NO_SPEC"
  }

  interfaces {
    url              = "ENDPOINT_URL"
    protocol_binding = "PROTOCOL"
  }
}

Reemplaza lo siguiente:

  • REGION: Es la región del registro.
  • AGENT_NAME: Es el nombre único que deseas darle a tu agente, por ejemplo, my-support-agent.
  • ENDPOINT_URL: Es la URL del extremo de API del agente, por ejemplo, https://api.example.com/v1/agents/1234.
  • PROTOCOL: Es la vinculación del protocolo para el extremo. Los valores válidos son HTTP_JSON, GRPC o JSONRPC.

Quita un agente

Para borrar los agentes que se registraron automáticamente en Agent Registry, debes borrar el agente subyacente en su entorno de ejecución de Google Cloud específico. Luego, el agente se quita automáticamente del registro.

Para quitar un agente registrado de forma manual del registro, debes borrar su recurso Service. Esta acción quita el agente de los resultados de la búsqueda y hace que otras herramientas no puedan descubrirlo:

Console

  1. En la consola de Google Cloud , ve a Agent Registry:

    Ir al registro de agentes

  2. En el selector de proyectos, selecciona el proyecto de Google Cloud en el que configuraste el Registro de agentes.

  3. Selecciona la pestaña Agentes.

    En la página, se muestra una lista de todos los agentes registrados. La lista incluye el nombre del agente, el identificador, el tipo, la descripción, la versión, el entorno de ejecución y la ubicación.

  4. Haz clic en el nombre del agente que quieres quitar.

  5. En la pestaña Descripción general del agente, haz clic en Borrar.

  6. En el cuadro de diálogo de confirmación, ingresa DELETE para confirmar la acción.

  7. Haz clic en Borrar.

gcloud

Ejecuta el comando gcloud agent-registry services delete:

gcloud agent-registry services delete AGENT_NAME \
    --project=PROJECT_ID \
    --location=REGION

Reemplaza lo siguiente:

  • AGENT_NAME: Es el nombre del agente que deseas quitar, por ejemplo, my-support-agent.
  • PROJECT_ID: Es el ID del proyecto.
  • REGION: Es la región del registro.

Terraform

Quita el recurso google_agent_registry_service que representa al agente de tu configuración de Terraform y, luego, ejecuta terraform apply.

¿Qué sigue?