AI Email Agent

AI电子邮件代理

基于ReAct的AI邮件代理，采用TypeScript和Node.js构建，与Gmail API集成，实现智能邮件管理。该代理能够读取、搜索和起草邮件，并支持使用外部MCP（模型上下文协议）工具。

特点/特性

• ReAct 框架利用推理和行动循环进行智能决策
• Gmail 集成通过OAuth2认证全面访问Gmail
• 草稿创建为用户创建邮件草稿以供审阅（绝不自动发送）
• MCP 支持可以从外部MCP服务器消耗工具
• 结构化日志记录所有操作均记录并附有时戳
• TypeScript具有严格模式的类型安全实现

用例

1. 草拟电子邮件向指定收件人生成专业电子邮件
2. 回复电子邮件查找特定邮件并创建合适的回复
3. 电子邮件摘要总结每日邮件并按重要性分类
4. 日常管理/杂务识别垃圾邮件/广告以备潜在删除

先决条件

• Node.js 18及以上版本
• npm 或 yarn
• OpenAI API密钥
• 启用Gmail API的Google Cloud Console项目

安装

1. 克隆仓库

git clone 
cd llm-agent-template

1. 安装依赖项

npm install

1. 设置Google Cloud Console

a. 去到 Google Cloud 控制台

b. 创建一个新项目或选择现有项目

c. 启用Gmail API：

- 导航至“APIs 与服务”→“库” - 搜索“Gmail API” - 点击“启用”

d. 创建OAuth2凭据：

- 前往“APIs和服务”→“凭据” - 点击“创建凭据”→“OAuth 客户端 ID” - 选择“桌面应用程序”或“网页应用” - 添加授权重定向URI： http://localhost:3000/oauth2callback - 下载凭据（客户端ID和客户端密钥）

1. 配置环境变量

创建一个 .env 项目根目录下的文件：

# OpenAI API Key
OPENAI_API_KEY=your_openai_api_key_here

# Gmail OAuth2 Credentials
GMAIL_CLIENT_ID=your_client_id_here.apps.googleusercontent.com
GMAIL_CLIENT_SECRET=your_client_secret_here
GMAIL_REDIRECT_URI=http://localhost:3000/oauth2callback

# Optional: OpenAI Model (default: gpt-4o-mini)
OPENAI_MODEL=gpt-4o-mini

1. 构建项目

npm run build

认证

在使用该代理之前，请先使用Gmail进行身份验证：

npm run auth

这将：

1. 打开浏览器进行谷歌身份验证
2. 请求访问您的Gmail权限
3. 将身份验证令牌本地保存在 .credentials/tokens.json

您只需进行一次此操作。令牌过期时会自动刷新。

使用方法

该代理支持两种模式： 单次拍摄（或一次性拍摄） 并且 互动聊天。

单次拍摄模式

运行一个任务并退出：

npm run agent ""

互动聊天模式

与客服人员开始对话：

npm run chat

在聊天模式下，您可以：

• 进行多轮对话
• 提出后续问题
• 基于之前的上下文进行构建
• 类型 exit 或者 quit 结束会议

示例用例

1. 起草一封新邮件

npm run agent "Draft an email to john@example.com about tomorrow's project meeting at 2 PM"

1. 回复电子邮件

npm run agent "Reply to the email from jane@example.com about the quarterly report"

1. 总结每日邮件

npm run agent "Summarize all emails I received today and tell me which ones are important"

1. 查找垃圾邮件

npm run agent "Find all spam and promotional emails from the last week"

1. 搜索特定电子邮件

npm run agent "Find all emails from alice@example.com about the budget"

1. 互动对话

npm run chat

# Then have a conversation:
👤 You: Find emails from today
🤖 Agent: [searches and shows results]

👤 You: Reply to the one from John
🤖 Agent: [creates draft reply]

👤 You: exit

CLI 命令

• npm run auth - 使用Gmail进行身份验证
• npm run agent "" - 按照指令运行代理（一次性）
• npm run chat - 开始互动聊天会话（多轮对话）
• npm run prompt - 显示发送给大型语言模型（LLM）的系统提示
• npm start config - 显示MCP配置
• npm run dev - 以开发模式运行，使用tsx

查看系统提示

查看发送给大型语言模型（LLM）的确切提示（对调试很有用）：

npm run prompt

这将显示：

• 包含指令的完整系统提示
• 所有可用工具及其说明
• 已加载工具的统计数据（Gmail + MCP）

你也可以在不使用MCP工具的情况下查看提示

npm start prompt --no-mcp

禁用MCP工具

在不使用MCP工具的情况下运行：

# Single-shot mode
npm start run "" --no-mcp

# Chat mode
npm start chat --no-mcp

交互式聊天与一次性对话

使用聊天模式的时机：

• 你想进行一场来回对话
• 你需要完善或跟进之前的请求
• 你在逐步浏览你的收件箱
• 您希望基于之前查询的上下文进行构建

何时使用单次拍摄：

• 你有一个一次性任务
• 你正在逃避脚本或自动化操作
• 你希望代理在完成任务后退出

MCP 集成

该代理可以从外部MCP服务器消耗工具以扩展其功能。

配置MCP服务器

编辑 mcp-config.json：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/files"]
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "your_brave_api_key"
      }
    }
  }
}

查看MCP配置

npm start config

可用工具

该代理可以访问以下Gmail工具：

搜索电子邮件

使用Gmail查询语法搜索电子邮件。

参数：

• query （可选）：搜索查询（例如，“from:john@example.com subject:meeting”）
• maxResults （可选）：要返回的最大结果数（默认：10）
• after （可选）：查找日期之后（YYYY/MM/DD）的电子邮件
• before （可选）：查找日期之前（YYYY/MM/DD）的电子邮件

