@drewswiredin/backstage-plugin-assistants-backend

The backend plugin of AI Assistants for Backstage. It streams replies, runs Backstage actions as tools with the calling user's credentials, and calls MCP server tools under a configured credential or the user's own token. Assistant definitions live in the plugin database and are edited in-app; app-config.yaml holds providers, MCP servers, the approval gate, and runtime limits.

Pairs with the frontend plugin, @drewswiredin/backstage-plugin-assistants.

Docs: drewswiredin.github.io/backstage-assistants

Requirements

• Backstage 1.56 or later on the new backend system (@backstage/backend-defaults).
• Node 22.12 or later.
• A plugin database: SQLite, Postgres, or MySQL.
• Recommended: @backstage/plugin-signals-backend, so working and unread status reaches the browser as Signals rather than by polling.

Install

yarn --cwd packages/backend add @drewswiredin/backstage-plugin-assistants-backend

// packages/backend/src/index.ts
backend.add(import('@drewswiredin/backstage-plugin-assistants-backend'));

Minimal configuration

assistants:
  defaultModel: openrouter:anthropic/claude-sonnet-5
  builtinActions: true # the built-in catalog/TechDocs read tools
  providers:
    openrouter:
      type: openai-compatible
      apiKey: ${OPENROUTER_API_KEY}
      baseUrl: https://openrouter.ai/api/v1
      models:
        - name: anthropic/claude-sonnet-5
          contextWindow: 1000000

backend:
  actions:
    pluginSources:
      - assistants # plus catalog, scaffolder, etc. for their actions

The backend refuses to start until assistants.defaultModel and at least one provider with one model are configured. The first start seeds one assistant, open to every signed-in user; open /assistants and talk to it.

Documentation

• Getting started
• Model providers: OpenAI, Anthropic, Azure, OpenAI-compatible, and provider types from a backend module
• Actions and tools: Backstage actions, the built-in tools, and a recommended starter setup
• MCP servers: shared credentials, per-user sign-in, and servers that run their own OAuth
• Approvals and permissions
• Run in production: replicas, upgrades, logs, and troubleshooting
• Security
• Reference: configuration keys, startup errors, and HTTP routes

Example system prompts ship with this package, in examples/prompts/.

License

Apache-2.0