Content
# Tool List
> Self-developed AI Agent framework · ReAct mode + Agentic RAG + MCP protocol extension + Multi-Agent workflow (StateGraph) orchestration
## Project Introduction
A full-stack AI intelligent agent system that implements a complete technical stack from the bottom up: **dialogue memory → structured output → RAG knowledge enhancement → tool calling → MCP protocol → ReAct intelligent agent → multi-agent graph orchestration**. All core mechanisms of the agent (loop control, tool execution, state management, streaming push) are implemented independently, without relying on the framework's built-in automation.
## Core Capabilities
| Dimension | Capability | Technical Implementation |
| --- | --- | --- |
| **Agent Framework** | Self-developed ReAct Agent framework | Four-layer inheritance (BaseAgent → ReActAgent → ToolCallAgent → ZhouManus), state machine (IDLE→RUNNING→FINISHED/ERROR), manual tool call control, Terminate active termination + maxSteps safeguard |
| **RAG Pipeline** | Agentic RAG retrieval generation | LLM routing decision + hybrid search (Hybrid Search: vector PGVector + keyword ILIKE) + multi-round reflection loop + safeguard direct answer |
| **MCP Protocol** | Dynamic tool extension at runtime | MCP protocol-based SSE/stdio dual-mode hot swap, WatchService configuration file hot loading, REST API runtime registration |
| **Multi-Agent Workflow** | Graph directed graph orchestration | StateGraph-based 7-node condition routing, Flux.concat() + Flux.defer() implementation of true node-by-node SSE push, NonTransientAiException downgrade fault tolerance |
| **Streaming Architecture** | Multi-scheme comparison in the same project | Flux / SseEmitter / ServerSentEvent multiple implementations |
| **Observability** | Local deployment Langfuse3 full-chain tracking | OpenTelemetry OTLP protocol native docking, Span-level record Agent thinking-action-result full process |
## Project Structure
| Directory | Technology Stack | Description |
| --- | --- | --- |
| `src/` | Spring Boot 3.4 + Spring AI | Backend main application (intelligent agent, RAG, tool, API) |
| `zhou-ai-agent-frontend/` | Vue 3 + Vite + TypeScript | Chat interface frontend (dual-mode dialogue interface) |
| `zhou-image-search-mcp-server/` | Spring Boot 3.4 + MCP Server | Image search MCP service (Pexels API) |
## Technology Stack
**Backend**
- Java 21, Spring Boot 3.4.4, Spring AI 1.0.0
- Spring AI Alibaba + DashScope (Tongyi Qianwen Qwen)
- **StateGraph** (multi-agent workflow orchestration engine, condition routing + state management)
- **ReactAgent** (Alibaba Cloud Graph React proxy framework, ReAct mode)
- PGVector (PostgreSQL vector database)
- Knife4j / OpenAPI 3 (API documentation)
- iTextPDF, Jsoup, Hutool, Kryo
- Micrometer Tracing + OpenTelemetry (observability)
- Langfuse (AI observability platform)
**Frontend**
- Vue 3.5, TypeScript, Vite 6
- Vue Router 4, Axios
**MCP Server**
- Spring Boot 3.4.5, Spring AI MCP Server
- Pexels API (image search)
**Infrastructure**
- Docker Compose (one-click startup Langfuse + PostgreSQL)
- PostgreSQL + pgvector (vector storage + memory persistence)
## Quick Start
### Environment Requirements
- JDK 21
- Node.js 18+
- PostgreSQL (optional, for PGVector persistence vector storage)
- Maven 3.9+
### 1. Configure API Key
Before starting, you need to configure the following API Keys:
| Configuration Item | File Location | Description |
| --- | --- | --- |
| `spring.ai.dashscope.api-key` | `src/main/resources/application.yaml` | Alibaba Cloud DashScope API Key (Tongyi Qianwen model) |
| `search-api.api-key` | `src/main/resources/application.yaml` | SearchAPI.io API Key (web search function) |
| `AMAP_MAPS_API_KEY` | `src/main/resources/mcp-servers.json` | Amap MCP Server API Key |
| Pexels API Key | `zhou-image-search-mcp-server/src/main/resources/application.yaml` | Image search MCP Server Pexels API Key |
### 2. Start Backend
```bash
# After configuring the API Key
mvn spring-boot:run
# Backend runs at http://localhost:8123/api
```
### 3. Start Frontend
```bash
cd zhou-ai-agent-frontend
npm install
npm run dev
# Frontend runs at http://localhost:5173, automatically proxying /api to backend 8123 port
```
### 4. Start MCP Server (optional)
```bash
cd zhou-image-search-mcp-server
# Configure Pexels API Key
mvn spring-boot:run
# MCP Server runs at http://localhost:8127
```
## API Interface
| Interface | Method | Description |
| --- | --- | --- |
| `/api/ai/love_app/chat/sync` | GET | Synchronous dialogue (AI emotional master) |
| `/api/ai/love_app/chat/sse` | GET | SSE streaming dialogue (Flux mode) |
| `/api/ai/love_app/chat/server_sent_event` | GET | SSE streaming dialogue (ServerSentEvent packaging) |
| `/api/ai/love_app/chat/sse_emitter` | GET | SSE streaming dialogue (SseEmitter mode) |
| `/api/ai/manus/chat` | GET | Intelligent agent streaming dialogue (ZhouManus, SseEmitter) |
| `/api/ai/manus/chat/flux` | GET | Intelligent agent streaming dialogue (ZhouManus, Flux recommended) |
| `/api/mcp/servers` | GET | List all registered MCP Servers |
| `/api/mcp/servers` | POST | Register new MCP Server |
| `/api/mcp/servers/{name}` | DELETE | Remove MCP Server |
| `/api/mcp/servers/refresh` | POST | Reload MCP Server from configuration file |
| `/api/mcp/servers/tools` | GET | List all available tools |
| `/engine/agent/decide/stream` | GET/POST | Investment decision streaming interface (SSE, proxy to agent-decision-engine) |
| `/engine/agent/health` | GET | Decision engine health check |
| `/health` | GET | Health check |
| `/actuator` | GET | Spring Boot Actuator endpoint |
API documentation access: `http://localhost:8123/api/swagger-ui.html` (Knife4j)
Langfuse observability panel: `http://localhost:3000` (docker-compose startup)
## Intelligent Agent Architecture
ZhouManus adopts a four-layer inheritance architecture to implement the autonomous loop of "thinking → action":
```
┌─────────────────────────────────────────────┐
│ ZhouManus │
│ (specific intelligent agent, configuration prompt word and tool) │
├─────────────────────────────────────────────┤
│ ToolCallAgent │
│ think(): call LLM to determine if tool is needed │
│ act(): manually execute LLM-selected tool │
├─────────────────────────────────────────────┤
│ ReActAgent │
│ step() = think() + act() │
│ think-before-act loop mode │
├─────────────────────────────────────────────┤
│ BaseAgent │
│ Agent Loop: execute up to maxSteps steps │
│ State management: IDLE → RUNNING → FINISHED/ERROR │
│ Session memory: maintain messageList context │
└─────────────────────────────────────────────┘
```
**BaseAgent (base layer)** — responsible for "loop engine": define agent main loop, run up to 20 steps, manage state machine (idle → running → completed/error), maintain dialogue memory. Subclasses only need to implement the `step()` method to define what to do in each step.
**ReActAgent (inference layer)** — implement "think before act" mode: split `step()` into `think()` (thinking) and `act()` (action) abstract methods. This layer only defines execution order, not concerned with specific thinking or action.
**ToolCallAgent (tool layer)** — implement specific thinking and action: `think()` call LLM to let the large model judge which tools are needed; `act()` manually execute these tools (disabled Spring AI built-in automatic tool call, changed to manual control).
**ZhouManus (application layer)** — specific intelligent agent instance: configure system prompt words ("you are a full assistant"), access all tools, set maximum steps.
**Termination mechanism**: two ways to jump out of the loop — ① call `TerminateTool` (large model judgment task completed actively call); ② reach maximum steps 20 steps (safeguard protection, prevent infinite loop).
## Available Tool List
**Built-in tools** (`src/main/java/com/zhou/zhouaiagent/tools/`):
| Tool | Description |
| --- | --- |
| `TerminateTool` | Terminate intelligent agent execution, notify Agent task completed |
| `WebSearchTool` | Baidu web search (through SearchAPI.io, return top 5 results) |
| `WebScrapingTool` | Web content capture (based on Jsoup) |
| `FileOperationTool` | File read and write operation (operate `tmp/file/` directory) |
| `TerminalOperationTool` | Execute terminal/Shell command |
| `PDFGenerationTool` | Generate PDF document (iTextPDF, support Chinese font) |
| `ResourceDownloadTool` | Download resource file from URL (save to `tmp/download/`) |
**MCP extended tools**:
| Tool | Source | Description |
| --- | --- | --- |
| `searchImage` | Custom MCP Server | Search images through Pexels API (`zhou-image-search-mcp-server`) |
| `amap-maps` series tools | Amap MCP | Geographic encoding, path planning, POI search and other map services (`@amap/amap-maps-mcp-server`) |
## Docker Deployment
### Single Container Deployment
```bash
docker build -t zhou-ai-agent .
docker run -p 8123:8123 zhou-ai-agent
```
### Complete Environment (including Langfuse + PostgreSQL)
```bash
# Start all services (Langfuse + PostgreSQL + pgvector)
docker-compose up -d
# Service list:
# - Langfuse: http://localhost:3000 (observability panel)
# - PostgreSQL (Langfuse): localhost:5432
# - PostgreSQL (pgvector): localhost:5433
# Stop service
docker-compose down
```
## Core Module Details
### Memory Persistence (JDBC)
Based on `JdbcChatMemoryRepository` to achieve session memory persistence storage, service restart session not lost.
```
┌─────────────────────────────────────────────────┐
│ MessageWindowChatMemory │
│ Sliding window: retain recent 20 messages │
├─────────────────────────────────────────────────┤
│ JdbcChatMemoryRepository │
│ Storage: type + content + metadata three columns │
│ Serialization: Jackson JSON (avoid Kryo compatibility issue) │
├─────────────────────────────────────────────────┤
│ PostgreSQL + JDBC │
│ Automatic table creation, support multi-session isolation │
└─────────────────────────────────────────────────┘
```
### MCP Dynamic Tool Discovery and Hot Swap
Support dynamic addition/removal of MCP Server at runtime, no need to restart service. Automatically load all MCP Server configurations from `mcp-servers.json` at startup.
```
┌─────────────────────────────────────────────────┐
│ McpServerController │
│ REST API: POST/DELETE/GET /mcp/servers │
├─────────────────────────────────────────────────┤
│ McpToolRegistry │
│ @PostConstruct automatically load mcp-servers.json │
│ Support SSE and stdio two transmission modes │
│ ConcurrentHashMap manage all MCP Server connections │
├─────────────────────────────────────────────────┤
│ DynamicToolCallbackProvider │
│ Unified management: built-in tools + MCP tools + dynamic tools │
│ ZhouManus get complete tool list through this provider │
├─────────────────────────────────────────────────┤
│ McpConfigFileWatcher │
│ WatchService monitor mcp-servers.json file change │
│ Automatically refresh MCP Server connection when file modified │
└─────────────────────────────────────────────────┘
```
#### MCP Configuration Description (mcp-servers.json)
The configuration file is located at `src/main/resources/mcp-servers.json` and supports two modes:
**SSE Mode** — Connect to a standalone MCP Server (must be started separately):
```json
{
"mcpServers": {
"server-name": {
"url": "http://localhost:8127"
}
}
}
```
**stdio Mode** — Automatically start the MCP Server subprocess (communicate through stdin/stdout):
```json
{
"mcpServers": {
"server-name": {
"command": "java",
"args": [
"-Dspring.ai.mcp.server.stdio=true",
"-Dspring.main.web-application-type=none",
"-Dspring.main.banner-mode=off",
"-Dspring.main.log-startup-info=false",
"-Dlogging.level.root=WARN",
"-Dlogging.pattern.console=",
"-jar",
"/absolute/path/to/your-mcp-server.jar"
],
"env": {}
}
}
}
```
> **Important**: In stdio mode, the jar path must use an absolute path and must include the complete jar file. Using a relative path may cause the jar file to be not found due to different working directories. Also, you need to completely suppress Spring Boot's stdout output (banner, logs, etc.) through JVM parameters, otherwise, non-JSON content will pollute the MCP stdio protocol communication, leading to `MismatchedInputException` or connection timeout.
### Observability (Langfuse 3)
You can refer to the springai integration with langfuse3 example on [github](https://github.com/muxiaoming/langfuse3-official)
Native integration with Langfuse 3 through OpenTelemetry protocol, no Langfuse SDK dependency.
```
┌─────────────────────────────────────────────────┐
│ Langfuse 3 Panel │
│ Visualize Agent execution route, Token consumption, latency │
│ Display prompt/completion complete conversation content │
├─────────────────────────────────────────────────┤
│ OpenTelemetry OTLP Exporter │
│ OTLP/HTTP → Langfuse /api/public/otel │
├─────────────────────────────────────────────────┤
│ micrometer-tracing-bridge-otel │
│ Micrometer Observation → OTel Span bridge │
├─────────────────────────────────────────────────┤
│ ChatModelCompletionContentObservationFilter │
│ Inject gen_ai.prompt / gen_ai.completion │
├─────────────────────────────────────────────────┤
│ Spring AI Observation + @Observed annotation │
│ ChatModel.call() → spring_ai chat_client │
│ BaseAgent.run() → agent.run │
│ ToolCallAgent.think() → agent.think │
│ ToolCallAgent.act() → agent.act │
└─────────────────────────────────────────────────┘
```
### Agentic RAG
LLM as an agent for autonomous decision-making complete RAG Pipeline, integrating hybrid retrieval and multi-round reflection mechanism.
```
┌─────────────────────────────────────────────────┐
│ LLM Route Agent │
│ Autonomous judgment: RETRIEVE (retrieve) / DIRECT_ANSWER (direct answer)│
├─────────────────────────────────────────────────┤
│ RewriteQueryTransformer │
│ Query rewriting, optimizing retrieval words │
├─────────────────────────────────────────────────┤
│ HybridDocumentRetriever │
│ Vector retrieval: semantic similarity (PGVector COSINE) │
│ Keyword retrieval: ILIKE exact match (PostgreSQL native) │
│ Merge and deduplicate: LinkedHashMap deduplicate by ID │
├─────────────────────────────────────────────────┤
│ LLM Retrieval Evaluator │
│ Evaluate retrieval quality: SUFFICIENT / RE_RETRIEVE / GIVE_UP│
│ Multi-round reflection: up to 2 rounds, LLM generates improved retrieval words │
├─────────────────────────────────────────────────┤
│ Bottom-line strategy │
│ Retrieval is empty → LLM direct answer │
│ Retrieval has results → construct context → LLM answer based on material │
└─────────────────────────────────────────────────┘
```
### Flux Stream Processing
Unified use of `Flux<String>` to achieve thread-safe stream output.
```java
// BaseAgent.runStreamFlux() core implementation
Flux.create(sink -> {
Schedulers.boundedElastic().schedule(() -> {
for (int i = 0; i < maxSteps; i++) {
String stepResult = step();
sink.next("Step " + (i+1) + ": " + stepResult);
}
sink.complete();
});
}, FluxSink.OverflowStrategy.BUFFER);
```
### Investment Decision Engine Integration (agent-decision-engine)
The front-end integrates with an independent [agent-decision-engine](https://github.com/your-repo/agent-decision-engine) service, providing 7-node Multi-Agent Graph stream investment decision-making function.
```
┌────────────────────────────────────────────┐
│ zhou-ai-agent (Vue 3 front-end) │
│ DecisionEngineView.vue │
│ ├── decisionEngine.ts (axios) │
│ ├── decisionEngine-sync.ts (fetch SSE) │
│ └── decisionEngine-fixed.ts (POST SSE) │
├────────────────────────────────────────────┤
│ Vite proxy: /engine → localhost:8182/api │
├────────────────────────────────────────────┤
│ agent-decision-engine (back-end) │
│ MultiAgentInvestService │
│ ├── IntentClassifyAgent (intent classification) │
│ ├── ProblemPerceptionAgent (problem perception) │
│ ├── KnowledgeRetrievalAgent (knowledge retrieval) │
│ ├── DataFetchAgent (data acquisition) │
│ ├── ReasoningAnalysisAgent (reasoning analysis) │
│ ├── DecisionGenerateAgent (decision generation) │
│ └── GraphScheduleAgent (summary output) │
└────────────────────────────────────────────┘
```
**Decision-making process**: User input investment needs → Intent classification (non-investment direct return) → Problem perception → Knowledge retrieval (ReAct) → Data acquisition (ReAct) → Reasoning analysis → Decision generation → Summary output, 7 steps are pushed to the front-end through SSE stream.
## Screenshots
**DashScope Console**
**IDE Code View**
**IDE Debug View**
**Manus Intelligent Agent Front-end Interface**
**Langfuse3 Interface**
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available