从零构建邮件智能体
循序构建具备邮件分流、人工审批、评测与长期记忆的助手。
- Star 数
- ★ 2.4k
- 最近更新
- 2 个月前
- License
- MIT
- 主语言
- Jupyter Notebook
- FA 评分
- 49/100 · 缺口较多
30 秒速览
- 运行形态
- 可在哪里用
- 平台专用OpenAI API
- 费用
- 软件免费，模型调用费用自付
- 上手难度
- 中 · 需要几步配置
- 开始前需要
- 典型场景
- 正在学习 LangGraph 的 Python 开发者，可按 notebook 顺序理解聊天模型、工具调用、节点、边、记忆以及智能体与工作流的区别。
- 不适合
- 只想直接使用成品邮件助手、不愿自己搭建和部署代码的用户
- 需要开箱即用 Gmail 授权与部署步骤的团队，相关细节需另查文档
这个 Agent 能做什么，适合哪些场景？
这是一个面向开发者的分阶段教程与参考实现，最终产物是可连接 Gmail API 的环境式邮件助手。项目由四组 notebook 及 src/email_assistant 中的配套 Python 代码组成，依次覆盖基础智能体、评测、人工介入和记忆。助手先进行邮件分流，再由智能体处理回复；发送邮件和安排会议等特定工具调用可以交给用户审核。记忆版本通过 LangGraph Store 持久保存反馈与偏好，完整 Gmail 版本位于 email_assistant_hitl_memory_gmail.py。项目还提供基于 Pytest、LangSmith evaluate API 和 LLM-as-a-judge 的评测路径，并说明 Gmail 图可以部署到 LangGraph Platform，但所给材料未包含具体部署命令。
基础流程在 src/email_assistant/email_assistant.py 中把邮件分流步骤与负责邮件回复的智能体组合起来。notebooks/evaluation.ipynb 使用 eval/email_dataset.py 中的邮件数据，通过 Pytest 和 LangSmith evaluate API 检查回复质量、工具调用与分流决策，其中回复评测包含 LLM-as-a-judge。src/email_assistant/email_assistant_hitl.py 增加人工介入，并通过 Agent Inbox 让用户审核发送邮件、安排会议等特定工具调用。src/email_assistant/email_assistant_hitl_memory.py 使用 LangGraph Store 持久化记忆，从用户反馈中学习并逐步适应偏好。notebook 默认使用模拟邮件与日历工具；src/email_assistant/email_assistant_hitl_memory_gmail.py 则提供 Gmail API 集成版本。测试结果写入 .env 中 LANGSMITH_PROJECT 指定的 LangSmith 项目，以便查看轨迹、评测指标和实现对比。
- 正在学习 LangGraph 的 Python 开发者，可按 notebook 顺序理解聊天模型、工具调用、节点、边、记忆以及智能体与工作流的区别。
- 准备开发邮件自动化产品的工程团队，可从邮件分流、回复处理和 Gmail API 集成的参考代码起步。
- 需要控制高影响操作的团队，可借鉴 Agent Inbox 审核发送邮件和安排会议等工具调用的人工介入设计。
- 希望助手长期适应用户习惯的开发者，可研究基于 LangGraph Store 保存反馈和偏好的记忆实现。
- 需要建立智能体质量门槛的评测工程师，可复用邮件数据集、Pytest、LangSmith
evaluateAPI 以及针对回复、工具调用和分流决策的评测方法。
如何安装或部署这个 Agent？
需要 Python 3.11 或更高版本。先在仓库根目录执行 cp .env.example .env，然后在 .env 中设置 LANGSMITH_API_KEY=your_langsmith_api_key、LANGSMITH_TRACING=true、LANGSMITH_PROJECT="interrupt-workshop" 和 OPENAI_API_KEY=your_openai_api_key。推荐安装方式为：pip install uv，随后执行 uv sync --extra dev 和 source .venv/bin/activate。也可执行 python3 -m venv .venv、source .venv/bin/activate、python3 -m pip install --upgrade pip、pip install -e .。可编辑安装不能省略；包名为 interrupt_workshop，导入名为 email_assistant。使用 Gmail 版本还需按照 src/email_assistant/tools/gmail/README.md 配置 Google API 凭据，但所给材料没有列出其具体步骤。
如何使用这个 Agent？
按 notebooks/agent.ipynb、notebooks/evaluation.ipynb、notebooks/hitl.ipynb、notebooks/memory.ipynb 的顺序学习和运行相应实现；需要基础概念时先看 notebooks/langgraph_101.ipynb。代码中可以使用 from email_assistant import ... 导入已安装包。基础实现、人工介入实现、记忆实现和 Gmail 完整实现分别位于 email_assistant.py、email_assistant_hitl.py、email_assistant_hitl_memory.py 和 email_assistant_hitl_memory_gmail.py。运行自动化测试可执行 python tests/run_all_tests.py；检查全部 notebook 可执行 python tests/test_notebooks.py 或 pytest tests/test_notebooks.py -v。所给材料没有提供启动交互式邮件助手或部署到 LangGraph Platform 的完整命令，因此不能仅凭这些内容给出可复制的首次生产调用。
这个 Agent 有哪些优点和局限？
- 采用四阶段递进结构，并为每一阶段同时提供 notebook 和配套 Python 实现，便于从概念实验过渡到代码。
- 人工介入不是抽象说明：项目明确使用 Agent Inbox 审核发送邮件、安排会议等高影响工具调用。
- 记忆实现使用 LangGraph Store 持久保存用户反馈与偏好，而非只保留单次对话上下文。
- 评测覆盖回复质量、工具调用和分流决策，并结合 Pytest、LangSmith
evaluateAPI 与 LLM-as-a-judge。 - 既提供模拟邮件和日历工具，也提供独立的 Gmail API 完整实现，适合先离线学习再接入真实邮箱。
- 运行依赖 Python 3.11+、OpenAI API 密钥和 LangSmith API 密钥，评测与追踪绑定到相应服务。
- Gmail 集成需要额外配置 Google API 凭据；具体权限、授权步骤和部署命令不在所给材料中。
- README 只明确列出
email_assistant这一种可测试实现，没有证明其他实现均已纳入同一自动化测试入口。 - 材料没有给出启动交互式助手的单一命令、生产运行参数或故障恢复行为，落地时仍需阅读代码与补齐运行封装。
- 未来才计划通过 LangMem 管理后台记忆集合和提供记忆查询工具，因此这些能力不属于当前已实现范围。
这个 Agent 与同类方案有什么区别？
与只执行固定步骤的工作流相比，项目将邮件分流步骤和能够处理回复的智能体组合起来；langgraph_101.ipynb 专门介绍智能体与工作流的区别。项目没有提供与其他具体邮件助手或智能体框架的实证对比。
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | 形态 / 费用 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|---|
| 从零构建邮件智能体 当前 | 49 · 缺口较多 | 代码库 / SDK免费 + 模型费 | ★ 2.4k | 2 个月前 | Jupyter Notebook | OpenAI API |
| Deuz SDK | 69 · 存在缺口 | 代码库 / SDK免费 + 模型费 | ★ 563 | 2 天前 | TypeScript | OpenAI API · Claude API |
| LangGraph Multi-Agent Swarm | 51 · 缺口较多 | 代码库 / SDK免费 + 模型费 | ★ 1.6k | 29 天前 | Python | OpenAI API |
| EvoAgentX | 47 · 缺口较多 | 代码库 / SDK免费 + 模型费 | ★ 3.4k | 1 个月前 | Python | OpenAI API |
FollowAgents 如何评估这个 Agent？
查看各维度的扣分理由
证据说明高影响工具调用（发送邮件、安排会议）可交由人工审查，且工作流权限大体为只读；因此用户确认和外部影响控制获得部分肯定。README也披露了OpenAI、LangSmith、Gmail及持久化记忆等主要外部数据路径，并由许可证和版权声明提供来源归属。扣分原因是未提供Gmail授权范围、最小权限设计、邮件与记忆内容如何传输或保留、敏感数据清理、撤销已执行操作或恢复机制；依赖仅设宽泛下限，工作流还使用beta动作，未见锁定、漏洞扫描或缓解策略。人工审查只被描述，所给材料中没有实现代码可核实其覆盖范围。未知的发布者身份未被视为风险，也未用于加分。
README、项目配置和测试文件共同表明Python版本、安装方式、外部服务及测试入口，但只能支持普通程度以下的静态可靠性判断。扣分点包括README所称安装包名与pyproject项目名不一致、conftest默认选择记忆实现而运行器只允许基础实现，以及HITL/记忆实现因Question工具和恢复命令问题被明确排除。依赖外部API、密钥和LangSmith，缺少离线或降级说明；错误信息主要限于测试脚本中的未知实现和笔记本执行失败，未展示产品运行时的恢复性错误处理。
材料按基础代理、评估、人工介入和记忆四阶段覆盖学习者与邮件助理场景，并区分模拟工具、Gmail集成、可部署实现和未来LangMem扩展，因而场景和能力边界较清楚。扣分原因是未给出适用生产规模、隐私环境、模型替换或非邮件迁移的具体适配步骤；触发精度只概述邮件分流和“特定”工具调用需审查，未展示分类阈值、允许列表、审批策略或误触发处理。Python 3.11至3.13、uv/pip和环境变量说明支持常见环境，但外部平台依赖限制了环境适配满分。
README的信息架构清晰，提供分阶段导航、代码与笔记本入口、环境配置、两种安装方式、测试命令和Gmail部署指引；完整MIT文本与元数据一致，因此这些项目得分较高。扣分在于项目名、README所称安装名和导入名之间存在不稳定或矛盾；示例丰富但没有真正的FAQ或故障排除章节。已明确披露部分测试限制和未来工作，但主要藏在测试代码注释中。版本只有0.1.0，未见变更日志、发布策略或兼容承诺；版权主体可见，但未提供已验证维护者、支持渠道或明确更新责任。
作为教学型仓库，分阶段笔记本、配套模块、评估、人工审批和记忆形成可直接学习和改造的产物，相比单一邮件代理示例具有明显增量价值。扣分原因是所给证据没有展示最终输出契约、生产部署结果或完整HITL/记忆实现的可用性；测试运行器实际上只覆盖基础助手。使用OpenAI、LangSmith、Gmail及可能的平台部署会产生凭据、服务和运行成本，但没有成本估算、速率限制、资源需求或轻量替代方案，因此成本效益只能获得薄弱支持。
README把主要功能主张映射到具体笔记本、源码路径、测试和配置，且pyproject与测试文件能交叉印证Python范围、依赖、测试方式和实现名称。未来扩展被明确标注，测试代码也坦率区分可测与不可测实现，事实与计划的分离较好。扣分原因是关键代理源码、Gmail工具说明、笔记本内容和实际测试结果未包含在材料中；“可部署”“自动化测试套件”和记忆/HITL效果等主张因此只能追踪到引用，不能从当前文件充分复核，也没有独立来源交叉证明。
- 源码中未见：敏感信息处理使用专用、低权限、可随时吊销的 API 密钥，不要复用生产凭据，也不要让密钥出现在日志里。
- 源码中未见：依赖安全审查安装前固定版本并做一次依赖扫描（如 npm audit、pip-audit）；优先放在容器里运行。
- 源码中未见：回滚或恢复路径运行前先备份，或在 git 分支、快照上操作，确保改动可以撤销。
- 人工介入与记忆版本未被现有运行器测试；测试代码明确记录Question工具可能使恢复流程无限循环。
- 在接入真实Gmail前，应核实OAuth权限范围、发送和日历操作的逐项审批覆盖，以及已执行操作的撤销或补偿方案。
- 邮件内容、用户反馈、长期记忆和LangSmith追踪可能包含敏感数据；材料未说明最小化、脱敏、保留期限或删除流程。
- 依赖未精确锁定，且GitHub工作流使用beta第三方动作；部署前应锁定版本并进行供应链与漏洞审查。
- 不要把README中的测试和部署描述视为已验证结果；本评估未执行代码、笔记本或外部API。
常见问题
可以不连接真实 Gmail 就试用吗？
哪些操作支持人工审批？
运行时需要哪些外部凭据？
如何判断回复或工具选择是否正确？
evaluate API，评测回复质量、工具调用与邮件分流决策；回复质量评测包含 LLM-as-a-judge。