feat: overhaul chat architecture with persistent JdbcChatMemory, reactive UI components, and improved conversation management
This commit is contained in:
91
context-agent.md
Normal file
91
context-agent.md
Normal file
@@ -0,0 +1,91 @@
|
||||
---
|
||||
trigger: always_on
|
||||
---
|
||||
|
||||
# Application Context: `loyalty-agent`
|
||||
|
||||
Application Name: **Loyalty Agent Service**
|
||||
Module Path: `loyalty-agent/`
|
||||
Runtime Port: `9332`
|
||||
Technology Stack: Java 25, Spring Boot 4.x, Spring AI 2.x, Spring WebSocket (STOMP), Ollama, Spring AI MCP Client
|
||||
|
||||
---
|
||||
|
||||
## 1. Primary Roles & Responsibilities
|
||||
|
||||
`loyalty-agent` acts as the **BFF (Backend-For-Frontend)** and **AI Orchestration Layer**:
|
||||
- **BFF & WebSocket Server**: Manages WebSocket/STOMP connections with the Frontend (`src/`), receiving chat requests and streaming LLM responses back to the UI in real time.
|
||||
- **AI Orchestrator**: Interacts with the Ollama LLM (`qwen3.5:4b`) via Spring AI `ChatClient`, routing user queries, managing prompt templates, and handling conversation state.
|
||||
- **MCP Client**: Connects to `loyalty-mcp-server` via the MCP SSE protocol (`http://localhost:9331/sse`) to dynamically load and invoke loyalty business tools.
|
||||
- **REST Proxy & Persistence**: Exposes REST endpoints to the Frontend for proxy data queries (Campaigns, Rules) and conversation history management.
|
||||
|
||||
---
|
||||
|
||||
## 2. Protocol & Real-time Chat Messaging Flow (WebSocket STOMP)
|
||||
|
||||
### WebSocket Configuration (`config/WebSocketConfig.java`)
|
||||
- **STOMP Endpoint**: `/ws` (Supports SockJS fallback)
|
||||
- **Application Destination Prefix**: `/app`
|
||||
- **User Destination Prefix**: `/user`
|
||||
- **Broker Prefixes**: `/topic`, `/queue`
|
||||
|
||||
### Messaging Flow
|
||||
1. **Client Request**: Frontend sends a message to `/app/chat` with payload `{ content: string, conversationId: string }`.
|
||||
2. **Server Processing**: `AgentController` receives the message and delegates it to `LoyaltyAgentService`, which processes it via Spring AI `ChatClient`.
|
||||
3. **Event Streaming**: The server pushes events (`AgentEvent`) back to the client on `/user/queue/chat-events`.
|
||||
|
||||
### Event Types Sent to UI (`AgentEvent` Types)
|
||||
- **`TOKEN`**: Text stream chunks returned in real time from the LLM. The UI appends these chunks sequentially for a typing effect.
|
||||
- **`TOOL_STATUS`**: Status update when executing a tool (tool name, status `RUNNING` / `COMPLETED` / `FAILED`, arguments/results). The UI renders an animated indicator badge.
|
||||
- **`DONE`**: Signals that the LLM has finished responding to the current request.
|
||||
- **`ERROR`**: Signals system errors or failure during LLM/Tool execution.
|
||||
|
||||
---
|
||||
|
||||
## 3. AI & Environment Configuration (`application.yml` & `config/`)
|
||||
|
||||
- **Ollama LLM Provider**:
|
||||
- Base URL: `http://192.168.99.10:11434`
|
||||
- Model: `qwen3.5:4b`
|
||||
- **MCP Server Connection**:
|
||||
- URL: `${MCP_SERVER_URL:http://localhost:9331/sse}`
|
||||
- Transport: SSE (Server-Sent Events)
|
||||
- **Loyalty Core Integration**:
|
||||
- Base URL: `${LOYALTY_CORE_BASE_URL:http://192.168.99.242:8081}`
|
||||
- Authentication: Keycloak OAuth2 Client Credentials (`KEYCLOAK_TOKEN_URI`, `KEYCLOAK_CLIENT_SECRET`)
|
||||
|
||||
---
|
||||
|
||||
## 4. Source Code Architecture
|
||||
|
||||
```
|
||||
dev.sonpx.loyalty.agent/
|
||||
├── LoyaltyAgentApplication.java
|
||||
├── config/
|
||||
│ ├── AgentConfig.java # RestClient & OAuth2 configuration for Core API
|
||||
│ ├── WebSocketConfig.java # STOMP WebSocket endpoints configuration
|
||||
│ └── McpConfig.java # Spring AI MCP Client setup
|
||||
├── controller/
|
||||
│ ├── AgentController.java # STOMP @MessageMapping("/chat") & Proxy REST APIs
|
||||
│ └── ConversationController.java # REST APIs for conversation history & messages
|
||||
├── service/
|
||||
│ ├── LoyaltyAgentService.java # Core service building ChatClient & streaming LLM output
|
||||
│ ├── AgentEventPublisher.java # Helper to send AgentEvent via SimpMessagingTemplate
|
||||
│ ├── ToolResultPresentationProcessor.java # Formats presentation content from tools
|
||||
│ └── AgentPersistenceService.java # Conversation & message persistence
|
||||
└── core/
|
||||
├── classifier/ # Intent classification logic
|
||||
├── executor/ # Plan and tool execution drivers
|
||||
├── memory/ # Conversation memory management
|
||||
├── orchestrator/ # Agent execution flow coordination
|
||||
└── workflow/ # Step-by-step workflow definitions
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Key Development Guidelines for Agents
|
||||
|
||||
1. **Preserve STOMP Contract**: Do not alter `/app/chat` or `/user/queue/chat-events` unless coordinated with the Frontend.
|
||||
2. **Propagate Conversation Context**: Ensure `conversationId` is passed consistently from WebSocket requests down to storage and MCP tool execution.
|
||||
3. **Handle Presentation Content**: When tools return payload with `presentation.content`, ensure the processor preserves the raw Markdown for the LLM to present to the user.
|
||||
4. **Ports & Env Vars**: Always target port `9332` for the Agent Service and respect standard environment variables for external endpoints.
|
||||
Reference in New Issue
Block a user