Last modified October 16, 2026

Enable Agent Platform features in Backstage

The Agent Platform section ships with the Giant Swarm Backstage plugins but is off by default. Enabling it takes several independent configuration changes—none of them discoverable from the portal itself. This guide walks them in order: first the browse experience, then what deploying agents needs.

All configuration goes into the instance’s Backstage app-config.

Make the section appear

The Agent Platform is off by default. Switch it on for the instance with app.portals.agentPlatform:

app:
  portals:
    agentPlatform: true
  extensions:
    - page:agent-platform

The page:agent-platform extension carries the Agent Platform’s screens: Sessions, Agents, Models, Connectors, Workflows, and Usage. It’s enabled by default, so you don’t need to list it, but it’s only mounted while app.portals.agentPlatform is on. Without that setting, the portal shows nothing of the Agent Platform, even when app.extensions lists the extension.

app.portals.platformPortal decides whether the classic portal stays. It defaults to true, so the classic portal and the Agent Platform run side by side, each linking to the other. Set it to false to make the Agent Platform the portal’s only navigation.

To try the Agent Platform before switching it on for everyone, a person can turn on the agent-platform-shell feature flag in their portal settings. It applies to their browser only, after a reload, and isn’t offered while app.portals.agentPlatform is on.

Name the Muster installations

Without an explicit installation list, the Connectors screen falls back to a legacy single-server entry and the installation picker mislabels your installation. Configure each installation the portal should reach:

muster:
  installations:
    - name: <cluster name>
      url: https://muster.<cluster>.<base domain>/mcp
      authProvider: <auth provider name>

The name must match the Kubernetes cluster name the portal knows, so the resource views and the MCP proxy line up. The authProvider names the auth provider used for the user’s Muster sign-in. Without it, no per-user Muster session can exist and per-server sign-in is suppressed.

Let agent avatars render

Agents render their identifying icons from the installation’s avatar service at avatars.<base domain>. The portal’s content security policy blocks that host unless it’s allowed:

backend:
  csp:
    imgSrc:
      - "'self'"
      - 'data:'
      - https://avatars.<base domain>

Remember the array-replacement rule from the warning at the start: keep 'self' and data: in the list.

Configure skill repositories

The create-an-agent flow offers skills discovered from Git repositories. With no repositories configured, the skills step is skipped and every agent starts skill-less:

agentPlatform:
  skills:
    repositories:
      - https://github.com/giantswarm/agent-skills

Every SKILL.md file in a listed repository defines one selectable skill.

That’s the browse experience complete. Deploying agents needs no further portal configuration: the portal creates agents through agent-manager’s tools, called over the installation’s Muster as the signed-in person. The installation picker offers only installations whose Muster lists agent-manager.

Accept the portal’s token at the agent runtime

The Sessions screen reads the agent runtime API, which sits behind an OAuth proxy. That proxy accepts a bearer token only when the token’s audience matches its own client or an explicitly allowed extra audience. Each portal instance has its own OIDC client, so add the portal’s client ID as an extra audience in the platform deployment’s values:

kagent:
  oauth2-proxy:
    extraArgs:
      oidc-extra-audience: <portal OIDC client ID>

Several portal instances share one comma-separated value—don’t add a second oidc-extra-audience key, since a duplicate YAML map key drops one of them with no error. Without this, the Sessions screen answers 401 and reports it couldn’t read the installation.

What each capability needs

Related

• Agent Platform in the developer portal - What you just enabled.
• Create and deploy an agent - The flow these settings unlock.
• Install the Agent Platform on your own cluster - Where the platform side of this configuration lives.