AI Asset entity model reference

The AI Catalog represents AI assets by using a small set of Backstage Software Catalog entity kinds. Use this reference to understand which entity kind and spec.type value represents each AI asset category, and which annotations each entity requires.

Important

The AiResource entity is a Developer Preview feature. Developer Preview features are not supported by Red Hat in any way and are not functionally complete or production-ready. Do not use Developer Preview features for production or business-critical workloads. Developer Preview features provide early access to functionality in advance of possible inclusion in a Red Hat product offering. Customers can use these features to test functionality and provide feedback during the development process. Developer Preview features might not have any documentation, are subject to change or removal at any time, and have received limited testing. Red Hat might provide ways to submit feedback on Developer Preview features without an associated SLA.

For more information about the support scope of Red Hat Developer Preview features, see Developer Preview Support Scope .

The AI Catalog builds on the Backstage Catalog Model Layer to define AI-specific entity kinds. The AiResource entity kind, which already represents AI skills and rules in upstream Backstage, is extended in Red Hat Developer Hub (RHDH) 2.1 to also represent AI agents through the agent value of spec.type . Model servers and Model Context Protocol (MCP) servers are represented by the AiModelServerAPI and API entity kinds.

AI asset category-to-entity-kind mapping

The following table maps each AI asset category to the Backstage entity kind, the spec.type value, and the annotation that the AI Catalog requires to classify the entity.

AI asset category RHDH/Backstage entity kind spec.type Required annotation

Agent

AiResource

agent

rhdh.io/ai-asset-category: agent

Skill

AiResource

skill

rhdh.io/ai-asset-category: skill

Rule

AiResource

rule

rhdh.io/ai-asset-category: rule

MCP server

API

mcp-server

rhdh.io/ai-asset-category: mcp-server

Model server

AiModelServerAPI

ai-model-server

rhdh.io/ai-asset-category: model-server

Common AI asset annotations

In addition to the required rhdh.io/ai-asset-category annotation, AI asset entities can set the following optional annotations. The AI Catalog uses these annotations to enrich search, filtering, and the entity detail page.

Annotation Description

rhdh.io/ai-asset-category

Required. The AI asset category, as listed in the mapping table. This annotation determines how the AI Catalog classifies and filters the entity.

rhdh.io/ai-asset-version

Optional. The version of the AI asset, for example 1.2.0 .

rhdh.io/ai-asset-source

Optional. The origin of the AI asset, for example github , internal , registry , or model-registry .

Example entities

The following examples show one entity for each entity kind. For the complete field reference for the AiResource entity kind, see AiResource entity schema reference.

Example: AiResource entity with spec.type: agent

apiVersion: backstage.io/v1alpha1 kind: AiResource metadata: name: developer-assistant title: Developer Assistant Agent description: An AI agent that helps developers with code generation, debugging, and documentation. annotations: rhdh.io/ai-asset-category: agent rhdh.io/ai-asset-version: '3.1.0' rhdh.io/ai-asset-source: internal spec: type: agent lifecycle: production owner: team-ai-platform model: openai/vllm-inference/gpt-4.1 instructions: An AI agent that helps developers with code generation and debugging. enableRAG: true

Example: API entity with spec.type: mcp-server

apiVersion: backstage.io/v1alpha1 kind: API metadata: name: github-mcp-server title: GitHub MCP Server description: Model Context Protocol server that provides GitHub repository context. annotations: rhdh.io/ai-asset-category: mcp-server spec: type: mcp-server lifecycle: experimental owner: team-integrations definition: | openapi: 3.0.0 info: title: GitHub MCP Server version: 0.9.0 remotes: - url: https://mcp.example.com/github type: streamable-http

Example: AiModelServerAPI entity with spec.type: ai-model-server

apiVersion: backstage.io/v1alpha1 kind: AiModelServerAPI metadata: name: granite-model-server title: Granite Model Server description: Model server that hosts code generation and instruction-following models. annotations: rhdh.io/ai-asset-category: model-server spec: type: ai-model-server lifecycle: production owner: team-ml-ops serverType: openai-v1 serverUrl: https://granite.example.com/v1 requiresApiKey: true models: discoverable: true available: - granite-3-code - granite-3-instruct default: granite-3-instruct

How the AI Catalog uses the entity model

The How to use this tab, also called the Usage tab, in the AI Catalog user interface sources its content from the annotations and spec fields that are described in this reference. When you set the rhdh.io/ai-asset-category annotation and the corresponding spec.type value, the AI Catalog classifies the entity, applies the correct filters, and renders category-specific usage guidance on the entity detail page. For more information about viewing AI assets in the catalog, see Discover and view AiResource entities.

Note

The upstream Backstage RFCs that define these AI asset entity kinds, RFC 32062 and RFC 33060, are in draft and are not finalized. The entity model that is documented here reflects the current draft and might change. A future release might supersede these entity kinds and provide a documented migration path.