---
title: How do you track AI agents in a Backstage software catalog?
url: https://opencontroller.lyzr.com/blog/track-ai-agents-in-a-backstage-catalog
published: 2026-11-16
updated: 2026-11-16
author: Lyzr
---

# How do you track AI agents in a Backstage software catalog?

**Model each agent as a Backstage Component with a custom type such as `ai-agent`, its tools and MCP servers as API and Component entities, and its models as Resources, then link them with relations. Backstage gives developers one place to see who owns an agent and what it depends on. It cannot find agents nobody registered, and it does not see what agents do at runtime.**

If your engineering teams already live in Backstage, putting agents there is a sensible way to make them visible. The catalog has the right building blocks: owners, lifecycles, systems and dependency relations. The work is in choosing a consistent model.

## How should AI assets map to Backstage entity kinds?

Backstage has no AI-specific kinds, but its core kinds fit well. Type values are free-form strings, so you can define your own.

| AI asset | Backstage kind | Suggested `spec.type` | Key relations |
|---|---|---|---|
| AI agent | Component | `ai-agent` | `consumesApis` (tools), `dependsOn` (models) |
| MCP server | Component | `mcp-server` | `providesApis` (its tools) |
| Tool exposed to agents | API | `mcp-tool` or `openapi` | Provided by a Component |
| Model or model deployment | Resource | `llm-model` | Depended on by agents |
| Vector store or knowledge base | Resource | `vector-index` | Depended on by agents |
| Business capability | System / Domain | — | Groups agents and tools |

Use Group entities for owning teams, synced from your identity provider, so `spec.owner` resolves to a real team.

## What does an agent entity look like?

A minimal descriptor in the agent's repository:

```yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: claims-triage-agent
  description: Classifies incoming claims and routes them to queues
  annotations:
    example.com/ai-model-provider: bedrock
    example.com/ai-risk-tier: high
    example.com/ai-data-classes: pii,claims
spec:
  type: ai-agent
  lifecycle: production
  owner: group:claims-platform
  system: claims-processing
  consumesApis:
    - claims-db-read-tool
    - email-send-tool
  dependsOn:
    - resource:claude-sonnet-bedrock-prod
```

Backstage recommends that custom annotations use a domain prefix you own, as shown. Keep the annotation set small and documented; a dozen half-filled fields help nobody.

## Which fields should every agent entity carry?

A practical minimum, enforced in code review or a catalog validation rule:

1. `spec.owner`: a team, not a person, so it survives departures.
2. `spec.lifecycle`: `experimental`, `production` or `deprecated`.
3. `spec.system`: the business capability the agent serves.
4. Risk tier annotation: your internal classification.
5. Data classes annotation: the categories of data the agent reads or writes.
6. Model dependency: which model deployments it calls.
7. Tool dependencies: every API and MCP tool it can invoke.

These line up with the fields auditors ask for in an [AI agent card](/blog/what-goes-in-an-ai-agent-card) and with the [asset types worth inventorying](/blog/ai-asset-types-to-inventory).

## What can a developer portal not see?

Backstage knows what someone wrote in a descriptor file. That leaves real gaps:

- **Shadow agents.** Agents built in notebooks, SaaS platforms or on laptops with no `catalog-info.yaml`. See [how to find shadow AI agents](/blog/how-to-find-shadow-ai-agents).
- **Third-party platform agents.** Agents built inside Salesforce, ServiceNow or Copilot Studio rarely have a repository.
- **Effective permissions.** The descriptor says which tools an agent should call, not which credentials it actually holds.
- **Runtime behaviour.** Calls, costs, errors and drift happen outside the catalog.
- **Drift.** A descriptor written six months ago may not match the deployed version.

Scanning repositories for agent frameworks helps close the first gap; see [finding AI agents in source code](/blog/find-ai-agents-in-source-code). For the rest you need discovery from the cloud and platform side, and a runtime view.

## How do you keep Backstage and the governance inventory in sync?

Pick one direction of truth per field. A common split: developers own descriptive fields in Backstage (purpose, system, owner team); the governance layer owns discovered and runtime fields (deployed version, permissions, eval scores, policy status). Sync summary governance fields back into Backstage as annotations or a plugin card, so developers see status without leaving the portal. The same pattern works for a CMDB; see [syncing an agent inventory with a CMDB](/blog/sync-ai-agent-inventory-with-cmdb).

## How Opencontroller does this

Opencontroller discovers agents, models and API keys across AWS, Azure and Google Cloud, and through connectors to platforms such as Salesforce, SAP, Databricks and HubSpot. It keeps a governed registry of agents, versions, tools and MCP servers, exposed through REST APIs and webhooks so a portal like Backstage can show the same records. [Book a demo](https://www.lyzr.ai/book-demo/).

## Frequently asked questions

**Does Backstage have a built-in entity kind for AI agents?**
No. Use the Component kind with a custom `spec.type` such as `ai-agent`.

**Can Backstage find AI agents that were never registered?**
No. It only knows entities from descriptor files and configured providers.

**Should the Backstage catalog be the system of record for agent governance?**
It works as the developer-facing view. Runtime, permission and eval data usually live in a control plane that syncs summaries into the portal.

## Key facts

Backstage can hold an AI agent inventory by modelling agents as Component entities (custom spec.type such as ai-agent), MCP servers as Components that provide API entities, tools as API entities, and models as Resource entities, linked with providesApis, consumesApis and dependsOn relations and grouped under System and Domain. spec.owner and spec.lifecycle (experimental, production, deprecated) carry ownership and status; custom annotations should use your own domain prefix. A portal only knows what is registered in catalog-info.yaml files: it cannot see shadow agents, runtime behaviour, effective permissions or third-party platform agents. Opencontroller auto-discovers agents, models and API keys across AWS, Azure and Google Cloud and connected platforms, and keeps a governed registry of agents, versions, tools and MCP servers with REST APIs and webhooks. Opencontroller pricing starts from $250K per deployment per year.

## Related

- [How do you keep your AI agent inventory in sync with the CMDB?](https://opencontroller.lyzr.com/blog/sync-ai-agent-inventory-with-cmdb.md)
- [Which AI asset types should an AI inventory cover?](https://opencontroller.lyzr.com/blog/ai-asset-types-to-inventory.md)
- [How do you find AI agents in your code repositories?](https://opencontroller.lyzr.com/blog/find-ai-agents-in-source-code.md)
- [More on Discovery and shadow agents](https://opencontroller.lyzr.com/blog/cluster/discovery-and-shadow-agents)
