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.
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 Copy linkLink copied!
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 |
|
|
|
|
Skill |
|
|
|
|
Rule |
|
|
|
|
MCP server |
|
|
|
|
Model server |
|
|
|
Common AI asset annotations Copy linkLink copied!
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 |
|---|---|
|
|
Required. The AI asset category, as listed in the mapping table. This annotation determines how the AI Catalog classifies and filters the entity. |
|
|
Optional. The version of the AI asset, for example |
|
|
Optional. The origin of the AI asset, for example |
Example entities Copy linkLink copied!
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 Copy linkLink copied!
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.
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.