# Agent 网络流量快速实验工程

本工程用于快速完成以下闭环：

1. 通过大模型生成任务行为画像（任务阶段、工具调用、拆分、消息大小、处理时间等）；
2. 将行为画像扩展为结构化 Agent 事件日志；
3. 从训练日志估计状态转移、持续时间、消息大小、超时和分支参数；
4. 使用双层状态机、节点队列和离散事件调度进行仿真；
5. 自动完成预测验证、基线对比、压力实验和重试放大实验；
6. 输出 CSV、JSON 和 PNG 图表。

## 快速开始

当前环境已具备主要依赖，直接运行：

```powershell
cd agent_traffic_experiments
python run_pipeline.py
```

默认使用 `local` 模式，不需要 API Key。结果写入 `outputs/latest/`。

## 使用大模型生成行为画像

本工程兼容 OpenAI 风格的 `/v1/chat/completions` 接口。先设置环境变量：

```powershell
$env:OPENAI_API_KEY="你的密钥"
$env:OPENAI_BASE_URL="https://api.openai.com/v1"
$env:OPENAI_MODEL="你要使用的模型名称"
python run_pipeline.py --generator llm
```

也可以使用其他兼容服务，只需修改 `OPENAI_BASE_URL` 和 `OPENAI_MODEL`。

大模型只负责生成少量、可解释的任务行为画像；本地生成器会校验画像并扩展成大量事件。这样比让大模型直接输出数万行日志更稳定、更便宜，也能保证消息 ID、父子关系、时间戳和流量统计一致。

如果 LLM 请求失败，程序默认自动回退到本地画像。使用 `--no-fallback` 可禁止回退。

## 常用命令

只生成数据：

```powershell
python run_pipeline.py --steps generate
```

生成数据、估参并运行实验：

```powershell
python run_pipeline.py --steps generate,estimate,experiment
```

使用已有数据重新实验：

```powershell
python run_pipeline.py --steps estimate,experiment
```

指定配置和输出目录：

```powershell
python run_pipeline.py --config configs/default.yaml --output outputs/run_001
```

## 输出说明

```text
outputs/latest/
  data/
    behavior_profiles.json       # LLM或本地生成的任务画像
    train_events.csv             # 参数估计数据
    test_events.csv              # 留出验证数据
    task_truth.csv               # 测试任务真实聚合值
  parameters/
    estimated_parameters.json    # 从训练日志估计的模型参数
  results/
    validation_metrics.csv       # 完整模型与基线误差
    validation_predictions.csv   # 逐场景预测值和真实值
    stress_results.csv           # 到达率压力实验
    retry_results.csv            # 超时与重试放大实验
    summary.json                 # 实验摘要
  figures/
    prediction_vs_truth.png
    model_comparison.png
    stress_curves.png
    retry_heatmap.png
```

## 实验内容

### E1 预测验证

训练集用于估计参数，测试集作为“模拟实测值”。完整状态机模型预测测试场景的内部字节数、任务时延、消息数和工具调用数。

### E2 基线对比

- `static_mean`：固定平均流量放大倍数；
- `no_context`：不区分任务类型和任务阶段；
- `full_model`：按任务画像和估计参数运行状态机仿真。

### E3 压力实验

逐渐提高外部到达率，观察吞吐量、平均/P95延迟、队列峰值、失败率和流量放大系数。

### E4 重试放大实验

改变超时概率和最大重试次数，观察任务成功率、平均重试数和内部流量放大系数。

## 数据字段

事件日志主要字段包括：

- `timestamp`、`task_id`、`message_id`、`parent_message_id`；
- `task_type`、`task_phase`、`source`、`destination`；
- `state_before`、`state_after`、`state_duration_ms`；
- `message_type`、`message_size_bytes`；
- `queue_length`、`success`、`retry_count`、`is_external`。

## 注意事项

- 当前数据是用于方法验证的模拟数据，不能冒充真实生产日志；
- LLM 画像应在报告中标注模型名称、生成时间和提示词版本；
- 正式参赛前，应尽量用少量真实 Agent 日志替换或校准模拟参数；
- 所有随机实验都由配置中的随机种子控制，便于复现。