Administrar los agentes

Vista previa

Este producto o esta función se encuentra sujeto a las "Condiciones de la oferta de la fase previa a la DG" en la sección Condiciones del servicio generales de las Condiciones específicas del servicio. Los productos y las funciones de la fase previa a la DG están disponibles “tal como están” y pueden estar sujetos a asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

La administración eficaz de tu flota de agentes requiere mantener la precisión del registro mediante la visualización y la actualización de los detalles del servicio a medida que evolucionan tus cargas de trabajo, la anulación de metadatos o la eliminación de agentes que ya no están en uso.

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 tus agentes estén registrados en Agent Registry. También necesitas tu ID del proyecto para realizar estas tareas.

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

Roles obligatorios

Para obtener los permisos que necesitas para administrar 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 agentes, puedes descubrirlos en tu entorno y ver sus configuraciones detalladas, como sus extremos, habilidades y metadatos asociados.

Enumera y visualiza 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 Google Cloud console, ve a Agent Registry:

   Ve a Agent Registry

2. En el selector de proyectos, selecciona el Google Cloud proyecto 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, el identificador, tipo, la descripción, la versión, el entorno 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 alpha agent-registry agents list \
  --project=PROJECT_ID \
  --location=REGION

Reemplaza lo siguiente:

• PROJECT_ID: El ID del proyecto
• REGION: La región del registro

Filtra los 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 Google Cloud console, ve a Agent Registry:

   Ve a Agent Registry

2. En el selector de proyectos, selecciona el Google Cloud proyecto 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, el identificador, 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 seleccionadas.

gcloud

Filtra tu lista de agentes para mostrar solo los recursos que coinciden con metadatos específicos, usando la marca --filter:

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

Reemplaza FILTER_EXPRESSION por la expresión de filtro de 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'.

Visualiza los detalles de un agente

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

Console

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

   Ve a Agent Registry

2. En el selector de proyectos, selecciona el Google Cloud proyecto 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, el identificador, 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 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 específicos del agente.

   La disponibilidad de las funciones depende de tu entorno de ejecución. Las pestañas como Sesiones, Playground, Memorias y Evaluación son capacidades específicas que se muestran para los agentes compilados en entornos de ejecución administrados, como Vertex AI Agent Engine:

   • Descripción general: Detalles principales del agente, incluidos el nombre, el identificador, la ubicación, la descripción y el entorno de ejecución del agente. 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 el gasto de 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 para ayudarte a administrar los costos y la experiencia del usuario. Para obtener más información, consulta la descripción general de Observabilidad.
   • Seguimientos: La ruta de acceso exacta de un paso de conversación por 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 seguimientos de agentes.
   • Seguridad: Hallazgos de Model Armor y Security Command Center, incluidas las infracciones de la política 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 hallazgos de seguridad.
   • Topología: Un mapa visual de las relaciones y los flujos de tráfico entre un agente, su puerta de enlace de agente asignada y los servidores de MCP con los que interactúa. Para obtener más información sobre la puerta de enlace de agente, consulta la descripción general de la puerta de enlace de agente. Para obtener más información sobre la topología, consulta Visualiza gráficos para un agente registrado.
   • Identidad: El principal del agente que se usa para la aplicación de políticas. Usas 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.
   • Playground: Una interfaz de chat directo para probar el comportamiento del agente.
   • Memorias: Funciones de personalización a largo plazo que generan o recuperan detalles de conversaciones anteriores con el agente para preservar el contexto en todas las interacciones.
   • Evaluación: Detalles de todas las tareas de evaluación del agente. 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, usa el comando agents describe:

gcloud alpha 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.

Actualiza los metadatos y los extremos del agente

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

Para la API de Agent Registry, los recursos Agent se usan para el descubrimiento. Por lo tanto, debes actualizar el recurso Service registrado directamente.

Usa Google Cloud 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 alpha 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: El ID del proyecto
  • REGION: La región del registro

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

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

  Reemplaza lo siguiente:

  • ENDPOINT_URL: La nueva URL del extremo del servicio del agente, por ejemplo, https://new-api.example.com/agent.
  • PROTOCOL: La vinculación de 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 tarjeta de agente nueva:

  gcloud alpha agent-registry services update AGENT_NAME \
    --project=PROJECT_ID \
    --location=REGION \
    --agent-spec-content=@AGENT_SPEC
  

  Nota: El archivo de especificación del agente que subas no debe superar los 10 KB.

  Reemplaza AGENT_SPEC por el nombre de la nueva especificación del agente, por ejemplo, new-agent-card.json.

Quita un agente

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

Para quitar un agente registrado de forma manual 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 descubrir:

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

Reemplaza lo siguiente:

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

¿Qué sigue?

• Aprende a visualizar las relaciones de los agentes con un gráfico de topología.
• Aprende a buscar agentes y herramientas con consultas en lenguaje natural.