Backstage Integration

Give your engineers an AI assistant inside your Backstage developer portal

Overview

Backstage is the open source developer portal that Spotify created. Engineering teams use it as their home for services, documentation and tools.

The Asyntai AI Assistant plugin adds an assistant page to that portal. Your engineers ask a question in plain words and get an answer from the content you gave Asyntai: your documentation site, your runbooks, your internal guides. Answers come with links to the right page, in the language of the question.

What You Get

An AI Assistant page with its own item in the sidebar
An Ask AI card for the Backstage home page
Follow-up questions in the same conversation, and a New chat button
A website picker when your Asyntai account has more than one knowledge base
Answers with headings, lists and links, in more than 80 languages

Requirements

A Backstage app on the new frontend system or the legacy one
An Asyntai account on the Starter plan or higher, because the plugin uses the Asyntai API
Access to your Backstage app-config.yaml

Installation

Follow these steps to add Asyntai to Backstage:

Install the Package

From the root of your Backstage repository, run:

yarn --cwd packages/app add @asyntai/backstage-plugin-ai-assistant

Get Your API Key

Sign in to Asyntai, open Settings, then API, and copy your API key. Store it on your Backstage server as the environment variable ASYNTAI_API_KEY.

Add the Proxy Entry

Add this to app-config.yaml. The Backstage backend adds the key to each request, so the key never reaches the browser.

proxy:
  endpoints:
    /asyntai:
      target: https://asyntai.com
      headers:
        Authorization: Bearer ${ASYNTAI_API_KEY}
      allowedMethods: ['GET', 'POST']

Turn On the Plugin

New frontend system: nothing to add. Backstage finds the plugin by itself when feature discovery is on. If it is off, add the plugin to packages/app/src/App.tsx:

import asyntaiPlugin from '@asyntai/backstage-plugin-ai-assistant';

export default createApp({
  features: [/* your other features */, asyntaiPlugin],
});

Legacy frontend system: add a route in App.tsx:

import { AsyntaiAssistantPage } from '@asyntai/backstage-plugin-ai-assistant';

<Route path="/ai-assistant" element={<AsyntaiAssistantPage />} />

Then add a sidebar item in components/Root/Root.tsx:

import { AsyntaiIcon } from '@asyntai/backstage-plugin-ai-assistant';

<SidebarItem icon={AsyntaiIcon} to="ai-assistant" text="AI Assistant" />

Ask a Question

Restart Backstage, open AI Assistant in the sidebar, and ask something your documentation answers.

Options

All options are optional. Put them in app-config.yaml:

asyntai:
  websiteId: docs.example.com   # a website id or domain from your Asyntai account
  title: Engineering Assistant  # the page title
  proxyPath: /asyntai           # change it only if you renamed the proxy entry

Without websiteId, the plugin uses your primary website and shows a picker when the account has more than one.

The Home Page Card

The plugin also brings an Ask AI card.

New frontend system: the card is a home page widget called AsyntaiAskAi. Add it from the home page editor, or put it in the default layout in app-config.yaml:

app:
  extensions:
    - page:home:
        config:
          defaultConfig:
            - component: AsyntaiAskAi
              column: 0
              row: 0
              width: 6
              height: 6

Legacy frontend system: put <AsyntaiAssistantCard /> on your home page or on any other page.

Tip: Add your runbooks and internal guides to the Asyntai knowledge base. The assistant then answers the questions your team asks each other in chat every day.

Removing It

Run yarn --cwd packages/app remove @asyntai/backstage-plugin-ai-assistant, then delete the /asyntai proxy entry and any lines you added to App.tsx.

Plans & Pricing

The plugin is free. It uses the Asyntai API, which needs the Starter plan or higher. View pricing.

Need Help?

If you have any questions or run into issues, contact us at [email protected].

Documentation