How reagent-systems/simple-agent-websocket works
Project Type and Purpose
• This is an open-source, modular “thin” wrapper around the SimpleAgent Core, exposing its functionality over WebSockets and HTTP.
• It is not a full-stack application (no persistent database), but a server-side component plus a test client UI for real-time AI agent sessions.
• Purpose: DRY-compliant real-time interface, leveraging SimpleAgent Core via a Git submodule.
File Structure Analysis
• Top level:
• main.py (entry point)
• websocket_server.py (legacy wrapper)
• requirements.txt, Dockerfile, setup scripts
• SimpleAgent-Core (Git submodule)
• test_client_enhanced.html (client UI)
• websocket_server/ package:
• server.py (initializes Flask‐SocketIO server)
• routes.py (HTTP API endpoints)
• event_handlers.py (maps socket events → handlers)
• run_manager.py (enhances core RunManager with WebSockets)
• agent_wrapper.py (session & state management)
• core_loader.py (loads core library via submodule)
README Insights
• Confirms architecture: modular server package + submodule.
• Lists events, endpoints, tech stack (Flask-SocketIO, Python, git submodule).
• Emphasizes DRY, modularity, real-time updates, multi-session, no code duplication.
a. Main Components
1. Client Side:
• test_client_enhanced.html (Browser UI)
• (Any other socket.io clients)
2. WebSocket/HTTP Server:
• main.py → initializes server (Flask + SocketIO)
• websocket_server/server.py
• websocket_server/routes.py (HTTP endpoints: /health, /sessions, /version)
• websocket_server/event_handlers.py (socket event layer)
3. Session & Business Logic:
• websocket_server/agent_wrapper.py (session context, user inputs)
• websocket_server/run_manager.py (orchestrates step execution + emits events)
4. Core Library:
• SimpleAgent-Core (submodule) loaded via websocket_server/core_loader.py
5. External Services:
• AI provider API (OpenAI, LMStudio, Gemini) accessed by the core
6. Deployment/Infra:
• Docker container (Dockerfile, .dockerignore)
• Environment variables (.env in submodule)
b. Relationships & Data Flows
• Client → WebSocket (/socket.io/): run_agent, user_input, stop_agent → event_handlers
• event_handlers → run_manager / agent_wrapper → core_loader → SimpleAgent Core
• Core → run_manager emits assistant_message, step_start, tool_call back → event_handlers → Client
• HTTP calls (e.g., GET /health) → routes.py → server status
• main.py wires server, loads configuration, binds host/port
c. Architectural Patterns & Principles
• Layered architecture: Presentation (UI), Transport (WebSocket/HTTP), Application (event handlers & run manager), Core (agent engine)
• Modular package: single-responsibility modules, easy to extend
• DRY via git submodule: no code duplication of core
• Pub/Sub style event propagation: Flask-SocketIO events
d. Key Technologies
• Python 3.x
• Flask + Flask-SocketIO
• git submodule for SimpleAgent Core
• Socket.IO protocol (WebSocket fallback)
• HTML/JavaScript client
• Docker