Buscar agentes, herramientas y habilidades

Agent Registry te permite buscar entre tus agentes registrados, habilidades de Agent2Agent (A2A), habilidades independientes y servidores del Protocolo de contexto del modelo (MCP) por palabra clave, prefijo o lenguaje natural en la consola de Google Cloud , Google Cloud CLI o la API de Agent Registry. Las búsquedas por palabras clave y prefijos te ayudan a encontrar recursos rápidamente por nombre, identificador o metadatos. La búsqueda semántica encuentra capacidades relacionadas conceptualmente en las instrucciones y descripciones de lenguaje natural según la intención.

Las búsquedas evalúan las descripciones de las capacidades de los agentes, los servidores de MCP y las habilidades, los esquemas de herramientas y las instrucciones de las habilidades. No puedes usar consultas de búsqueda para descubrir endpoints. Si quieres obtener instrucciones para enumerar y filtrar endpoints por metadatos, consulta Descubre endpoints y filtra componentes por metadatos.

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. Registrar un agente, un servidor de MCP o una habilidad 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 buscar agentes, herramientas y habilidades en el Registro de agentes, pídele a tu administrador que te otorgue el rol de IAM de Visualizador de la API de Agent Registry (roles/agentregistry.viewer) 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.

Busca agentes y herramientas

Para descubrir capacidades dentro de tu registro, puedes buscar agentes y servidores de MCP registrados en la consola de Google Cloud , gcloud CLI o la API de REST.

Cuando buscas agentes o servidores de MCP, puedes consultar por nombre visible, descripción o palabras clave de capacidad:

• Agentes: Las búsquedas verifican el nombre visible, la descripción, el identificador de agente y los nombres, las descripciones y las etiquetas de las habilidades de A2A intercaladas declaradas en su tarjeta de agente para encontrar una coincidencia.
• Servidores de MCP: Las búsquedas verifican el nombre visible, la descripción, el identificador del servidor de MCP y los nombres y las descripciones de sus herramientas para encontrar una coincidencia.

Buscar por palabras clave

Puedes realizar una búsqueda por palabra clave para encontrar recursos que contengan términos específicos en sus capacidades, como la habilidad de A2A de un agente o la herramienta de un servidor de MCP. Para comprender cómo se estructuran estas capacidades en el registro, consulta Esquemas JSON. Para obtener una lista completa de los campos en los que se puede buscar, consulta la referencia de la API.

Las consultas de palabras clave aceptan cadenas de texto libre y admiten los operadores lógicos AND, OR y NOT:

Console

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

   Ir al registro de agentes

2. En el selector de proyectos, selecciona tu proyecto de Google Cloud .

3. En la barra Buscar en tu registro que se encuentra en la parte superior de la página, ingresa una consulta de palabra clave de al menos tres caracteres, como flight o database, o un filtro de campo, como Name:booking, y, luego, presiona Enter.

   En la tabla Resultados de la búsqueda, se muestran los agentes, los servidores de MCP y las habilidades independientes que coinciden en las ubicaciones seleccionadas.

gcloud

Proporciona la marca --search-string al comando gcloud agent-registry agents search o gcloud agent-registry mcp-servers search.

Por ejemplo, busca un agente que pueda controlar las reservas de vuelos:

gcloud agent-registry agents search \
    --project=PROJECT_ID \
    --location=REGION \
    --search-string="flight OR booking"

Busca un servidor de MCP que proporcione herramientas de base de datos:

gcloud agent-registry mcp-servers search \
    --project=PROJECT_ID \
    --location=REGION \
    --search-string="database"

Reemplaza lo siguiente:

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

REST

Envía una solicitud POST al extremo agents:search o mcpServers:search con el campo searchString en el cuerpo de la solicitud.

Por ejemplo, busca un agente que pueda controlar las reservas de vuelos:

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{"searchString": "flight OR booking"}' \
    "https://agentregistry.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/agents:search"

Busca un servidor de MCP que proporcione herramientas de base de datos:

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{"searchString": "database"}' \
    "https://agentregistry.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/mcpServers:search"

Reemplaza lo siguiente:

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

Buscar por prefijo

