# agent

**Repository Path**: jssbzg/agent

## Basic Information

- **Project Name**: agent
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-21
- **Last Updated**: 2026-01-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# IoT Sentinel - 工业物联网智能助手

## 项目简介
IoT Sentinel 是一个基于 Spring Boot 和 LangChain4j 构建的智能管理系统。它结合了大型语言模型 (LLM) 和工业物联网 (IIoT) 协议，允许用户通过自然语言与设备进行交互、监控设备状态状态并下达控制指令。

## 核心功能
- **自然语言交互**：通过 AI 代理理解并执行复杂的设备指令。
- **实时监控**：接收并处理来自 MQTT 代理的实时遥测数据。
- **设备控制**：向工业设备发送控制指令（如开启、关闭、设定阈值）。
- **持久化存储**：引入 PostgreSQL 数据库，用于存储设备元数据和所有的交互日志，用于审计和后续分析。

## 逻辑拓扑
以下是系统的核心逻辑拓扑结构：

```mermaid
graph TD
    User["用户 (Frontend/Chat)"] -- "提出问题/下令" --> Controller["AgentController"]
    Controller -- "发送消息" --> AgentService["AgentService"]
    
    subgraph AI_Engine [AI 引擎层]
        AgentService -- "处理对话" --> SentinelAgent["SentinelAgent (LangChain4j)"]
        SentinelAgent -- "调用工具" --> DeviceTools["DeviceTools"]
    end
    
    subgraph Data_Persistence [数据持久化层 - PostgreSQL]
        AgentService -- "审计日志" --> InteractionDB[("agent_interactions 表")]
        DeviceService -- "设备注册/元数据" --> MetadataDB[("device_metadata 表")]
        DeviceService -- "实时遥测记录" --> TelemetryDB[("telemetry_records 表")]
    end
    
    subgraph Device_Layer [设备交互层]
        DeviceTools -- "指令下达" --> DeviceControlService["DeviceControlService (MQTT Outbound)"]
        DeviceTools -- "状态查询" --> DeviceService["DeviceService (DB-Driven)"]
        MqttBroker -- "遥测上报" --> DeviceService
        DeviceControlService -- "发送指令" --> MqttBroker
    end
    
    MqttBroker <--> PhysicalDevices["物理/模拟设备"]
```

## 数据库设计逻辑说明
为了完善项目逻辑，我们引入了关系型数据库 PostgreSQL：

1. **`agent_interactions` 表**：
   - **目的**：记录每一次用户与 AI 的交互。
   - **作用**：这不仅是为了审计，更是为了将来可以分析用户的偏好，或者作为 RAG (检索增强生成) 的历史上下文。
   - **逻辑**：在 `AgentService` 处理完消息并获得回复后，将交互细节异步录入数据库。

2. **`device_metadata` 表**：
   - **目的**：维护设备的静态信息（名称、位置、描述）。
   - **作用**：MQTT 遥测通常只包含动态数值。通过数据库，我们可以为设备赋予物理意义，使得 AI 能够回答“一号车间的温度是多少”这类基于位置的问题。
   - **逻辑**：在 `DeviceService` 接收到新设备遥测时自动初始化记录。

3. **`telemetry_records` 表**：
   - **目的**：持久化存储所有收到的实时遥测点位。
   - **作用**：取代了不稳定的内存存储 (ConcurrentHashMap)。这使得系统即使重启，也能保留所有设备的历史运行轨迹，并支持 AI 分析历史趋势。
   - **逻辑**：每当 MQTT 监听器收到一条 JSON 消息，`DeviceService` 就会将其解析并插入此表。

## 配置要求
在 `application.properties` 中已配置如下数据库连接 (请确保 PostgreSQL 已运行)：

```properties
datasource:
    url: jdbc:postgresql://localhost:5432/ragdb
    username: postgres
    password: ${DB_PASSWORD:1425369}
    driver-class-name: org.postgresql.Driver
```

## 本地方法调用 (Tool Use) 实现原理

本项目利用 **LangChain4j** 的 AI Services 机制实现了大语言模型对本地 Java 方法的自动调度（即 Function Calling）。

### 核心代码实现

1. **接口定义 (`SentinelAgent`)**：
   通过 `@AiService` 注解将接口注册为 AI 服务。LLM 会根据接口中的 `SystemMessage` 提示词自动判断何时需要调用工具。

2. **工具类 (`DeviceTools`)**：
   在普通的 Spring Component 中，使用 `@Tool` 注解标注具体的方法。LangChain4j 启动时会扫描这些注解，并将方法签名（名称、参数、描述）转换成 LLM 可理解的 JSON Schema。
   ```java
   @Tool("查询系统中所有已知设备的列表")
   public String listAllDevices() { ... }
   ```

### 核心类拓扑结构 (Class Topology)

```mermaid
classDiagram
    class SentinelAgent {
        <<interface>>
        +chat(message) String
    }
    class DeviceTools {
        +getDeviceStatus(id) String
        +controlDevice(id, cmd) String
        +listAllDevices() String
    }
    class AgentService {
        -SentinelAgent agent
        +chat(msg) String
    }
    class LangChain4j_Runtime {
        <<Infrastructure>>
    }

    AgentService --> SentinelAgent : 调用入口
    SentinelAgent ..> LangChain4j_Runtime : 代理实现
    LangChain4j_Runtime --> DeviceTools : 自动发现与反射调用
    DeviceTools --> DeviceService : 业务逻辑
```

6. **最终回复**：LLM 结合执行结果，生成最终的自然语言回复。

## 如何查看原始提示词 (Raw Prompt)
如果您想查看发送给大模型的最终提示词（包括 System Message、工具定义以及用户输入），我们已经在 `application.properties` 中开启了请求日志：

1. **配置配置**：
   ```properties
   langchain4j.open-ai.chat-model.log-requests=true
   logging.level.dev.langchain4j=DEBUG
   ```
2. **查看方式**：
   启动应用后，在控制台日志中搜索 `Request:` 关键字。您将看到一个包含 `messages` 数组的 JSON 对象，其中 `content` 字段即为最终发送的提示词。

## 重要开发注释
在本项目代码中，我们采用了以下设计模式：
- **AI Service 模式**：通过 LangChain4j 的 `@AiService` 声明式定义 Agent，解耦了提示词 (Prompt) 逻辑。
- **自动发现逻辑**：在 `DeviceService` 中实现了自动注册，保证了系统在面对不可预知的大量 IoT 设备接入时的鲁棒性。
- **防崩溃设计**：数据库操作被 `try-catch` 包裹，确保即便数据库连接出现抖动，也不会导致核心的控制指令发送失败。