# How to Start the FastAPI Backend Service for the Graph-RAG Agent

> Start your FastAPI backend service for the Graph-RAG Agent by running uvicorn server main app --reload. Get your project running quickly and efficiently.

- Repository: [GLK/graph-rag-agent](https://github.com/1517005260/graph-rag-agent)
- Tags: how-to-guide
- Published: 2026-02-23

---

**Run `uvicorn server.main:app --reload` from the project root after installing dependencies and configuring your `.env` file.**

The **FastAPI backend service** powers the core API layer of the Graph-RAG agent in the `1517005260/graph-rag-agent` repository. This service handles conversational queries, knowledge graph operations, and feedback collection through a modular router architecture defined in the `server/` package.

## Prerequisites and Environment Setup

Before starting the FastAPI backend service, ensure you have **Python 3.10 or newer** installed. The project relies on specific package versions defined in [`requirements.txt`](https://github.com/1517005260/graph-rag-agent/blob/main/requirements.txt), including FastAPI and Uvicorn.

Create and activate a virtual environment to isolate dependencies:

```bash
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

pip install -r requirements.txt

```

## Configuration and Environment Variables

The backend requires external service credentials and connection strings. These are managed through environment variables loaded by [`server/server_config/settings.py`](https://github.com/1517005260/graph-rag-agent/blob/main/server/server_config/settings.py).

Create your environment file from the example:

```bash
cp .env.example .env

```

Edit `.env` to include:
- **Neo4j connection details**: `NEO4J_URI`, `NEO4J_USER`, `NEO4J_PASSWORD`
- **LLM API keys**: `OPENAI_API_KEY` or other provider credentials referenced in the settings module

The [`server/server_config/database.py`](https://github.com/1517005260/graph-rag-agent/blob/main/server/server_config/database.py) file reads these values to initialize the Neo4j driver, while [`server/main.py`](https://github.com/1517005260/graph-rag-agent/blob/main/server/main.py) imports the settings to configure the FastAPI application instance.

## Launching the FastAPI Service

Start the backend using **Uvicorn**, the ASGI server recommended for FastAPI applications. Run this command from the project root directory:

```bash
uvicorn server.main:app --reload

```

This command:
- Targets `server.main:app`, which points to the FastAPI instance created in [`server/main.py`](https://github.com/1517005260/graph-rag-agent/blob/main/server/main.py)
- Enables `--reload` for hot-reloading during development (code changes reflect immediately without restart)

For production deployments or specific network configurations, specify host and port:

```bash
uvicorn server.main:app --host 0.0.0.0 --port 8000

```

## Verifying the Installation

Once running, the FastAPI backend exposes interactive API documentation at:
- **Swagger UI**: `http://localhost:8000/docs`
- **ReDoc**: `http://localhost:8000/redoc`

The service includes several modular routers defined in [`server/main.py`](https://github.com/1517005260/graph-rag-agent/blob/main/server/main.py):
- [`server/routers/chat.py`](https://github.com/1517005260/graph-rag-agent/blob/main/server/routers/chat.py) handles conversational endpoints
- [`server/routers/knowledge_graph.py`](https://github.com/1517005260/graph-rag-agent/blob/main/server/routers/knowledge_graph.py) manages graph CRUD operations and queries
- Additional routers handle source management and feedback collection

Test the health of the Neo4j connection by invoking the knowledge graph endpoints through the Swagger UI, which validates that [`server/server_config/database.py`](https://github.com/1517005260/graph-rag-agent/blob/main/server/server_config/database.py) successfully connected to your configured Neo4j instance.

## Summary

- **Entry point**: The FastAPI application is defined in [`server/main.py`](https://github.com/1517005260/graph-rag-agent/blob/main/server/main.py) and exposed via `server.main:app`
- **Dependencies**: Install from [`requirements.txt`](https://github.com/1517005260/graph-rag-agent/blob/main/requirements.txt) with Python 3.10+
- **Configuration**: Populate `.env` with Neo4j and LLM credentials for [`server/server_config/settings.py`](https://github.com/1517005260/graph-rag-agent/blob/main/server/server_config/settings.py)
- **Launch command**: `uvicorn server.main:app --reload` for development
- **Verification**: Access `/docs` or `/redoc` to confirm the service is operational

## Frequently Asked Questions

### What Python version is required to run the FastAPI backend?

The Graph-RAG agent requires **Python 3.10 or newer**. This ensures compatibility with the type hints and async features used throughout the `server/` package, particularly in [`server/main.py`](https://github.com/1517005260/graph-rag-agent/blob/main/server/main.py) and the router modules.

### Where does the FastAPI application load its configuration?

Configuration is loaded from environment variables via [`server/server_config/settings.py`](https://github.com/1517005260/graph-rag-agent/blob/main/server/server_config/settings.py). You must create a `.env` file in the project root containing values for `NEO4J_URI`, `NEO4J_USER`, `NEO4J_PASSWORD`, and your LLM API keys. The [`server/server_config/database.py`](https://github.com/1517005260/graph-rag-agent/blob/main/server/server_config/database.py) module uses these settings to initialize the Neo4j driver.

### How do I enable hot-reloading during development?

Add the `--reload` flag to your Uvicorn command: `uvicorn server.main:app --reload`. This monitors the `server/` directory for changes and automatically restarts the service, which is essential when modifying routers in [`server/routers/chat.py`](https://github.com/1517005260/graph-rag-agent/blob/main/server/routers/chat.py) or [`server/routers/knowledge_graph.py`](https://github.com/1517005260/graph-rag-agent/blob/main/server/routers/knowledge_graph.py) during active development.

### Can I run the backend on a specific port or bind to all network interfaces?

Yes. By default, Uvicorn binds to `127.0.0.1:8000`. To expose the service on all interfaces (necessary for Docker containers or remote access), use `uvicorn server.main:app --host 0.0.0.0 --port 8000`. Adjust the port number as needed for your deployment environment.