⚠️ Repo moved under ai-platform-engineering ⚠️

🚀 Backstage AI Agent

🧪 Evaluation Badges

Claude	Gemini	OpenAI	Llama

---

• 🤖 Backstage Agent is an LLM-powered agent built using the LangGraph ReAct Agent workflow and MCP tools.
• 🌐 Protocol Support: Compatible with A2A protocol for integration with external user clients.
• 🛡️ Secure by Design: Enforces Backstage API token-based authentication and supports external authentication for strong access control.
• 🔌 Integrated Communication: Uses langchain-mcp-adapters to connect with the Backstage MCP server within the LangGraph ReAct Agent workflow.
• 🏭 First-Party MCP Server: The MCP server is generated by our first-party openapi-mcp-codegen utility, ensuring version/API compatibility and software supply chain integrity.

---

🚀 Getting Started

Running it via Docker:

1️⃣ Configure Environment

Ensure your .env file is set up as described in the cnoe-agent-utils usage guide based on your LLM Provider.

Example .env configuration:

############################
# Agent Configuration
############################
LLM_PROVIDER=azure-openai
AGENT_NAME=backstage

############################
# Azure OpenAI Configuration
############################
AZURE_OPENAI_API_KEY=<your-azure-key>
AZURE_OPENAI_API_VERSION=2025-04-01-preview
AZURE_OPENAI_DEPLOYMENT=gpt-4.1
AZURE_OPENAI_ENDPOINT=<your-azure-endpoint>

############################
# Backstage Configuration
############################
BACKSTAGE_API_KEY=<your-backstage-key>
BACKSTAGE_API_URL=https://api.backstage.io

2️⃣ Start the Agent (A2A Mode)

1. Pull the A2A image:

docker pull ghcr.io/cnoe-io/agent-backstage:a2a-latest

2. Run the agent in a Docker container using your .env file:

docker pull ghcr.io/cnoe-io/agent-backstage:a2a-latest && \
docker run --rm -p 0.0.0.0:8000:8000 -it \
  -v $(pwd)/.env:/app/.env \
  ghcr.io/cnoe-io/agent-backstage:a2a-latest

3️⃣ Run the Client

Use the agent-chat-cli to interact with the agent:

uvx https://github.com/cnoe-io/agent-chat-cli.git a2a

---

🏗️ Architecture

flowchart TD
  subgraph Client Layer
    A[User Client A2A]
  end

  subgraph Agent Transport Layer
    B[Google A2A]
  end

  subgraph Agent Graph Layer
    C[LangGraph ReAct Agent]
  end

  subgraph Tools/MCP Layer
    D[Langchain MCP Adapter]
    E[Backstage MCP Server]
    F[Backstage API Server]
  end

  A --> B --> C
  C --> D
  D -.-> C
  D --> E --> F --> E

Loading

✨ Features

• 🤖 LangGraph + LangChain MCP Adapter for agent orchestration
• 🧠 Azure OpenAI GPT-4 as the LLM backend
• 🔗 Connects to Backstage via a dedicated Backstage MCP agent
• 🔄 A2A protocol support for flexible integration and multi-agent orchestration
• 📊 Comprehensive Backstage API Support:
  • Catalog Management
  • Service Management
  • User Management
  • Plugin Management
  • Documentation Management

---

Local Development

Running Locally

You can run the agent locally without Docker:

First clone the repo

git clone https://github.com/cnoe-io/agent-backstage.git
cd agent-backstage

make run-a2a

In a new terminal, start the A2A client:

make run-a2a-client

Quick Demos

▶️ Test with Backstage API

🏃 Quick Start: Set Up Backstage Access

1. Create a Backstage Account: If you don't have one, sign up at Backstage.

2. Generate an API Key:

   • Log in to your Backstage account
   • Go to Configuration → API Access
   • Create a new API key with appropriate permissions
   • Save the API key securely

3. Get Your Backstage Domain:

   • Your API URL will be https://api.backstage.io
   • Update the BACKSTAGE_API_URL in your .env file

Example Interactions

1. Catalog Management

User: list all services
Agent: Here are the current services:

1. ID: BS123ABC - Web Application
   Status: active
   Owner: John Smith

2. ID: BS456DEF - Database Cluster
   Status: active
   Owner: DevOps Team

Let me know if you need more details about any service or would like to take action!

2. Service Management

User: show me all plugins
Agent: Here are all the plugins configured in Backstage:

1. Web Application (ID: PS1)
   - Status: active
   - Integration: API
   - Team: Platform

2. Database Cluster (ID: PS2)
   - Status: active
   - Integration: Nagios
   - Team: Infrastructure

3. Payment Gateway (ID: PS3)
   - Status: maintenance
   - Integration: Custom
   - Team: Payments

Would you like more details about any specific plugin?

🔍 Troubleshooting

Common Issues

1. Docker Issues

   • Ensure Docker daemon is running
   • Check if you have sufficient permissions
   • Verify the required images are available

2. Port Conflicts

   • If port 8000 is in use, modify port mapping in docker run command
   • Check for other services using required ports

3. Environment Variables

   • Verify all required variables in .env
   • Check API keys and tokens are valid
   • No trailing spaces in values

4. Client Connection Issues

   • Server must be running before client
   • Port numbers should match
   • API keys must match between server and client

Logs

• Docker: Use docker logs <container-id>
• Local: Check terminal output
• Debug mode: Set DEBUG=true in .env

📚 Documentation

For more detailed information about the project, please refer to:

• API Documentation - Detailed API reference
• Architecture Overview - System design and components
• Development Guide - Setup and development workflow
• Deployment Guide - Production deployment instructions
• Contributing Guide - How to contribute to the project
• Security Policy - Security practices and vulnerability reporting
• License - Project license details
• Changelog - Version history and changes
• Code of Conduct - Community guidelines

🔐 Security Notes

• Never commit your .env file to version control
• Keep your API keys and tokens secure
• Use environment variables or secret managers in production
• Regularly rotate your API keys and tokens

👥 Maintainers

See MAINTAINERS.md for the list of maintainers.

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details on how to get started.

📄 License

Apache 2.0