Administrar los agentes

Para administrar de manera eficaz tu flota de agentes, debes mantener el registro actualizado. Para ello, visualiza y actualiza los detalles de los agentes a medida que evoluciona tu ecosistema de IA, anula los metadatos o quita los agentes que ya no se usan.

En este documento, se detalla cómo ver y modificar los detalles y la configuración de tu agente registrado.

Antes de comenzar

Antes de administrar agentes, asegúrate de que estén registrados en Agent Registry. También necesitarás el ID de tu proyecto para realizar estas tareas.

Para usar los comandos de Google Cloud CLI en este documento, asegúrate de configurar tu entorno de gcloud CLI.

Roles obligatorios

Para obtener los permisos que necesitas para administrar los agentes registrados en Agent Registry, pídele a tu administrador que te otorgue el rol de IAM Editor de la API de Agent Registry (roles/agentregistry.editor) en el proyecto. 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 y metadatos asociados.

Cómo ver y enumerar todos los agentes

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

Console

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

    Ir a Agent Registry

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

  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 tiempo de ejecución y la ubicación del agente.

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

gcloud

Para enumerar todos los agentes en una ubicación específica, usa el comando agents list:

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

Reemplaza lo siguiente:

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

Cómo filtrar agentes registrados

Si tienes varios agentes o si deseas 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 a Agent Registry

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

  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 tiempo de ejecución y la ubicación del agente.

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

    • Para filtrar por ubicación, haz clic en el menú Ubicación, selecciona las ubicaciones por las que deseas filtrar y haz clic en Aplicar.
    • Para filtrar por tiempo de ejecución, haz clic en el menú Tiempo de ejecución, selecciona los tiempos de ejecución por los 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, usando la marca --filter:

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

Reemplaza FILTER_EXPRESSION por 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 único a nivel global (URN), 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 del agente por el que se filtrará, por ejemplo, Support Agent.

Cómo ver los detalles de un agente

Ver detalles de un agente específico, incluidos sus protocolos, habilidades e identidad:

Console

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

    Ir a Agent Registry

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

  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 tiempo de ejecución y la ubicación del agente.

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

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

  5. Haz clic en la pestaña correspondiente para ver los detalles específicos del agente.

    La disponibilidad de las funciones depende del tiempo de ejecución. Las pestañas como Sessions, Playground, Memories y Evaluation son capacidades específicas que se muestran para los agentes creados en tiempos de ejecución administrados, como Agent Runtime en Gemini Enterprise Agent Platform:

    • Resumen: Detalles principales del agente, incluidos su nombre, identificador, ubicación, descripción y tiempo de ejecución En la descripción general, también se muestran las habilidades y el URI del recurso, que necesitas para compilar consultas en el gráfico de topología.
    • Observabilidad: Estadísticas centradas en la aplicación, como la latencia, el tráfico, los errores y la inversión en tokens Esta pestaña se integra con las herramientas de Google Cloud Observability para mostrar métricas de rendimiento en tiempo real y la utilización a nivel del sistema, lo que te ayuda a administrar los costos y la experiencia del usuario. Para obtener más información, consulta la Descripción general de la observabilidad.
    • Registros: La ruta exacta de un paso de 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 Cómo ver los seguimientos del agente.
    • 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 Cómo ver los resultados de seguridad.
    • Topología: Es un mapa visual de las relaciones y los flujos de tráfico entre un agente, su puerta de enlace de agentes 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 Cómo ver los gráficos de un agente registrado.
    • Identidad: Es el principal del agente que se usa para aplicar la política. Por ejemplo, usas esta identidad para configurar vinculaciones del proveedor 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
    • Playground: Es una interfaz de chat directa para probar el comportamiento del agente.
    • Recuerdos: Son funciones de personalización a largo plazo que generan o recuerdan detalles de conversaciones anteriores con el agente para preservar el contexto en las interacciones.
    • Evaluación: Detalles de todas las tareas de evaluación del agente. Esta pestaña te permite crear nuevas tareas de evaluación, subir métricas y evaluar el rendimiento cognitivo del agente y la confiabilidad del modelo en comparación con el tráfico real o las simulaciones sintéticas.

gcloud

Para ver los metadatos detallados de un agente específico, usa el comando agents describe:

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

Reemplaza AGENT_NAME por el nombre de tu agente, por ejemplo, my-custom-agent.

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 de tiempo 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 caso de la API de Agent Registry, los recursos de Agent se usan para el descubrimiento. Por lo tanto, debes actualizar el recurso Service registrado directamente.

Console

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

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

    Ir a Agent Registry

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

  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 tiempo 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 nuevo nombre o descripción.

  7. Haz clic en Guardar.

gcloud

Usa gcloud CLI 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: Es el nombre de tu agente, por ejemplo, my-support-agent.
    • PROJECT_ID: El ID del proyecto
    • REGION: Es la región del registro.

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

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

    Reemplaza lo siguiente:

    • 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

    Reemplaza AGENT_SPEC por el nombre del nuevo archivo de especificación del agente, por ejemplo, new-agent-card.json. El tamaño máximo del archivo de especificaciones 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 asignarle a tu agente, por ejemplo, my-support-agent.
  • ENDPOINT_URL: Es la URL del extremo de API del agente, por ejemplo, https://api.remote-service.com/v1/agents/1234.
  • PROTOCOL: Es la vinculación del protocolo para el extremo. Los valores válidos son HTTP_JSON, GRPC o JSONRPC.

Cómo quitar un agente

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

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

Console

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

    Ir a Agent Registry

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

  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 tiempo de ejecución y la ubicación del agente.

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

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

  6. En el diálogo de confirmación, escribe BORRAR para confirmar la acción.

  7. Haz clic en Borrar.

gcloud

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: 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?