How to Start the Streamlit Frontend UI for Graph-RAG Agent

Run streamlit run frontend/app.py from the repository root to launch the Graph-RAG Agent web interface on http://localhost:8501.

The graph-rag-agent repository ships with a standalone Streamlit frontend that communicates with the FastAPI backend via HTTP. This guide explains exactly how to start the Streamlit frontend UI using the official entry point and configuration files found in the frontend/ directory.

Launch Command and Entry Point

The frontend entry point is located at frontend/app.py. This script initializes the entire user interface through its main() function, which orchestrates page configuration, session state management, and component rendering.

To start the UI, execute the following from the repository root:

cd graph-rag-agent/
streamlit run frontend/app.py

By default, this starts a local web server on http://localhost:8501 and opens the interface in your default browser.

What Happens When You Launch

When you run the launch command, frontend/app.py executes the following initialization sequence:

1. Configures the page via st.set_page_config – sets the title, icon, and wide layout mode.
2. Initializes session state via init_session_state – preserves chat history, selected agent, and debug flags across reruns.
3. Starts performance monitoring via init_performance_monitoring.
4. Injects custom CSS via custom_css for styling adjustments.
5. Renders the sidebar via display_sidebar for navigation and settings.
6. Displays the chat interface via display_chat_interface, or a two-column layout with display_debug_panel on the right when debug mode is enabled.

Configuration via Environment Variables

The frontend reads configuration from environment variables defined in frontend/frontend_config/settings.py. These settings allow you to customize the backend connection and default behavior without modifying code.

Override the Backend API URL

By default, the frontend connects to http://localhost:8000. To point it to a different FastAPI backend:

export FRONTEND_API_URL="http://my-server:8000"
streamlit run frontend/app.py

Enable Debug Mode

To start the UI with the debug panel visible by default:

export FRONTEND_DEFAULT_DEBUG=true
streamlit run frontend/app.py

This activates the two-column layout in display_chat_interface, showing the debug panel alongside the chat interface.

Programmatic Launch Methods

For automated deployments or Docker containers, you can launch the frontend programmatically using Python's subprocess module:

import subprocess

# Optional: Start the FastAPI backend

subprocess.Popen(["python", "server/main.py"])

# Launch the Streamlit frontend

subprocess.run(
    ["streamlit", "run", "frontend/app.py"],
    check=True
)

This approach ensures the backend is running before the frontend attempts to connect via the HTTP client defined in frontend/utils/api.py.

Key Frontend Architecture Files

Understanding these files helps troubleshoot startup issues:

• frontend/app.py – Main entry point containing the main() function that wires together all UI components.
• frontend/frontend_config/settings.py – Loads FRONTEND_API_URL, FRONTEND_DEFAULT_DEBUG, and other environment variables.
• frontend/utils/api.py – HTTP client wrapper that respects the FRONTEND_API_URL setting when communicating with the backend.
• frontend/components/chat.py – Implements the chat interface that renders messages and handles streaming responses.

Summary

• The primary entry point for the Streamlit frontend is frontend/app.py, which contains the main() function orchestrating the UI.
• Launch the interface by running streamlit run frontend/app.py from the repository root, accessible by default at http://localhost:8501.
• Configure the backend connection using the FRONTEND_API_URL environment variable defined in frontend/frontend_config/settings.py.
• Enable debug mode by setting FRONTEND_DEFAULT_DEBUG=true to activate the two-column layout with the debug panel.
• For production deployments, use programmatic launch methods to manage both the FastAPI backend and Streamlit frontend processes.

Frequently Asked Questions

What port does the Graph-RAG Agent frontend use by default?

The Streamlit frontend starts on port 8501 by default (http://localhost:8501). This is Streamlit's default behavior and can be changed using Streamlit's command-line flags, such as streamlit run frontend/app.py --server.port 8502.

Why does the frontend fail to connect to the backend?

The frontend attempts to reach the FastAPI backend at the URL specified by FRONTEND_API_URL (default: http://localhost:8000). If the backend isn't running on that address, the HTTP client in frontend/utils/api.py will throw connection errors. Ensure you've started the backend with python server/main.py and that the FRONTEND_API_URL environment variable matches your backend's actual address.

Can I run the frontend without the debug panel?

Yes. The debug panel only appears when debug_mode is enabled in the session state. By default, this is controlled by the FRONTEND_DEFAULT_DEBUG environment variable (set to false by default). Running streamlit run frontend/app.py without setting this variable starts the normal single-column chat interface via display_chat_interface.

How do I customize the default agent shown in the UI?

The default agent selection is configured through environment variables loaded by frontend/frontend_config/settings.py. Set the appropriate FRONTEND_ variables in your .env file or export them before starting the application. The init_session_state function in frontend/app.py reads these values to initialize the session state on startup.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}