Las búsquedas de prefijos están optimizadas para una latencia baja, lo que permite que tus aplicaciones recuperen agentes y herramientas relevantes de forma dinámica a medida que el usuario escribe.

Si compilas una interfaz de organizador o una función de autocompletado, puedes realizar búsquedas de prefijos en el Registro de agentes para encontrar resultados que comiencen con una cadena determinada. Las búsquedas de prefijos usan el símbolo comodín de sufijo * para buscar el comienzo de una palabra:

gcloud

Ejecuta el comando gcloud agent-registry agents search o gcloud agent-registry mcp-servers search con una expresión de prefijo.

Por ejemplo, busca agentes cuyo nombre visible comience con Best_A2A_*:

gcloud agent-registry agents search \
    --project=PROJECT_ID \
    --location=REGION \
    --search-string="displayName:Best_A2A_*"

De manera similar, busca servidores de MCP cuyo nombre visible comience con Prod_Server_*:

gcloud agent-registry mcp-servers search \
    --project=PROJECT_ID \
    --location=REGION \
    --search-string="displayName:Prod_Server_*"

Reemplaza lo siguiente:

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

REST

Pasa la expresión de prefijo en el campo searchString del cuerpo de la solicitud:

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{"searchString": "displayName:Best_A2A_*"}' \
    "https://agentregistry.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/agents:search"

Reemplaza lo siguiente:

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

Cómo buscar habilidades independientes

Vista previa

Este producto o función está sujeto a las "Condiciones de la Oferta de la Fase Previa a la DG" en la sección Condiciones Generales del Servicio 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.

Puedes buscar habilidades independientes registradas en el Registro de agentes. Esta función te permite descubrir capacidades reutilizables para adjuntar a tus agentes.

Cuando buscas habilidades, buscas la revisión de habilidad predeterminada. Para actualizar la revisión predeterminada de una habilidad, consulta Actualiza los metadatos de la habilidad o la revisión predeterminada.

Modos de búsqueda

Puedes usar dos modos de búsqueda de habilidades según tus requisitos:

• Búsqueda por palabra clave: Analiza solo los atributos de metadatos básicos, como el nombre visible, la descripción, el nombre del recurso y el identificador de habilidad. Este modo está optimizado para búsquedas de baja latencia, búsquedas exactas y autocompletado de nombres. Para ver un ejemplo, consulta Busca habilidades por palabra clave o expresión.
• Búsqueda semántica: Indexa automáticamente el contenido completo de la carga útil de SKILL.md, incluidas las instrucciones en lenguaje natural, las secuencias de comandos y los recursos de metadatos. Este modo identifica temas conceptuales y está optimizado para que los agentes de organización descubran paquetes de capacidades relevantes de forma dinámica, según tu intent. Para ver un ejemplo, consulta Busca habilidades por significado semántico.

Campos y sintaxis de búsqueda

Cuando se realizan búsquedas por metadatos o cadenas de palabras clave, se indexan los siguientes campos:

Nombre del campo	Comportamiento de mayúsculas y minúsculas	Búsqueda por prefijo	Búsqueda en todos los campos	Descripción
displayName	No distingue mayúsculas de minúsculas	Sí	Sí	Es el nombre visible de la habilidad. Usa este campo para buscar nombres comunes.
description	No distingue mayúsculas de minúsculas	No	Sí	La descripción detallada del propósito y la funcionalidad de la habilidad. Usa este campo para buscar palabras clave.
name	No distingue mayúsculas de minúsculas	Sí	Sí	Es el nombre del recurso de la habilidad. Usa este campo para buscar por nombre de recurso.
skillId	No distingue mayúsculas de minúsculas	Sí	Sí	Es el identificador de la habilidad. Usa este campo para encontrar los recursos de un publicador específico. Por ejemplo, el formato de las habilidades administradas por Google es urn:skill:PUBLISHER_ID:NAMESPACE:SKILL_ID.
publisher	No distingue mayúsculas de minúsculas	Sí	No	Es el publicador asociado con la habilidad. Usa este campo para filtrar por la organización de publicación.
frontmatter.name	No distingue mayúsculas de minúsculas	No	No	Es el nombre de la habilidad definida en el encabezado del archivo SKILL.md.
frontmatter.description	No distingue mayúsculas de minúsculas	No	No	Es la descripción de la habilidad definida en el encabezado del archivo SKILL.md.
frontmatter.compatibility	No distingue mayúsculas de minúsculas	No	No	La compatibilidad de la habilidad definida en el encabezado del archivo SKILL.md.
frontmatter.license	No distingue mayúsculas de minúsculas	No	No	La licencia de la habilidad definida en el encabezado del archivo SKILL.md.
createTime	No aplicable	No	No	Es la marca de tiempo de la creación de la habilidad. Este campo solo está disponible en los filtros. Admite operadores de rango, como <, > y coincidencias exactas.
updateTime	No aplicable	No	No	Es la marca de tiempo de la última actualización de la habilidad. Este campo solo está disponible en los filtros. Admite operadores de rango, como <, > y coincidencias exactas.

Para buscar habilidades, proporciona una cadena de consulta con la marca --query en gcloud CLI o el parámetro searchString en la API de REST. Puedes usar los siguientes elementos de sintaxis en tus solicitudes de búsqueda:

• Operadores booleanos: Incluye los operadores AND, OR o NOT para encadenar requisitos.
• Filtros específicos de campos: Se orientan a un campo con el operador :, por ejemplo, displayName:database.
• Búsqueda de prefijos: Usa el símbolo comodín de sufijo * para encontrar valores que comiencen con un prefijo específico, por ejemplo, displayName:cloud-*.

Busca habilidades por palabra clave o expresión

Busca habilidades que tengan un prefijo de nombre visible y una palabra clave de descripción específicos:

gcloud

Ejecuta el comando gcloud alpha agent-registry skills search con --search-type=keyword:

gcloud alpha agent-registry skills search \
    --project=PROJECT_ID \
    --location=REGION \
    --query="displayName:cloud-* AND description:database" \
    --search-type=keyword

Reemplaza lo siguiente:

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

REST

Envía una solicitud GET al extremo skills:search con searchString y searchType=KEYWORD:

curl -G -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    --data-urlencode "searchString=displayName:cloud-* AND description:database" \
    --data-urlencode "searchType=KEYWORD" \
    "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/REGION/skills:search"

Reemplaza lo siguiente:

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

Buscar habilidades por significado semántico

Busca habilidades relacionadas con la administración de bases de datos relacionales con la búsqueda semántica:

gcloud

Ejecuta el comando gcloud alpha agent-registry skills search con --search-type=semantic:

gcloud alpha agent-registry skills search \
    --project=PROJECT_ID \
    --location=REGION \
    --query="manage and configure relational databases" \
    --search-type=semantic

Reemplaza lo siguiente:

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

REST

Envía una solicitud GET al extremo skills:search con searchString y searchType=SEMANTIC:

curl -G -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    --data-urlencode "searchString=manage and configure relational databases" \
    --data-urlencode "searchType=SEMANTIC" \
    "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/REGION/skills:search"

Reemplaza lo siguiente:

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

Habilidades administradas por Google

Las habilidades administradas por Google se pueden descubrir desde cualquier proyecto. Para obtener una lista de las habilidades administradas por Google disponibles, consulta el repositorio de google/skills en GitHub.

Descubre extremos y filtra componentes por metadatos

También puedes descubrir cualquier componente en el Registro de agentes, incluidos los extremos registrados, enumerando su colección y filtrando por campos de metadatos estructurados:

• Descubre extremos: Debido a que los recursos de Endpoint no admiten consultas de :search, los descubres explorando la pestaña Extremos en la consola deGoogle Cloud , ejecutando gcloud agent-registry endpoints list --filter o llamando al método REST endpoints.list. Para obtener instrucciones completas, consulta Administra y descubre extremos.
• Filtra agentes, servidores de MCP y habilidades: Cuando conozcas el identificador de registro (URN), el nombre visible o el atributo de un componente, filtra la colección en la consola deGoogle Cloud o pasa --filter a gcloud agent-registry agents list, gcloud agent-registry mcp-servers list o gcloud alpha agent-registry skills list. Para obtener más información, consulta Administra agentes, Administra servidores y herramientas de MCP y Administra habilidades.