AiResource entity schema reference
Use this reference to define an AiResource entity in a catalog-info.yaml file. The asset location is set in the backstage.io/source-location annotation, which supports a source repository URL or an OCI image reference.
The AiResource entity kind is experimental and its schema might change. Set lifecycle: experimental until the schema stabilizes.
Required fields
| Field | Description |
|---|---|
|
|
The Backstage API version. Use |
|
|
The entity kind. Must be |
|
|
A unique name for the asset within the catalog. |
|
|
A short description of the asset. A clear description improves discoverability in search and filtering. |
|
|
The asset location, in location-reference form. For a source repository, use |
|
|
The category of content that the asset contains. One of |
|
|
The lifecycle state of the asset. Set to |
|
|
The team or group that owns the asset. Ownership is enforced by the existing catalog role-based access control (RBAC) model. |
Optional fields
| Field | Description |
|---|---|
|
|
A list of tags that describe the asset, such as |
|
|
A list of external links that are shown on the entity detail page. |
|
|
Additional annotations for the entity, such as |
Accepted location references
The backstage.io/source-location annotation accepts the following forms:
| Location type | Expected backstage.io/source-location value |
|---|---|
|
Source repository |
A source repository URL with the |
|
OCI image |
An OCI image reference with the |
Example: skill in a source repository
apiVersion: backstage.io/v1alpha1 kind: AiResource metadata: name: python-test-writing-skill description: Skill for writing Python unit tests. annotations: backstage.io/source-location: url:https://github.com/my-org/python-test-writing-skill spec: type: skill lifecycle: experimental owner: team-platform
Example: agent in a source repository
Use spec.type: agent to register an AI agent, such as an OpenAI Agent SDK compatible agent.
apiVersion: backstage.io/v1alpha1
kind: AiResource
metadata:
name: developer-assistant
description: An AI agent that helps developers with code generation, debugging, and documentation.
annotations:
backstage.io/source-location: url:https://github.com/my-org/developer-assistant-agent
spec:
type: agent
lifecycle: experimental
owner: team-ai-platform
You do not need to register agents manually when you use the OGX entity provider. The OGX entity provider generates AiResource entities with spec.type: agent automatically from its configuration. For more information, see Configure the OGX entity provider.
Example: rule in a source repository
apiVersion: backstage.io/v1alpha1 kind: AiResource metadata: name: security-coding-rules description: Organization security rules for AI coding assistants. annotations: backstage.io/source-location: url:https://github.com/my-org/security-coding-rules spec: type: rule lifecycle: experimental owner: team-security
Example: skill packaged as an OCI image
Use the location-reference form url:oci://… . The url: prefix is required. The catalog stores the image reference only; it does not pull the image.
apiVersion: backstage.io/v1alpha1 kind: AiResource metadata: name: pdf-processor-skill description: Skill that extracts and summarizes PDF documents, published as an OCI image. annotations: backstage.io/source-location: url:oci://quay.io/my-org/skills/pdf-processor:v1.2.0 spec: type: skill lifecycle: experimental owner: team-platform