loyalty-agent-service/context-agent.md

trigger

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.