Skip to content

Conversation

@dfl-aeb
Copy link

@dfl-aeb dfl-aeb commented Jul 10, 2025

Add UI customization support for GenAI chat assistant

image
  • Enable dynamic agent titles, descriptions, and welcome messages via app-config.yaml
  • Add frontend config schema with @visibility annotations for security
  • Integrate EmptyState component with MarkdownContent for rich welcome messages
  • Support Markdown formatting including links in welcome messages
genai:
  agents:
    general: 
      title: '🤖 General AI Assistant'
      description: 'Start chatting with your AI Assistant!' 
      welcomeMessage: |
        Hello! I'm here to help with your platform engineering questions. What would you like to know? 

        For more information, check out the [documentation](/docs)

Reason for this change

The GenAI plugin supports multiple agents for different use cases (e.g., general assistance, documentation help, code review). However, all agents currently show the same generic UI text:

  • Static titles: All agents display "Chat Assistant" regardless of their purpose
  • Generic descriptions: Empty state shows "Start chatting!" for all agents
  • Plain text welcome messages: No way to provide rich, agent-specific onboarding with links to relevant documentation

This creates a poor user experience where users can't distinguish between different agents or understand their specific capabilities. Organizations need to customize these UI elements to:

  • Clearly identify each agent's purpose (e.g., "📚 Documentation Assistant", "🤖 Code Review Bot")
  • Provide contextual descriptions and welcome messages
  • Include hyperlinks to relevant documentation, guidelines, or support resources

Description of changes

Configuration Schema Enhancement:

  • Added frontend config schema (config.d.ts) with @visibility frontend annotations to expose agent UI configuration securely
  • Extended agent configuration to support title, description, and welcomeMessage properties
  • Implemented proper TypeScript interfaces for type safety

UI Component Updates:

  • Created useAgentMetadata hook to load agent-specific UI configuration with fallback defaults
  • Updated AgentPage to use dynamic titles from configuration instead of static prop
  • Enhanced ChatHistoryComponent to use Backstage's EmptyState component with agent-specific content
  • Integrated MarkdownContent component to support rich formatting in welcome messages

Documentation:

  • Added comprehensive UI customization guide with step-by-step setup instructions
  • Updated main README with quick-start section for UI customization
  • Explained the security model and why each Backstage instance needs its own config schema

Description of how you validated changes

Manual Testing:

  • Verified UI customization works with different agent configurations
  • Tested Markdown rendering including hyperlinks in welcome messages
  • Confirmed fallback behavior when no configuration is provided
  • Validated that EmptyState component integrates properly with MarkdownContent

Configuration Testing:

  • Tested with and without config.d.ts setup to ensure graceful degradation
  • Verified TypeScript compilation and config schema validation
  • Confirmed @visibility frontend annotations work correctly

Cross-browser Testing:

  • Tested UI rendering in different browsers and themes
  • Verified Markdown links are clickable and properly styled

Checklist


By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

- Enable dynamic agent titles, descriptions, and welcome messages via app-config.yaml
- Add frontend config schema with @visibility annotations for security
- Integrate EmptyState component with MarkdownContent for rich welcome messages
- Support Markdown formatting including links in welcome messages
@dfl-aeb dfl-aeb requested a review from a team as a code owner July 10, 2025 15:29
@niallthomson
Copy link
Contributor

Hey @dfl-aeb thanks for the PR! I like the changes.

I committed a couple small tweaks, let me know if you disagree:

  1. I added a check to throw an error if the agent doesn't exist, we needed this anyway and you addition helps slot this in
  2. I changed description to tagLine. Although your idea made sense, I recently added an MCP server to the plugin that has kind of taken over this field and it has unfortunately doubled up as a prompt-like field due to that.

@dfl-aeb
Copy link
Author

dfl-aeb commented Jul 29, 2025

Thanks! Sounds good to me. The only thing I stumbled upon was this error message during startup:

[backend]: ForwardedError: Plugin 'aws-genai' startup failed; caused by Error: Missing required config value at 'genai.agents.general.description' in 'app-config.local.yaml'****

The description is still required in the config.d.ts of the backend. I think it would be helpful to clarify when to use which configuration and what the purpose of the description is besides the tagLine?!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants