✨ Agent runtime isolation Step1: Service decomposition based on Docker #606

Author: Phinease

backend/apps/agent_app.py

@@ -22,12 +22,13 @@
 # Import monitoring utilities
 from utils.monitoring import monitoring_manager
 
-router = APIRouter(prefix="/agent")
+agent_runtime_router = APIRouter(prefix="/agent")
+agent_config_router = APIRouter(prefix="/agent")
 logger = logging.getLogger("agent_app")
 
 
 # Define API route
-@router.post("/run")
+@agent_runtime_router.post("/run")
 @monitoring_manager.monitor_endpoint("agent.run", exclude_params=["authorization"])
 async def agent_run_api(agent_request: AgentRequest, http_request: Request, authorization: str = Header(None)):
     """
@@ -45,7 +46,7 @@ async def agent_run_api(agent_request: AgentRequest, http_request: Request, auth
             status_code=HTTPStatus.INTERNAL_SERVER_ERROR, detail="Agent run error.")
 
 
-@router.get("/stop/{conversation_id}")
+@agent_runtime_router.get("/stop/{conversation_id}")
 async def agent_stop_api(conversation_id: int, authorization: Optional[str] = Header(None)):
     """
     stop agent run and preprocess tasks for specified conversation_id
@@ -58,7 +59,7 @@ async def agent_stop_api(conversation_id: int, authorization: Optional[str] = He
                             detail=f"no running agent or preprocess tasks found for conversation_id {conversation_id}")
 
 
-@router.post("/search_info")
+@agent_config_router.post("/search_info")
 async def search_agent_info_api(agent_id: int = Body(...), authorization: Optional[str] = Header(None)):
     """
     Search agent info by agent_id
@@ -72,7 +73,7 @@ async def search_agent_info_api(agent_id: int = Body(...), authorization: Option
             status_code=HTTPStatus.INTERNAL_SERVER_ERROR, detail="Agent search info error.")
 
 
-@router.get("/get_creating_sub_agent_id")
+@agent_config_router.get("/get_creating_sub_agent_id")
 async def get_creating_sub_agent_info_api(authorization: Optional[str] = Header(None)):
     """
     Create a new sub agent, return agent_ID
