Soluciona problemas del registro de agentes

En esta página, se muestra cómo resolver problemas con Agent Registry.

Se excedió la cuota de frecuencia de la API

Es posible que encuentres este problema si interactúas con la API de Agent Registry o rápidamente navegas por Agent Registry en la Google Cloud consola:

429 Too Many Requests

Para resolver este problema, implementa la retirada exponencial en tus clientes de la API para administrar las frecuencias de solicitudes. La API de Agent Registry tiene una cuota de frecuencia predeterminada de 1,200 solicitudes por minuto a nivel global y por región (20 consultas por segundo).

Si encuentras limitaciones cuando cambias de pestaña en Google Cloud consola, espera unos momentos y vuelve a intentarlo. Si tu caso de uso programático requiere límites más altos, solicita un aumento de cuota para la RequestsPerMinute métrica.

Error de tamaño de carga útil durante el registro manual

Es posible que encuentres este problema si registras manualmente un agente o un servidor de MCP: 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 tenga menos de 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

Es posible que encuentres este problema si creas un agente o un servidor de MCP en un producto Google Cloud compatible, como Google Workspace o Gemini Enterprise: el recurso no aparece cuando se llama 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 otras integraciones se propagan mediante trabajos por lotes sin conexión que se ejecutan de forma periódica. 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 pertinente esté habilitada.

Las operaciones de larga duración parecen bloqueadas

Es posible que encuentres este problema si implementas agentes o configuras vinculaciones complejas: la operación tarda una cantidad significativa de tiempo y parece bloqueada.

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 backend de agentes y 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. Configura la configuración de tiempo de espera del cliente como resultado y sondea la marca booleana done para verificar la finalización.

Resultados vacíos cuando se recuperan las vinculaciones disponibles

Es posible que encuentres este problema si recuperas las vinculaciones disponibles para un proveedor de autenticación: la API muestra un empty array o un error de acceso, incluso si verificaste que existe la vinculación.

Para resolver este problema, verifica que tu principal tenga los permisos correctos de Identity and Access Management (IAM) en el recurso AuthProvider de destino. La API aplica verificaciones estrictas de IAM y quita los objetos Binding que hacen referencia a los proveedores de autenticación a los que el emisor no tiene acceso. Asegúrate de que tu principal tenga el acceso requerido en el proveedor de autenticación y el rol roles/agentregistry.viewer en el proyecto.

Falla la descarga de la revisión de habilidades con el error 302

Es posible que encuentres este problema si intentas descargar una carga útil de revisión de habilidades con la API de GetSkillRevision con el parámetro de consulta ?alt=media: la solicitud falla y muestra un error similar al siguiente:

{
  "error": {
    "code": 302,
    "message": "Unknown Error.",
    "status": "UNKNOWN"
  }
}

Para resolver este problema, verifica que tu cliente HTTP esté configurado para seguir automáticamente los redireccionamientos. 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.

Falla la validación de la revisión de habilidades o se muestra el estado FAILED

Es posible que encuentres este problema después de crear una nueva revisión de habilidades: 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 ZIP:

  • Asegúrate de que el archivo ZIP contenga un archivo SKILL.md en su raíz.
  • Verifica que el archivo SKILL.md tenga un bloque de metadatos iniciales de YAML válido con name y description definidos.
  • Confirma que la carga útil ZIP no exceda 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 archivo individual debe ser inferior a 1 MB.
  • Verifica que el archivo no contenga vínculos simbólicos, elementos de recorrido de directorios, como .., o rutas absolutas.

Error de entidad de recurso no encontrada cuando se administran políticas de IAP

Es posible que encuentres este problema si usas comandos gcloud iap web para administrar políticas de salida en recursos de Agent Registry:

NOT_FOUND: Requested entity was not found

Para resolver este problema, verifica que la marca de recurso que pasas a gcloud iap web coincida con el tipo de recurso secundario subyacente de Agent Registry:

  • 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.

Verifica el URI del recurso que muestra gcloud agent-registry [endpoints|mcp-servers|agents] list para confirmar si la ruta del recurso contiene /endpoints/, /mcpServers/ o /agents/. Si pasas la marca de recurso incorrecta, por ejemplo, si pasas --endpoint para un ID de servidor de MCP, se produce un error NOT_FOUND.

Se denegó el permiso cuando se aplicaron políticas de IAM web de IAP

Es posible que encuentres este problema si aplicas o modificas políticas de IAM web de Identity-Aware Proxy para recursos de Agent Registry:

ERROR: (gcloud.iap.web.set-iam-policy) PERMISSION_DENIED

Para resolver este problema, verifica que tu usuario activo o cuenta de servicio tenga 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 de administrador de IAM de proyectos (roles/resourcemanager.projectIamAdmin) en el proyecto de administración central.
  • Confirma que el emisor tenga los permisos iap.web.setIamPolicy y resourcemanager.projects.setIamPolicy.