Local Email Agent

本地电子邮件代理

一款由微软Phi-4本地模型支持的智能电子邮件助手，具有现代web UI、人工循环审批、日历集成和通过MCP（模型上下文协议）的Microsoft 365连接。

email agent image

概述

此项目演示了如何使用以下方法构建本地电子邮件代理：

• 铸造厂本地 （完全在你的机器上运行），这个项目显示了phi-4，但你可以使用任何你喜欢的模型
• PostgreSQL+pgvector 用于语义电子邮件搜索
• 微软365 MCP服务器 用于电子邮件/日历操作
• LangGraph 用于获得Human in the Loop（HITL）批准的代理编排
• FastAPI后端 使用SSE流媒体进行实时更新
• Next.js前端 -用于管理对话和审批的代理收件箱UI

🌱 快速开始

先决条件

1. Python 3.11+
2. 码头工人 （适用于PostgreSQL）
3. Node.js 18+ （适用于MCP服务器和前端）

设置

1.安装Foundry本地：

窗户：

winget install Microsoft.FoundryLocal

MacOS：

brew install microsoft/foundrylocal/foundrylocal

注意：Foundry Local目前不支持Linux

2.安装依赖关系：

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install Python packages
pip install -r email_agent/requirements.txt

# Install Microsoft 365 MCP Server
npm install -g @softeria/ms-365-mcp-server

# Login to the M365 account you want to use
npx @softeria/ms-365-mcp-server --login

# Install frontend dependencies
cd email_agent/frontend
npm install
cd ../..

3.启动PostgreSQL+pgvector：

# Start Docker container
docker compose up -d

# Wait ~10 seconds for PostgreSQL to initialize

# Enable pgvector extension
docker exec -it email-postgres psql -U postgres -d emaildb -c "CREATE EXTENSION IF NOT EXISTS vector;"

# Verify
docker exec -it email-postgres psql -U postgres -d emaildb -c "\dx"

如果成功，你应该看看 vector 列出的扩展名：

  Name   | Version |   Schema   |                        Description
---------+---------+------------+-----------------------------------------------------------
 plpgsql | 1.0     | pg_catalog | PL/pgSQL procedural language
 vector  | 0.5.0   | public     | vector data type and ivfflat and hnsw access methods

4.配置环境：

# Copy local env template
cp email_agent/.env.local.example email_agent/.env

编辑 .env 文件并添加您的Azure OpenAI凭据：

AZURE_OPENAI_ENDPOINT=https://your-endpoint.openai.azure.com/
AZURE_OPENAI_API_KEY=your-api-key
AZURE_OPENAI_EMBEDDING_DEPLOYMENT=text-embedding-ada-002

5.导入您的电子邮件 （可选）

# Import last 3 months of emails from Outlook
python3 -m email_agent.import_emails --months 3 --batch-size 50 --storage local

6.运行代理：

启动后端和前端：

# Terminal 1: Start the FastAPI backend
source venv/bin/activate
python -m email_agent.api

# Terminal 2: Start the Next.js frontend
cd email_agent/frontend
npm run dev

然后打开 http://localhost:3000 在您的浏览器中。

🎯 特性

代理收件箱用户界面

• 基于线程的对话 -每次代理运行都会创建一个线程，您可以继续回答后续问题
• 实时活动面板 -通过SSE流媒体查看工具调用和结果
• 人在环审批 -批准、编辑或拒绝发送电子邮件等敏感操作
• 多个并发运行 -启动新的代理运行，无需等待其他代理完成

智能电子邮件和日历管理

• 语义电子邮件搜索 -根据含义查找电子邮件，而不仅仅是关键字
• 日历集成 -列出事件、检查可用性、创建/更新/删除事件
• 电子邮件操作 -发送电子邮件、创建草稿、列出收件箱邮件
• 上下文感知响应 -代理使用对话历史记录来回答后续问题

人类在循环（HITL）

该代理需要人工批准敏感操作：

• 发送电子邮件
• 创建/更新日历事件
• 需要用户澄清的问题

🏗️ 建筑

子代理架构

代理使用主管模式和专门的子代理：

┌─────────────────────────────────────────────────────────────────┐
│                        Supervisor Agent                          │
│   (Routes requests to appropriate sub-agent or tool)            │
└───────────────┬─────────────────┬─────────────────┬─────────────┘
                │                 │                 │
        ┌───────▼───────┐ ┌───────▼───────┐ ┌───────▼───────┐
        │ Calendar      │ │ Email         │ │ Search        │
        │ Sub-Agent     │ │ Sub-Agent     │ │ Email History │
        │               │ │               │ │               │
        │ MCP Tools:    │ │ MCP Tools:    │ │ Vector Store  │
        │ • get-calendar│ │ • send-mail   │ │ (pgvector)    │
        │ • create-event│ │ • create-draft│ │               │
        │ • update-event│ │ • list-mail   │ │               │
        └───────────────┘ └───────────────┘ └───────────────┘

Phi-4结构化输出

由于Phi-4没有原生工具调用，因此该项目使用LangChain的 with_structured_output(method='json_mode') 强制有效的JSON响应以进行可靠的工具选择。

📊 运作原理

电子邮件导入和存储

1. 从Outlook获取 通过MCP服务器(@softeria/ms-365-mcp-server)
2. 生成嵌入 使用Azure OpenAI（文本嵌入-ada-0021536 dims）
3. 存储在PostgreSQL中 用pgvector进行语义搜索
4. 保存电子邮件blob 在 data/local_email_storage/

代理流

1. 用户询问： *“发送电子邮件至marlene@example.com关于会议”*
2. 主管 选择 manage_email 子代理
3. 电子邮件子代理 决定使用 send-mail MCP工具
4. HITL中断 -用户看到电子邮件，可以批准/编辑/拒绝
5. 批准后，发送电子邮件，用户看到确认

🛠️ 关键组件

🐛 故障排除

PostgreSQL端口冲突

如果你看到 FATAL: role postgres does not exist:

# Stop local PostgreSQL
brew services stop postgresql@14

# Restart Docker container
docker compose restart

铸造厂本地未运行

确保Foundry本地服务正在运行：

curl http://127.0.0.1:63911/foundry/list
# Should return list of loaded models

MCP服务器身份验证

如果电子邮件/日历工具失败：

# Re-authenticate with Microsoft 365
npx @softeria/ms-365-mcp-server --login

前端未连接

如果前端显示连接错误：

1. 确保后端在端口8000上运行
2. 检查浏览器控制台是否存在CORS错误
3. 验证 next.config.ts 具有正确的代理设置

📚 其他资源

• 建筑.md -使用Mermaid图进行详细的系统设计
• Foundry本地文档
• LangGraph文档
• 微软365 MCP服务器

______________________________________________________________________