@@ -85,7 +86,7 @@ async def get_creating_sub_agent_info_api(authorization: Optional[str] = Header(
             status_code=HTTPStatus.INTERNAL_SERVER_ERROR, detail="Agent create error.")
 
 
-@router.post("/update")
+@agent_config_router.post("/update")
 async def update_agent_info_api(request: AgentInfoRequest, authorization: Optional[str] = Header(None)):
     """
     Update an existing agent
@@ -99,7 +100,7 @@ async def update_agent_info_api(request: AgentInfoRequest, authorization: Option
             status_code=HTTPStatus.INTERNAL_SERVER_ERROR, detail="Agent update error.")
 
 
-@router.delete("")
+@agent_config_router.delete("")
 async def delete_agent_api(request: AgentIDRequest, authorization: Optional[str] = Header(None)):
     """
     Delete an agent
@@ -113,7 +114,7 @@ async def delete_agent_api(request: AgentIDRequest, authorization: Optional[str]
             status_code=HTTPStatus.INTERNAL_SERVER_ERROR, detail="Agent delete error.")
 
 
-@router.post("/export")
+@agent_config_router.post("/export")
 async def export_agent_api(request: AgentIDRequest, authorization: Optional[str] = Header(None)):
     """
     export an agent
@@ -127,7 +128,7 @@ async def export_agent_api(request: AgentIDRequest, authorization: Optional[str]
             status_code=HTTPStatus.INTERNAL_SERVER_ERROR, detail="Agent export error.")
 
 
-@router.post("/import")
+@agent_config_router.post("/import")
 async def import_agent_api(request: AgentImportRequest, authorization: Optional[str] = Header(None)):
     """
     import an agent
@@ -141,7 +142,7 @@ async def import_agent_api(request: AgentImportRequest, authorization: Optional[
             status_code=HTTPStatus.INTERNAL_SERVER_ERROR, detail="Agent import error.")
 
 
-@router.get("/list")
+@agent_config_router.get("/list")
 async def list_all_agent_info_api(authorization: Optional[str] = Header(None), request: Request = None):
     """
     list all agent info
@@ -155,7 +156,7 @@ async def list_all_agent_info_api(authorization: Optional[str] = Header(None), r
             status_code=HTTPStatus.INTERNAL_SERVER_ERROR, detail="Agent list error.")
 
 
-@router.get("/call_relationship/{agent_id}")
+@agent_config_router.get("/call_relationship/{agent_id}")
 async def get_agent_call_relationship_api(agent_id: int, authorization: Optional[str] = Header(None)):
     """
     Get agent call relationship tree including tools and sub-agents

backend/apps/base_app.py backend/apps/config_app.pybackend/apps/base_app.py renamed to backend/apps/config_app.py

@@ -4,14 +4,12 @@
 from fastapi.middleware.cors import CORSMiddleware
 from fastapi.responses import JSONResponse
 
-from apps.agent_app import router as agent_router
+from apps.agent_app import agent_config_router as agent_router
 from apps.config_sync_app import router as config_sync_router
-from apps.conversation_management_app import router as conversation_management_router
 from apps.elasticsearch_app import router as elasticsearch_router
-from apps.file_management_app import router as file_manager_router
+from apps.file_management_app import file_management_config_router as file_manager_router
 from apps.image_app import router as proxy_router
 from apps.knowledge_summary_app import router as summary_router
-from apps.memory_config_app import router as memory_router
 from apps.me_model_managment_app import router as me_model_manager_router
 from apps.mock_user_management_app import router as mock_user_management_router
 from apps.model_managment_app import router as model_manager_router
@@ -20,7 +18,7 @@
 from apps.tenant_config_app import router as tenant_config_router
 from apps.tool_config_app import router as tool_config_router
 from apps.user_management_app import router as user_management_router
-from apps.voice_app import router as voice_router
+from apps.voice_app import voice_config_router as voice_router
 from consts.const import IS_SPEED_MODE
 
 # Import monitoring utilities
@@ -41,10 +39,8 @@
 
 app.include_router(me_model_manager_router)
 app.include_router(model_manager_router)
-app.include_router(memory_router)
 app.include_router(config_sync_router)
 app.include_router(agent_router)
-app.include_router(conversation_management_router)
 app.include_router(elasticsearch_router)
 app.include_router(voice_router)
 app.include_router(file_manager_router)

backend/apps/file_management_app.py

@@ -16,19 +16,20 @@
 logger = logging.getLogger("file_management_app")
 
 # Create API router
-router = APIRouter(prefix="/file")
+file_management_runtime_router = APIRouter(prefix="/file")
+file_management_config_router = APIRouter(prefix="/file")
 
 
 # Handle preflight requests
-@router.options("/{full_path:path}")
+@file_management_config_router.options("/{full_path:path}")
 async def options_route(full_path: str):
     return JSONResponse(
         status_code=HTTPStatus.OK,
         content={"detail": "OK"},
     )
 
 
-@router.post("/upload")
+@file_management_config_router.post("/upload")
 async def upload_files(
         file: List[UploadFile] = File(..., alias="file"),
         destination: str = Form(...,
@@ -59,7 +60,7 @@ async def upload_files(
                             detail="No valid files uploaded")
 
 
-@router.post("/process")
+@file_management_config_router.post("/process")
 async def process_files(
         files: List[dict] = Body(
             ..., description="List of file details to process, including path_or_url and filename"),
@@ -100,7 +101,7 @@ async def process_files(
     )
 
 
-@router.post("/storage")
+@file_management_runtime_router.post("/storage")
 async def storage_upload_files(
     files: List[UploadFile] = File(..., description="List of files to upload"),
     folder: str = Form(
@@ -125,7 +126,7 @@ async def storage_upload_files(
     }
 
 
-@router.get("/storage")
+@file_management_config_router.get("/storage")
 async def get_storage_files(
     prefix: str = Query("", description="File prefix filter"),
     limit: int = Query(100, description="Maximum number of files to return"),
@@ -160,7 +161,7 @@ async def get_storage_files(
         )
 
 
-@router.get("/storage/{path}/{object_name}")
+@file_management_config_router.get("/storage/{path}/{object_name}")
 async def get_storage_file(
     object_name: str = PathParam(..., description="File object name"),
     download: str = Query("ignore", description="How to get the file"),
@@ -200,7 +201,7 @@ async def get_storage_file(
         )
 
 
-@router.delete("/storage/{object_name:path}")
+@file_management_config_router.delete("/storage/{object_name:path}")
 async def remove_storage_file(
     object_name: str = PathParam(..., description="File object name to delete")
 ):
@@ -224,7 +225,7 @@ async def remove_storage_file(
         )
 
 
-@router.post("/storage/batch-urls")
+@file_management_config_router.post("/storage/batch-urls")
 async def get_storage_file_batch_urls(
     request_data: dict = Body(...,
                               description="JSON containing list of file object names"),
@@ -272,7 +273,7 @@ async def get_storage_file_batch_urls(
     }
 
 
-@router.post("/preprocess")
+@file_management_runtime_router.post("/preprocess")
 async def agent_preprocess_api(
         request: Request, query: str = Form(...),
         files: List[UploadFile] = File(...),

backend/apps/runtime_app.py

@@ -0,0 +1,58 @@
+import logging
+
+from fastapi import FastAPI, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+
+from apps.agent_app import agent_runtime_router as agent_router
+from apps.voice_app import voice_runtime_router as voice_router
+from apps.conversation_management_app import router as conversation_management_router
+from apps.memory_config_app import router as memory_config_router
+from apps.file_management_app import file_management_runtime_router as file_management_router
+
+# Import monitoring utilities
+from utils.monitoring import monitoring_manager
+
+# Create logger instance
+logger = logging.getLogger("runtime_app")
+app = FastAPI(root_path="/api")
+
+# Add CORS middleware
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+app.include_router(agent_router)
+app.include_router(conversation_management_router)
+app.include_router(memory_config_router)
+app.include_router(file_management_router)
+app.include_router(voice_router)
+
+# Initialize monitoring for the application
+monitoring_manager.setup_fastapi_app(app)
+
+
+# Global exception handler for HTTP exceptions
+@app.exception_handler(HTTPException)
+async def http_exception_handler(request, exc):
+    logger.error(f"HTTPException: {exc.detail}")
+    return JSONResponse(
+        status_code=exc.status_code,
+        content={"message": exc.detail},
+    )
+
+
+# Global exception handler for all uncaught exceptions
+@app.exception_handler(Exception)
+async def generic_exception_handler(request, exc):
+    logger.error(f"Generic Exception: {exc}")
+    return JSONResponse(
+        status_code=500,
+        content={"message": "Internal server error, please try again later."},
+    )
+
+

backend/apps/voice_app.py

@@ -16,10 +16,11 @@
 
 logger = logging.getLogger("voice_app")
 
-router = APIRouter(prefix="/voice")
+voice_runtime_router = APIRouter(prefix="/voice")
+voice_config_router = APIRouter(prefix="/voice")
 
 
-@router.websocket("/stt/ws")
+@voice_runtime_router.websocket("/stt/ws")
 async def stt_websocket(websocket: WebSocket):
     """WebSocket endpoint for real-time audio streaming and STT"""
     logger.info("STT WebSocket connection attempt...")
@@ -39,7 +40,7 @@ async def stt_websocket(websocket: WebSocket):
         logger.info("STT WebSocket connection closed")
 
 
-@router.websocket("/tts/ws")
+@voice_runtime_router.websocket("/tts/ws")
 async def tts_websocket(websocket: WebSocket):
     """WebSocket endpoint for streaming TTS"""
     logger.info("TTS WebSocket connection attempt...")
@@ -73,7 +74,7 @@ async def tts_websocket(websocket: WebSocket):
             await websocket.close()
 
 
-@router.post("/connectivity")
+@voice_config_router.post("/connectivity")
 async def check_voice_connectivity(request: VoiceConnectivityRequest):
     """
     Check voice service connectivity

backend/main_service.py backend/config_service.pybackend/main_service.py renamed to backend/config_service.py

@@ -10,7 +10,7 @@
 from dotenv import load_dotenv
 load_dotenv()
 
-from apps.base_app import app
+from apps.config_app import app
 from utils.logging_utils import configure_logging, configure_elasticsearch_logging
 from services.tool_configuration_service import initialize_tools_on_startup
 

backend/runtime_service.py

@@ -0,0 +1,42 @@
+import uvicorn
+import logging
+import warnings
+import asyncio
+
+from consts.const import APP_VERSION
+
+warnings.filterwarnings("ignore", category=UserWarning)
+
+from dotenv import load_dotenv
+load_dotenv()
+
+from apps.runtime_app import app
+from utils.logging_utils import configure_logging, configure_elasticsearch_logging
+from services.tool_configuration_service import initialize_tools_on_startup
+
+configure_logging(logging.INFO)
+configure_elasticsearch_logging()
+logger = logging.getLogger("runtime_service")
+
+
+async def startup_initialization():
+    """
+    Perform initialization tasks during server startup
+    """
+    logger.info("Starting server initialization...")
+    logger.info(f"APP version is: {APP_VERSION}")
+    try:
+        # Initialize tools on startup - service layer handles detailed logging
+        await initialize_tools_on_startup()
+        logger.info("Server initialization completed successfully!")
+    except Exception as e:
+        logger.error(f"Server initialization failed: {str(e)}")
+        # Don't raise the exception to allow server to start even if initialization fails
+        logger.warning("Server will continue to start despite initialization issues")
+
+
+if __name__ == "__main__":
+    asyncio.run(startup_initialization())
+    uvicorn.run(app, host="0.0.0.0", port=5014, log_level="info")
+
+

doc/docs/en/backend/overview.md

@@ -179,8 +179,9 @@ uv sync && uv pip install -e ../sdk
 ### Service Startup
 ```bash
 python backend/data_process_service.py   # Data processing service
-python backend/main_service.py           # Main service
-python backend/nexent_mcp_service.py     # MCP service
+python backend/config_service.py         # Config service
+python backend/runtime_service.py        # Runtime service
+python backend/mcp_service.py            # MCP service
 ```
 
 ## Performance and Scalability

doc/docs/en/backend/tools/mcp.md

@@ -144,14 +144,15 @@ DELETE /remote-proxies?service_name={service_name}
 **Start Main Service**
 ```bash
 cd backend
-python main_service.py
+python config_service.py
+python runtime_service.py
 ```
 Service will start at `http://localhost:5010`.
 
 **Start MCP Service**
 ```bash
 cd backend
-python nexent_mcp_service.py
+python mcp_service.py
 ```
 Service will start at `http://localhost:5011`.