Cuando registras, descubres o conectas componentes en el Registro de agentes, puedes diagnosticar y resolver problemas comunes, como límites de cuota, errores de validación de habilidades y cargas útiles, discrepancias de ubicación, retrasos en la sincronización y errores de permisos.
Se superó la cuota de frecuencia de la API
El siguiente error se produce si superas el límite de frecuencia de solicitudes cuando interactúas con la API de Agent Registry o navegas con rapidez por Agent Registry en la consola deGoogle Cloud :
429 Too Many Requests
Para resolver este problema, implementa la retirada exponencial en tus clientes de API para administrar los porcentajes de solicitudes. La API de Agent Registry tiene una cuota de frecuencia predeterminada de 1,200 solicitudes por minuto o 20 consultas por segundo, a nivel global y por región.
Si encuentras limitaciones cuando cambias de pestaña en la consola de Google Cloud , espera
unos minutos y vuelve a intentarlo. Si tu caso de uso programático requiere límites más altos,
solicita un aumento de cuota
para la métrica RequestsPerMinute.
Error de tamaño de la carga útil durante el registro manual
El siguiente error se produce cuando registras manualmente un agente o un servidor de MCP con un archivo de especificación que supera el límite de tamaño:
La API rechaza la solicitud con un error que indica que la carga útil es demasiado grande.
Para resolver este problema, verifica que tu archivo agent-card.json o toolspec.json
sea inferior a 10 KB. Los tamaños de contenido de AgentSpec y McpServerSpec
están limitados a 10 KB. Minimiza tus archivos JSON, quita los espacios en blanco innecesarios o condensa las descripciones de las herramientas para cumplir con este límite. Para obtener más
información, consulta Esquemas JSON.
Faltan agentes o servidores de MCP después de la creación
El siguiente error se produce después de crear un agente o un servidor de MCP en un producto de Google Cloud compatible, como Google Workspace o Gemini Enterprise:
El recurso no aparece en el resultado cuando llamas a las APIs de ListAgents o
ListMcpServers.
Para resolver este problema, espera a que se complete la sincronización en segundo plano. Tus recursos se actualizan en tiempo real, pero los trabajos por lotes sin conexión periódicos propagan otras integraciones. Si tu recurso no aparece después de varias horas, verifica la configuración de Service Usage de tu proyecto y asegúrate de que la API correspondiente esté habilitada.
Las operaciones de larga duración parecen bloqueadas
El siguiente error ocurre cuando implementas agentes o configuras vinculaciones complejas:
La operación tarda mucho tiempo y parece detenida.
Para resolver este problema, usa la herramienta de MCP get_operation o el extremo de API google.longrunning.Operations.GetOperation para sondear el estado de la operación. Algunas creaciones de agentes y backends de MCP requieren un aprovisionamiento de infraestructura
significativo, lo que puede generar tiempos de operación de larga duración (LRO)
que pueden tardar hasta 30 minutos. Como resultado, configura los parámetros de tiempo de espera del cliente
y sondea la marca booleana done para verificar que se haya completado.
Se obtuvieron resultados vacíos cuando se recuperaban las vinculaciones disponibles
El siguiente error se produce si recuperas las vinculaciones disponibles para un
proveedor de autenticación
sin los permisos suficientes en el recurso AuthProvider de destino:
La API devuelve un array vacío o un error de acceso, incluso si la vinculación existe.
Para resolver este problema, verifica que tu principal tenga los permisos de Identity and Access Management (IAM) correctos en el recurso AuthProvider de destino.
La API aplica verificaciones estrictas de IAM y quita los objetos Binding
que hacen referencia a proveedores de autenticación a los que el emisor no tiene acceso. Asegúrate de que
tu principal tenga el acceso necesario en el proveedor de autenticación y el
rol roles/agentregistry.viewer en el proyecto.
La descarga de la revisión de habilidades falla con el error 302
El siguiente error se produce si intentas descargar una carga útil de revisión de habilidad
con la API de GetSkillRevision con el parámetro de consulta ?alt=media y tu
cliente HTTP no sigue los redireccionamientos:
{
"error": {
"code": 302,
"message": "Unknown Error.",
"status": "UNKNOWN"
}
}
Para resolver este problema, verifica que tu cliente HTTP esté configurado para
seguir los redireccionamientos automáticamente. El extremo ?alt=media requiere un redireccionamiento 302 para descargar correctamente el archivo de la habilidad. Por ejemplo, si usas curl, agrega la marca -L o --location a tu comando.
La validación de la revisión de la habilidad falla o muestra el estado FAILED
El siguiente error se produce cuando creas una revisión de habilidad nueva con un archivo ZIP no válido:
La revisión pasa a un estado FAILED y los agentes no pueden cargarla.
Para resolver este problema, verifica los registros de validación o inspecciona el contenido de la carga útil del archivo ZIP:
- Asegúrate de que el archivo ZIP contenga un archivo
SKILL.mden su raíz. - Verifica que el archivo
SKILL.mdtenga un bloque de encabezado YAML válido connameydescriptiondefinidos. - Confirma que la carga útil del archivo ZIP no supere los límites de tamaño: el tamaño comprimido debe ser inferior a 500 KB, el tamaño total sin comprimir debe ser inferior a 10 MB y el tamaño de los archivos individuales debe ser inferior a 1 MB.
- Verifica que el archivo no contenga vínculos simbólicos, elementos de recorrido de directorios,
como
.., ni rutas de acceso absolutas.
Las habilidades independientes no aparecen en las listas de recursos de servicios o agentes
El siguiente error se produce si consultas las listas de agentes o servicios para
habilidades independientes, por ejemplo, ejecutando
gcloud agent-registry services list o gcloud agent-registry agents list:
La habilidad independiente no aparece en el resultado.
Para resolver este problema, consulta la colección skills en su lugar:
- A diferencia de los agentes, los servidores de MCP y los endpoints registrados de forma manual, las habilidades independientes
no usan recursos
Serviceque se puedan escribir ni recursos de descubrimientoAgent,McpServeroEndpoint. En su lugar, el Registro de agentes representa las habilidades independientes directamente como recursosSkillde nivel superior y recursosSkillRevisioncon control de versiones. - Para enumerar, buscar o inspeccionar habilidades independientes, usa la pestaña Habilidades en la
consola deGoogle Cloud , ejecuta
gcloud alpha agent-registry skills listogcloud alpha agent-registry skills search, o llama a los métodos de la API de RESTskills. Para obtener instrucciones, consulta Administra habilidades y Busca habilidades independientes. - Si buscas habilidades de A2A intercaladas declaradas en la tarjeta de un agente, inspecciona el campo
skillsen el recurso de descubrimientoAgentcongcloud agent-registry agents describeogcloud agent-registry agents search.
Error de entidad de recurso no encontrada cuando se administran las políticas de IAP
El siguiente error se produce cuando usas comandos de gcloud iap web para administrar
las políticas de salida de Identity-Aware Proxy (IAP) en los recursos de Agent Registry:
NOT_FOUND: Requested entity was not found
Para resolver este problema, verifica lo siguiente:
- Estado del registro: Confirma que el componente de destino esté registrado en Agent Registry en la ubicación esperada.
- Formato del identificador: Confirma que tu comando o vinculación de política especifique el nombre del recurso estándar en lugar de un URN de identificador de registro.
- Marca de recurso: Verifica que la marca de recurso que pasas a
gcloud iap webcoincida con el tipo de recurso secundario del registro de agentes subyacente:- Para los extremos, como las APIs externas o los puntos de salida de la API de Google, usa
la marca
--endpoint. - Para los servidores del Protocolo de contexto del modelo, usa la marca
--mcp-server. - Para los agentes registrados, usa la marca
--agent.
- Para los extremos, como las APIs externas o los puntos de salida de la API de Google, usa
la marca
Verifica el nombre del recurso
que muestra gcloud agent-registry endpoints list,
gcloud agent-registry mcp-servers list o
gcloud agent-registry agents list
para confirmar si el nombre del recurso contiene /endpoints/, /mcpServers/ o
/agents/. Pasar la marca de recurso incorrecta, por ejemplo, pasar --endpoint
para un ID de servidor de MCP, causa un error NOT_FOUND.
Se denegó el permiso cuando se aplicaron las políticas de IAM de IAP para la Web
El siguiente error se produce cuando aplicas o modificas las políticas de IAM de la Web de IAP para los recursos de Agent Registry sin los roles administrativos necesarios:
ERROR: (gcloud.iap.web.set-iam-policy) PERMISSION_DENIED
Para resolver este problema, verifica que tu usuario o cuenta de servicio activos tengan los permisos necesarios en el proyecto que aloja el registro y la puerta de enlace:
- Asegúrate de que el emisor tenga el rol de administrador de políticas de IAP (
roles/iap.admin) o administrador de IAM del proyecto (roles/resourcemanager.projectIamAdmin) en el proyecto de administración central. - Confirma que el emisor tenga los permisos
iap.web.setIamPolicyyresourcemanager.projects.setIamPolicy.
No se encontró el servidor de MCP remoto en una ubicación regional
El siguiente error se produce si consultas un servidor de MCP remoto de Google o Google Cloud registrado automáticamente, o si le aplicas una política de salida de IAP, en una ubicación regional como us-central1:
La solicitud devuelve un error NOT_FOUND o una lista vacía, incluso cuando el servicio
proporciona extremos regionales (REP) o cuando el tráfico se enruta a través de un Agent Gateway
regional.
Cuando Agent Registry registra automáticamente un servidor de MCP de Google o
Google Cloud remoto para una API habilitada, crea el
recurso McpServer solo en la ubicación global, no en regiones individuales
como us-central1. Si el servicio proporciona extremos regionales, como
https://SERVICE.REGION.rep.googleapis.com/mcp,
Agent Registry enumera esas URLs regionales en el campo interfaces de
ese único recurso global McpServer.
Para solucionar este problema, realiza una de las siguientes acciones:
- Usa
globalpara los servidores registrados automáticamente: Especifica la ubicación deglobalcuando consultes el servidor en Agent Registry con--location=globalo aplícale políticas de salida de IAP con--region=global, incluso cuando el agente que realiza la llamada enrute el tráfico a través de una puerta de enlace regional. - Registra en una región para la residencia de datos: Si necesitas mantener los metadatos del registro
en una región específica, implementa servidores de MCP personalizados en entornos de ejecución regionales de
Cloud Run o
Google Kubernetes Engine (GKE), o
registra manualmente
el servidor de MCP y su URL de extremo regional en esa región y, luego, aplica
tu política de IAP en esa misma región. Cuando
Agent Gateway resuelve una URL de destino, las entradas del registro regional
tienen prioridad sobre las entradas de
global.
Errores de discrepancia de región cuando se configura Model Armor en Agent Gateway
El siguiente error se produce cuando configuras filtros de políticas de Model Armor en Agent Gateway en regiones que no coinciden:
La creación de la política de autorización falla con un error de discrepancia de región, o el tráfico enrutado a través de la puerta de enlace a un servidor de MCP falla en la evaluación de la política.
Para resolver este problema, verifica la alineación regional de tus recursos de puerta de enlace y las vinculaciones de políticas de destino:
- Alinea las regiones de la puerta de enlace y de Model Armor: Asegúrate de que Agent Gateway, las plantillas de Model Armor, y la extensión de autorización y la política residan en la misma región, como
us-central1. - Enruta a servidores de MCP regionales o de
global: No es necesario volver a registrar los servidores de MCP deglobalen una región solo para usar Model Armor. Debido a que Model Armor inspecciona las cargas útiles de solicitud y respuesta en la puerta de enlace regional, una puerta de enlace regional puede inspeccionar y controlar el tráfico enrutado a los servidores de MCP registrados en la ubicaciónglobal, así como a los destinos regionales. - Hacer coincidir las vinculaciones de salida de IAP con la ubicación de registro del destino: Aplica la vinculación de autorización de salida de IAP en la ubicación en la que está registrado el recurso
McpServerde destino. Usaglobalpara los servidores de MCP remotos registrados automáticamente o usa la región específica para los servidores de MCP registrados de forma regional.
El registro manual o la creación de vinculaciones fallan en una ubicación multirregional
El siguiente error se produce si intentas registrar manualmente un agente, un servidor de MCP
o un extremo, o crear una vinculación, en una ubicación multirregional, como
us o eu:
La API rechaza la solicitud con un error de ubicación no admitida o de argumento no válido.
Para resolver este problema, especifica una ubicación regional compatible, como
us-central1 o europe-west1, o la ubicación global. Las ubicaciones multirregionales us y
eu solo admiten el descubrimiento de componentes registrados automáticamente
y el registro o descubrimiento de habilidades
independientes. Para obtener la lista de ubicaciones compatibles, consulta Ubicaciones del registro de agentes.
Fallas cuando se accede a Agent Registry con la federación de identidades de personal
Los siguientes errores ocurren si accedes al Registro de agentes en la consola deGoogle Cloud o usas Google Cloud CLI cuando te autenticas con la federación de identidades de personal:
La consola deGoogle Cloud muestra errores de carga genéricos, como los siguientes:
- "Se produjo un error durante la carga…"
- "El servidor no pudo completar tu solicitud"
- "No se pudo cargar"
Además, los comandos gcloud pueden mostrar un error interno, como
error 13: an internal error has occurred.
Para resolver este problema, autentícate con una Cuenta de Google estándar administrada
a través de Cloud Identity o Google Workspace. Asegúrate de que la cuenta tenga los
permisos necesarios, como roles/agentregistry.admin o
roles/agentregistry.viewer.
Los servicios de administración de Gemini Enterprise Agent Platform tienen compatibilidad limitada con las identidades federadas. Otorgar roles de IAM más amplios a una principal federada no resuelve el problema.