# agent

**Repository Path**: DZJ7777/agent

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-20
- **Last Updated**: 2026-03-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MAS 边行为异常检测系统

基于多智能体系统（MAS）的边（行为）异常检测实验框架，支持任务子图级别的实时异常检测。

## 项目概述

本项目实现了一个完整的多智能体系统异常检测框架，包括：

- **MAS 模拟器**：模拟智能体之间的交互行为
- **特征提取**：提取边（行为）的结构、语义、模型和时序特征
- **异常检测模型**：基于 LSTM + GNN + MLP 的混合检测架构
- **任务子图**：以任务为中心构建子图进行增量检测

## 架构设计

### 任务流程

```
用户输入 → Agent_A → Agent_B → ... → 用户输出
    ↓          ↓          ↓            ↓
   边0       边1        边2          边N
```

每个任务形成一个独立子图，包含完整的交互链路。

### 检测模型架构

```
输入: 边特征 [latency, entropy, semantic_sim]
           ↓
    ┌──────────────────────────────┐
    │   1. LSTM 时序特征提取        │
    │   维护节点历史行为序列         │
    └──────────────────────────────┘
           ↓
    ┌──────────────────────────────┐
    │   2. GNN 空间特征提取         │
    │   GCN 在任务子图上传播        │
    └──────────────────────────────┘
           ↓
    ┌──────────────────────────────┐
    │   3. 特征融合                 │
    │   concat(边特征, 时序, 空间)   │
    └──────────────────────────────┘
           ↓
    ┌──────────────────────────────┐
    │   4. MLP 分类器               │
    │   二分类: 正常/异常            │
    └──────────────────────────────┘
```

## 文件结构

```
agent/
├── mas_exp.py              # MAS 模拟与特征提取
├── model_exp.py            # 模型训练与推理
├── behavior_log.csv        # 实验数据记录
├── requirements.txt        # 依赖包
├── .env                    # API 配置文件
├── task_subgraph_detector.pt  # 训练好的模型
├── README.md               # 项目说明
└── data/
    ├── MMLU/               # MMLU 数据集
    │   ├── load.py         # 数据加载脚本
    │   └── test.jsonl      # 测试数据
    └── injectagent/        # 注入智能体数据
```

## 特征字段规范

### 字段定义

本系统严格规定以下字段，所有特征提取模块必须遵守此规范，**不得添加额外字段**。

#### 必需字段（9 个）

所有 CSV 数据文件必须包含以下 9 个字段，顺序和名称必须完全一致：

| 序号 | 字段名 | 类型 | 说明 | 示例值 |
|------|--------|------|------|--------|
| 1 | `task_id` | String | 任务唯一标识符 | `"task_001"` |
| 2 | `edge_id` | Integer | 边在任务中的序号（从 0 开始） | `0`, `1`, `2` |
| 3 | `src` | String | 源节点 ID | `"User"`, `"Agent_A"` |
| 4 | `dst` | String | 目标节点 ID | `"Agent_Analyst"` |
| 5 | `timestamp` | String | ISO 格式时间戳 | `"2024-01-15T10:30:45.123456"` |
| 6 | `latency` | Float | 交互时延（秒） | `12.5`, `45.3` |
| 7 | `entropy` | Float | Logits 熵值（模型不确定性） | `0.012`, `3.45` |
| 8 | `semantic_sim` | Float | 与 System Prompt 的余弦相似度 | `0.85`, `0.23` |
| 9 | `is_anomaly` | Integer | 异常标签（0=正常，1=异常） | `0`, `1` |

#### 字段分类

| 分类 | 字段 | 用途 |
|------|------|------|
| **结构特征** | `task_id`, `edge_id`, `src`, `dst`, `timestamp` | 构建任务子图、节点映射 |
| **时序特征** | `latency` | 检测响应时间异常 |
| **模型特征** | `entropy` | 检测模型决策不确定性异常 |
| **语义特征** | `semantic_sim` | 检测意图一致性异常 |
| **标签** | `is_anomaly` | Ground Truth，用于模型训练和评估 |

### CSV 文件格式要求

#### 1. 文件头（Header）

```csv
task_id,edge_id,src,dst,timestamp,latency,entropy,semantic_sim,is_anomaly
```

#### 2. 数据行示例

```csv
task_001,0,User,Agent_Analyst,2024-01-15T10:30:45.123456,12.5,0.012,0.85,0
task_001,1,Agent_Analyst,Agent_Reviewer,2024-01-15T10:30:58.234567,8.3,0.015,0.82,0
task_001,2,Agent_Reviewer,Agent_Critic,2024-01-15T10:31:06.345678,15.2,2.45,0.32,1
```

