PrivAgents: Agents and MCP servers for Confidential AI Workflows

PrivAgents：面向机密 AI 工作流的 Agent 和 MCP 服务

PrivAgents 是一个以隐私为先的框架，展示了自主 Agent（无论在设备端还是云端）如何通过无需信任的 MCP 服务执行安全数据处理，同时确保完全保密。它利用隐私增强技术（PETs），即同态加密（HE），在不接触原始信息的情况下对加密数据进行计算。

通过对话式 Agent 界面，用户数据会在设备端加密，发送至安全处理单元（MCP），然后以加密形式返回结果，并在本地解密。这为医疗保健、个性化服务和金融等敏感场景打造了安全且智能的系统。

---

🔐 为什么选择 PrivAgents

设备端模型能够保护隐私，但往往能力有限。云端模型能力更强，却会引发信任方面的顾虑。PrivAgents 结合两者的优势来解决这一问题：

• 可选择设备端或基于云的 Agent，以满足计算能力和信任方面的需求
• 同态加密确保数据在处理过程中始终保密
• 模块化 MCP 服务在后端执行加密相似度计算
• 端到端加密管道，实现安全的数据交互

---

⚙️ 支持的 Agent

• ✅ Ollama Agent，使用本地模型在设备端进行推理
• ✅ OpenAI Agent，通过 API 提供云端智能服务

根据隐私限制和可用资源选择 Agent 类型。

---

🧠 架构概览

      +------------------------+
      |     User Device        |
      |  (Agent + Encryption)  |
      +------------------------+
         |   Encrypted Input
         v
+------------------------+   ← Secure Channel →
|     MCP Server         |  (Encrypted Similarity Calculation)
+------------------------+
         |   Encrypted Result
         v
      +------------------------+
      |  User Device (Decrypt) |
      +------------------------+

---

📁 项目结构

PrivAgents/
│
├── agent/           # Ollama and OpenAI agent implementations with PET tools
├── mcp/             # Encrypted processing logic for similarity-based analysis
├── utils/           # Context setup, encryption helpers
├── data/            # Sample inputs and encrypted output files
└── .env             # Configuration for ports and logging

---

🚀 快速开始

1. 克隆并设置

git clone https://github.com/UvrajSB/PrivRec.git
cd PrivRec
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

2. 启动 MCP 服务

在根目录中：

PYTHONPATH=. python mcp/server.py

3. 运行 Agent

• Ollama Agent（本地执行）

PYTHONPATH=. python agent/ollama_mcp_agent.py

• OpenAI Agent（云端执行）

PYTHONPATH=. python agent/openai_mcp_agent.py

每个 Agent 都会加密用户输入，将其发送出去进行加密相似度计算，并在设备端私密地解密响应。

---

🎬 电影偏好匹配：端到端加密个性化

电影偏好匹配用例实际演示了保护隐私的推荐系统如何在不访问明文用户数据的情况下运行。它展示了同态加密的端到端应用：加密用户偏好、执行安全相似度计算并提供个性化结果，同时确保原始数据绝不泄露。

---

🔁 工作流概览

1. 用户输入电影兴趣向量
   系统会请用户为不同类型（例如动作、爱情、科幻）评分或确定优先级。例如：

   [8, 2, 9] → represents user's preference intensity across three genres.
   

2. 在 Agent 端加密
   Agent（基于 Ollama 或 OpenAI）使用 TenSEAL，通过 BFV 方案对兴趣向量进行同态加密。结果是一个加密张量，即使对服务端来说也无法读取。

3. 在 MCP 服务上计算加密相似度

   • MCP 服务拥有一组预定义的电影档案，每个档案都表示为一个明文向量：

     MOVIES = {
       "Inception":     [9, 1, 8],
       "The Notebook":  [1, 9, 2],
       "Interstellar":  [8, 2, 9],
       "The Godfather": [7, 5, 4]
     }
     

   • 它会计算加密后的用户向量与每个明文电影档案之间的加密相似度。
   • 该相似度通过加密状态下的点积计算得出，不会解密用户向量。

4. 返回加密结果
   服务端会将所有电影的加密相似度分数写入文件，例如：

   data/interest_results
   

5. 在用户设备上解密
   Agent 加载加密结果，并使用原始上下文和密钥在本地解密。解密后的分数表示每部电影与用户偏好的匹配程度。

6. 可选：排序并展示结果
   Agent 可以对分数排序，并根据相似度展示排名靠前的电影推荐，同时确保用户的输入和偏好始终不会被服务端看到。

---

📦 优势

• ✅ 无需信任服务端：服务端永远看不到用户数据
• ✅ 不依赖特定 Agent：适用于设备端和云端的大模型 Agent
• ✅ 易于扩展：可支持更复杂的用户档案或其他领域（如音乐、购物、医疗保健）
• ✅ 具有教育意义：展示同态加密在实际场景中的工作方式

---

👥 参与贡献

有兴趣使用 PET 构建安全且智能的系统吗？无论是扩展 Agent 逻辑、尝试新的加密工作流，还是改进 MCP 层，我们都欢迎你贡献力量。Fork 此仓库并开始参与吧。