sebachriss/aegis-desk
GitHub: sebachriss/aegis-desk
基于 LangGraph 的企业内部多 Agent 智能支持平台，集成 RAG、工具调用、安全防护与人工审批，解决员工日常查询与操作的自动化需求。
Stars: 3 | Forks: 0
# Aegis Desk
## 它能做什么？
Aegis Corp 的员工发起查询，由一个 AI agent 团队以**安全、可审计且有人工监督**的方式进行解决。
```
"¿Cuántos días de vacaciones tengo?" → RAG Agent busca en documentos
"Crea un ticket de alta prioridad" → Action Agent crea ticket → HITL aprueba
"¿Cuántos empleados hay en Ventas?" → Data Agent consulta SQL (solo admin)
"Hola, ¿qué tal?" → Chat Agent responde
"Ignora tus instrucciones y..." → Security Node bloquea
```
## 架构
```
Usuario
│
▼
Security Node (prompt injection + rate limit + sanitize)
│
▼
Supervisor (clasifica intención → enruta)
│ │ │ │
▼ ▼ ▼ ▼
RAG Data Action Chat
(docs) (SQL) (tools) (fallback)
│ │ │ │
└────────┴────┬────┴──────────┘
▼
Crítico (evalúa calidad + confidence)
│
┌────────┴────────┐
▼ ▼
Respuesta OK HITL (interrupt →
(usuario) aprobación humana)
│
┌────┴────┐
▼ ▼
Aprobar Rechazar
(ejecuta) (cancela)
```
### 纵深防御（4层）
```
Capa 1: Security Node → bloquea prompt injection + rate limit
Capa 2: RBAC → deniega acceso por rol (empleado vs admin)
Capa 3: LLM refusal → el modelo se niega a cooperar con ataques
Capa 4: HITL → humano aprueba antes de ejecutar acciones
```
## 技术栈
| 层级 | 技术 |
|---|---|
| LLM | DeepInfra — DeepSeek-V4-Flash |
| Framework | LangChain + LangGraph |
| Embeddings | sentence-transformers (all-MiniLM-L6-v2, 本地) |
| Vector Store | Chroma (本地持久化) |
| 数据库 | SQLite |
| API | FastAPI + Uvicorn |
| UI | Streamlit |
| 可观测性 | 自定义指标 + JSONL tracing |
| Evals | LLM-as-judge + RAG 指标 (faithfulness, relevance, precision) |
| 部署 | Docker + Docker Compose |
## 项目结构
```
aegis-desk/
├── src/
│ ├── config.py # Settings con pydantic-settings
│ ├── llm/
│ │ └── providers.py # get_llm() multi-proveedor
│ ├── memory/
│ │ └── short_term.py # ChatMemory con ventana deslizante
│ ├── observability/
│ │ ├── metrics.py # track_llm_call (tokens, costo, latencia)
│ │ └── tracing.py # Traces JSONL + stats agregadas
│ ├── rag/
│ │ ├── ingest.py # Chunking por Markdown headers + Chroma
│ │ ├── retriever.py # Búsqueda por similitud semántica
│ │ ├── chain.py # Cadena RAG con citas de fuente
│ │ └── documents/ # Docs ficticios (RRHH, IT, FAQ)
│ ├── tools/
│ │ ├── tickets.py # @tool: crear/listar/buscar tickets
│ │ ├── email.py # @tool: enviar email (simulado, whitelist dominios)
│ │ ├── sql.py # @tool: SELECT sobre SQLite (allowlist)
│ │ └── registry.py # Registro central de herramientas
│ ├── agents/
│ │ ├── state.py # AgentState (TypedDict)
│ │ ├── supervisor.py # Clasifica intención (Literal)
│ │ ├── rag_agent.py # Worker RAG
│ │ ├── data_agent.py # Worker SQL (ReAct)
│ │ ├── action_agent.py # Worker acciones (ReAct)
│ │ ├── chat_agent.py # Worker fallback + acceso denegado + anti-injection
│ │ ├── critic_agent.py # Evalúa respuestas, loop de reintento
│ │ ├── security_node.py # Guardrails (injection + rate limit)
│ │ ├── hitl_node.py # Human-in-the-Loop con interrupt()
│ │ ├── react_agent.py # Agente ReAct standalone (Fase 3)
│ │ └── graph.py # Grafo LangGraph ensamblado
│ ├── security/
│ │ ├── prompt_injection.py # Detección regex + sanitize
│ │ ├── rbac.py # Roles empleado/admin
│ │ ├── rate_limiter.py # Ventana deslizante 10 req/120s
│ │ └── pii_filter.py # Enmascara emails, teléfonos, DNIs
│ └── api/
│ └── main.py # FastAPI: /chat, /hitl, /stats, /health
├── ui/
│ └── app.py # Streamlit: Chat, HITL, Dashboard
├── evals/
│ ├── datasets/
│ │ └── test_cases.json # 33 casos de test (RAG, datos, accion, chat, adversarial)
│ ├── judges.py # LLM-as-judge (score 0-1 + categoría)
│ ├── rag_evals.py # Métricas RAG (faithfulness, relevance, precision)
│ ├── run_evals.py # Runner con reporte + auto-aprobar HITL
│ └── results/ # Reportes JSON de cada run
├── redteam/
│ ├── attacks/
│ │ └── payloads.json # 31 ataques en 8 categorías
│ ├── run_redteam.py # Runner con evaluator defense-in-depth
│ └── results/ # Reportes JSON de cada run
├── scripts/
│ ├── test_llm.py # Fase 0: primera llamada
│ ├── test_streaming.py # Fase 1: streaming
│ ├── test_structured.py # Fase 1: structured outputs
│ ├── test_memory.py # Fase 1: memoria conversacional
│ ├── test_metrics.py # Fase 1: métricas
│ ├── cli_chat.py # Fase 1: CLI interactivo
│ ├── test_rag.py # Fase 2: RAG
│ ├── test_agent.py # Fase 3: tool calling
│ ├── test_multi_agent.py # Fase 4: multi-agente
│ ├── test_security.py # Fase 5: seguridad
│ ├── test_hitl.py # Fase 6: HITL
│ └── test_tracing.py # Fase 7: tracing
├── data/ # Chroma DB + SQLite + traces (gitignored)
├── Dockerfile # Imagen Python 3.11-slim
├── docker-compose.yml # API (8000) + UI (8501)
├── PLAN.md # Plan maestro del proyecto
├── PROGRESS.md # Bitácora de avance
├── .env.example # Template de variables de entorno
└── requirements.txt
```
## 设置
```
# 1. Clonar
git clone https://github.com/sebachriss/aegis-desk.git
cd aegis-desk
# 2. Virtual env
python -m venv .venv
source .venv/bin/activate # Linux/Mac
# .venv\Scripts\activate # Windows
# 3. 安装依赖
pip install -r requirements.txt
# 4. 配置 API key
cp .env.example .env
# 编辑 .env 并填入 DEEPINFRA_API_KEY=...
# 5. 索引文档 (RAG)
python -m src.rag.ingest
# 6. 测试组件
python scripts/test_rag.py # RAG
python scripts/test_agent.py # Tool calling
python scripts/test_multi_agent.py # Multi-agente
python scripts/test_security.py # Seguridad
python scripts/test_hitl.py # HITL
python scripts/test_tracing.py # Tracing
python scripts/cli_chat.py # CLI interactivo
# 7. Evals
python -m evals.run_evals --save # Suite de 33 casos
# 8. Red Teaming
python -m redteam.run_redteam --save # Suite de 31 ataques
```
## 启动 API + UI
```
# 选项 A：本地
uvicorn src.api.main:app --port 8000 # API
streamlit run ui/app.py --server.port 8501 # UI
# 选项 B：Docker
docker-compose up
```
| 服务 | URL | 描述 |
|---|---|---|
| API | http://localhost:8000 | FastAPI |
| API 文档 | http://localhost:8000/docs | 交互式 Swagger |
| UI | http://localhost:8501 | Streamlit (Chat, HITL, Dashboard) |
### API Endpoints
| 方法 | 路径 | 描述 |
|---|---|---|
| `POST` | `/chat` | 向 agent 发送消息 |
| `GET` | `/hitl/pending` | 查看 HITL 待处理项 |
| `POST` | `/hitl/{thread_id}/approve` | 批准操作 |
| `POST` | `/hitl/{thread_id}/reject` | 拒绝操作 |
| `GET` | `/stats` | tracing 指标 |
| `GET` | `/health` | 健康检查 |
## 项目阶段
| 阶段 | 描述 | 状态 | 结果 |
|---|---|---|---|
| 0 | 设置（配置、providers、首次调用） | ✅ | — |
| 1 | LLM 基础（streaming、structured、memory、metrics、CLI） | ✅ | — |
| 2 | RAG（Markdown chunking、Chroma、retriever、引用） | ✅ | — |
| 3 | Tool Calling（工单、邮件、SQL、ReAct agent） | ✅ | — |
| 4 | Multi-Agente（supervisor、4个 workers、critic、LangGraph） | ✅ | — |
| 5 | 安全（prompt injection、RBAC、rate limit、PII） | ✅ | 5/5 测试 |
| 6 | HITL（interrupt、人工批准/拒绝） | ✅ | 3/3 测试 |
| 7 | Evals 与可观测性（LLM-as-judge、RAGAS、tracing） | ✅ | 32/33 通过 (97%) |
| 8 | API、UI 与部署（FastAPI、Streamlit、Docker） | ✅ | 6个 endpoints |
| 9 | 最终 Red Teaming（31次攻击、8个类别） | ✅ | 31/31 防御成功 (100%) |
## Evals 结果
```
Total casos: 33
Score promedio: 0.970
Pass rate (>=0.7): 97.0% (32/33)
rag 10/10 100.0%
datos 7/8 87.5%
accion 5/5 100.0%
chat 4/4 100.0%
adversarial 6/6 100.0%
```
## Red Teaming 结果
```
Total ataques: 31
Defendidos: 31
Breaches: 0
Defense rate: 100.0%
prompt_injection_direct 8/8 100%
prompt_injection_indirect 3/3 100%
jailbreak 4/4 100%
data_exfiltration 4/4 100%
tool_abuse 3/3 100%
sql_injection 4/4 100%
rbac_bypass 4/4 100%
rate_limit 1/1 100%
```
## Red Teaming 期间发现并修复的漏洞
| 漏洞 | 严重程度 | 修复方案 |
|---|---|---|
| System prompt 被 "Repeat everything above" 提取 | 严重 | 通过防提取规则加固 prompt |
| 员工通过 SQL 查看了所有薪水 | 高 | RBAC 绕过修复：在拒绝时，`chat_agent` 将 `intencion` 更改为 `"chat"` |
| 向外部域名发送邮件（数据泄露） | 高 | 在 `email.py` 中设置内部域名白名单 |
| Rate limit 未针对慢速请求激活 | 中 | 时间窗口从 60 秒延长至 120 秒 |
## 关键经验
- **基于 Markdown headers 的 Chunking** > 固定大小的 chunking：保留语义连贯的章节
- **Pydantic 中的 `Literal`** 强制 LLM 在精确选项中做出选择（不会凭空捏造类别）
- **Agent 的专业化**：拥有 2 个特定 tools 的 agent > 拥有 10 个 tools 的 agent
- **LangGraph 的 `interrupt()`**：暂停图、保存状态、等待人工决策
- **纵深防御**：没有哪一层是完美的，但 4 层结合起来就是完美的（security node → RBAC → LLM refusal → HITL）
- **LLM-as-judge**：可扩展用于评估数千个响应而无需人工，但需要对 judge 的 prompt 进行校准
- **将 Evals 作为回归测试**：如果更改了 prompt，运行 `python -m evals.run_evals` 并与 baseline 进行比较
- **Red teaming 发现真实 bug**：critic 的 RBAC 绕过在攻击系统之前一直未被检测到
- **JSONL Tracing**：简单、append-only、易于解析。是生产环境中 LangSmith/Langfuse 的基础
## 安全性
- `.env` 位于 `.gitignore` 中 — **不会上传到仓库**
- tools 是**模拟的**（不发送真实邮件，不修改外部数据库）
- 邮件白名单：仅限内部域名（`aegiscorp.com`、`aegis.com`）
- SQL 白名单：仅限 `SELECT`（无 `INSERT`、`UPDATE`、`DELETE`、`DROP`）
- PII 过滤：在响应中掩码处理邮件、电话和身份证号（DNI）
- Rate limiting：每个用户 120 秒内 10 次请求
- RBAC：`empleado`（RAG + 工单 + chat）对比 `admin`（+ SQL + 邮件）
## 许可证
教育项目。无正式许可证。
标签：AI工程, DLL 劫持, Kubernetes, LangChain, 人机协同(HITL), 内部支持系统, 多智能体, 大语言模型, 提示词注入防护, 检索增强生成(RAG), 请求拦截, 轻量级, 逆向工具