#### 3. 约束条件

- **字段数量**：必须且只能有 9 个字段
- **字段顺序**：必须按照上述定义顺序
- **字段名称**：必须完全一致（区分大小写）
- **数据类型**：必须符合上述类型定义
- **缺失值**：不允许缺失值，所有字段必须有值
- **编码格式**：UTF-8
- **分隔符**：逗号（`,`）

### 特征计算方法

#### 1. Logits 熵

```python
H = -Σ p(x) × log p(x)
```

从 LLM 输出的 logprobs 计算模型决策不确定性。

#### 2. 语义相似度

计算响应文本与 System Prompt 的余弦相似度，衡量意图一致性。

#### 3. 交互时延

记录从请求发送到响应接收的时间差。

## 快速开始

### 1. 安装依赖

```bash
pip install -r requirements.txt
```

### 2. 配置 API

创建 `.env` 文件：

```env
OPENAI_API_KEY=your_api_key
BASE_URL=https://api.deepseek.com
DEFAULT_MODEL=deepseek-chat
```

### 3. 运行 MAS 模拟

```bash
python mas_exp.py
```

输出：
- `behavior_log.csv`：边特征数据
- 控制台显示任务执行进度和统计信息

### 4. 训练与评估模型

```bash
python model_exp.py
```

输出：
- `task_subgraph_detector.pt`：训练好的模型
- 测试集性能指标
- 任务级别分析结果

## 实验结果

### 示例输出

```
总任务数: 5
总边数: 16
总异常边数: 4
异常率: 25.0%

训练准确率: 100%
测试准确率: 66.67%
召回率: 100%
F1 分数: 0.6667
```

### 任务子图示例

| 任务 | 流程 | 边数 | 异常边 |
|------|------|------|--------|
| task_001 | User → Agent_A → Agent_B → User | 3 | 1 |
| task_002 | User → Agent_B → Agent_C → User | 3 | 0 |
| task_003 | User → Agent_A → Agent_C → Agent_B → User | 4 | 2 |

## 核心模块

### 1. Agent 类 (`mas_exp.py`)

```python
class Agent:
    """智能体节点类"""
    def __init__(self, agent_id, system_prompt, is_user=False)
    def call_llm(self, query, inject_anomaly=False)
```

### 2. TaskSubgraph 类 (`mas_exp.py`)

```python
class TaskSubgraph:
    """任务子图：记录一个完整任务中的所有边"""
    def add_edge(self, edge_feature)
    def get_adjacency_list(self)
    def get_edge_index(self, node_id_to_idx)
```

### 3. MASSimulator 类 (`mas_exp.py`)

```python
class MASSimulator:
    """多智能体系统模拟器"""
    def create_task(self, task_id, user_id)
    def send_message(self, src_id, dst_id, query, ...)
    def execute_task(self, task_id, user_query, agent_sequence, ...)
```

### 4. TaskSubgraphDetector 类 (`model_exp.py`)

```python
class TaskSubgraphDetector(nn.Module):
    """任务子图异常检测模型"""
    def detect_in_subgraph(self, task_edges, node_features, edge_index, device)
    def update_node_history(self, node_id, features)
```

## 异常注入机制

在 MAS 模拟中，支持三种异常注入方式：

1. **语义一致性降低**：修改 System Prompt 使模型生成无关内容
2. **时延异常**：人为增加 `time.sleep` 模拟响应延迟
3. **高熵值注入**：人为增加 Logits 熵值模拟决策不确定性

## 扩展使用

### 自定义任务流程

```python
simulator.execute_task(
    task_id='custom_task',
    user_query='你的问题',
    agent_sequence=['Agent_A', 'Agent_B', 'Agent_C', 'User'],
    inject_anomaly_edges=[0, 2]  # 在第 0 和 2 条边注入异常
)
```

### 加载 MMLU 数据集

```bash
cd data/MMLU
python load.py
```

数据将保存至 `data/MMLU/data.jsonl`。

## 技术栈

- **Python 3.8+**
- **PyTorch 2.0+**：深度学习框架
- **PyTorch Geometric**：图神经网络
- **OpenAI API**：LLM 调用
- **scikit-learn**：评估指标
- **pandas / numpy**：数据处理

## 模型参数

```
总参数量: 78,114
├── NodeLSTM: ~50K
├── SubgraphGCN: ~8K
├── Fusion Layer: ~12.5K
└── Classifier: ~6K
```

## 相关文档

- **[FEATURE_SPEC.md](FEATURE_SPEC.md)** - 特征字段规范详细文档，包含完整的字段定义、约束条件和实现要求

## 引用

如果本项目对你有帮助，欢迎引用。

## License

MIT License