通过ID获取邮件

通过消息ID获取电子邮件的完整内容。

参数：

• messageId （必填）：唯一的消息ID

发送邮件

创建一封电子邮件草稿（新建或回复）。

参数：

• to （必填）：收件人电子邮件地址
• subject （必填）：电子邮件主题
• body （必填）：电子邮件正文（纯文本）
• threadId （可选）：回复的线程ID
• inReplyTo （可选）：用于线程处理的 Message-ID 头
• references （可选）：用于线程的引用头

注： 这会生成一个草稿供用户审阅，不会自动发送。

输出： 创建草稿后，工具显示：

• 草稿ID和预览URL
• 完整的电子邮件内容（收件人、主题、正文）
• 格式化以便在控制台中轻松查看

项目结构

llm-agent-template/
├── src/
│   ├── index.ts              # CLI entry point
│   ├── agent/
│   │   ├── react-agent.ts    # ReAct loop implementation
│   │   ├── tool-executor.ts  # Tool execution engine
│   │   └── logger.ts         # Action logging
│   ├── tools/
│   │   ├── gmail/
│   │   │   ├── search-email.ts
│   │   │   ├── get-email.ts
│   │   │   └── send-email.ts
│   │   └── index.ts          # Tool registry
│   ├── gmail/
│   │   ├── auth.ts           # OAuth2 flow
│   │   ├── client.ts         # Gmail API client
│   │   └── token-store.ts    # Token storage/refresh
│   ├── mcp/
│   │   ├── client.ts         # MCP client implementation
│   │   └── tool-adapter.ts   # MCP tool adapter
│   └── types.ts              # Shared TypeScript types
├── package.json
├── tsconfig.json
├── mcp-config.json
└── README.md

它是如何工作的

ReAct框架

该代理使用ReAct（推理与行动）框架：

1. 想法代理思考接下来该做什么
2. 行动代理调用工具并传入特定参数
3. 观察代理接收并分析工具结果
4. 重复持续进行直至任务完成（最多10次迭代）
5. 答案向用户提供最终回复

日期意识

代理自动知晓当前日期。系统提示包括：

• 当前日期，以人类可读的格式表示（例如，“2024年1月15日，星期一”）
• 用于Gmail查询的ISO格式日期（YYYY-MM-DD）

这使得可以进行如下的自然查询：

• “给我看看今天的邮件”
• “总结上周的电子邮件”
• “查找昨天的消息”

示例流程：

User: "Reply to John's email about the meeting"

Thought: I need to find John's email first
Action: search_email
Input: {"query": "from:john subject:meeting"}
Observation: [Found email with ID: abc123]

Thought: Now I need to read the full email
Action: get_email_by_id
Input: {"messageId": "abc123"}
Observation: [Email content about meeting on Friday]

Thought: I'll create a reply confirming attendance
Action: send_email
Input: {
  "to": "john@example.com",
  "subject": "Re: Meeting",
  "body": "Thanks John, I'll be there on Friday.",
  "threadId": "thread123",
  "inReplyTo": "",
  "references": ""
}
Observation: [Draft created: draft456]

Answer: I've created a draft reply to John's email about the meeting...

记录日志

所有操作均记录在：

• 控制台（带颜色）
• agent.log 文件

日志格式： [timestamp] [level] action: details

配置

环境变量

• OPENAI_API_KEY 您的OpenAI API密钥（必需）
• GMAIL_CLIENT_ID - Gmail OAuth2 客户端ID（必填）
• GMAIL_CLIENT_SECRET - Gmail OAuth2 客户端密钥（必需）
• GMAIL_REDIRECT_URI - OAuth2 重定向URI（默认：http://localhost:3000/oauth2callback）
• OPENAI_MODEL - 要使用的OpenAI模型（默认：gpt-4o-mini）

Gmail API 配额

Gmail API 的配额如下：

• 每天10亿次查询
• 每秒每个用户250次查询
• 每秒每个用户25,000个配额单位

每个API调用都会消耗配额单位：

• 列出消息：5条
• 收到消息：5个单位
• 创建草案：10个单位

对于大多数使用场景来说，这些限制是绰绰有余的。

安全考量

• 代币本地存储于 .credentials/tokens.json
• 永远不要承诺 .env 或者 .credentials/ 进行版本控制
• OAuth2令牌会自动刷新
• 所有电子邮件在发送前都会作为草稿创建以供审阅
• MCP服务器在隔离的进程中运行

故障排除

“未找到身份验证令牌”

跑 npm run auth 使用Gmail进行身份验证。

“OPENAI_API_KEY 未设置”

创建一个 .env 使用您的OpenAI API密钥文件。

“无法连接到MCP服务器”

检查以下内容：

• MCP服务器的命令和参数是正确的
• 所需的环境变量已设置
• MCP服务器已安装

“已达到最大迭代次数”

代理无法在10次迭代内完成任务。请尝试：

• 简化您的指示
• 对你想要的东西有更具体的描述
• 将复杂任务分解为更小的任务

调试代理行为

使用 npm run prompt 查看发送给大型语言模型（LLM）的确切指令。这有助于理解：

• 代理知道哪些工具
• 它遵循的是什么指示
• 如果MCP工具正在正确加载
• 当前日期已提供给代理

发展

在开发模式下运行

npm run dev -- run "your instruction"

构建 TypeScript

npm run build

运行构建版本

npm start run "your instruction"

许可证

麻省理工学院（MIT）

贡献

欢迎贡献！请随时提交拉取请求。

致谢

• 使用……构建 OpenAI API
• 用途 Gmail API
• 支持 模型上下文协议
• 基于ReAct框架的 姚等人，2022