基于 HelloAgents 框架构建智能邮件助手 EmailSmartAssistant：自动分类、回复生成与智能提醒全流程实战

基于 HelloAgents 框架构建智能邮件助手 EmailSmartAssistant自动分类、回复生成与智能提醒全流程实战【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/datawhalechina/hello-agents本文聚焦 Datawhale《从零开始构建智能体》共创项目中的 EmailSmartAssistant 智能邮件助手完整讲解一个基于 Python 与 HelloAgentsReAct 范式的邮件自动化处理系统如何实现邮件自动分类、多语言回复草稿生成、关键信息提取与智能提醒以及如何通过分类 → 提取 → 回复 → 提醒四步流水线将零散邮件变成结构化处理结果。读完本文你将掌握邮箱配置参数、规则引擎分类算法、模板化回复生成与 HelloAgents 工具化智能体Tool / BaseTool / ToolRegistry / SimpleAgent的完整落地写法可直接复用于邮件、工单、客服消息等文本自动化场景。一、项目概述解决什么提供什么1.1 要解决的问题现代职场与个人生活中邮件处理存在四类典型痛点项目在 README 中将其归纳为筛选耗时大量邮件堆积人工筛选分类费力回复费力针对不同场景撰写回复需要额外精力措辞难以兼顾专业性与语气跟进易漏重要邮件的跟进事项、截止时间常因疏忽而延误信息分散关键信息散落在邮件中难以快速提取和整理。1.2 提供的核心能力项目围绕上述痛点提供了六项已实现的功能README 中标记为[x]功能说明邮件智能分类按类型work/customer/personal/spam/other、优先级high/medium/low、发件人类型colleague/system/customer/external自动分类智能回复生成根据邮件语义与场景生成个性化回复草稿支持中英文与正式/非正式语气关键信息提取自动提取日期、时间、联系方式手机号/邮箱、待办事项智能提醒系统基于提取的时间信息创建个性化提醒支持多种提前时间设置可视化报告生成邮件处理统计图表与结构化摘要报告多邮箱支持兼容 Gmail、Outlook、QQ 邮箱等主流邮箱服务1.3 适用场景企业办公邮件管理、客户服务邮件处理、个人邮箱整理、项目协作邮件跟进。二、技术架构与整体工作流2.1 技术栈一览根据 requirements.txt 与 README 的说明项目的技术选型如下智能体框架hello-agents[all]0.1.0ReAct 范式对应 HelloAgents 框架版本邮件协议imaplib / smtplib / email标准库imaplib2、email-validatorNLPjieba中文分词、TextBlob、langdetect语言检测机器学习scikit-learn、sentence-transformers、transformers用于分类与相似度扩展数据处理pandas、numpy可视化matplotlib、seaborn、plotly模板渲染Jinja2reply_templates.json中{{subject}}风格变量即由 Jinja2 渲染时间处理dateparser、arrow、python-dateutil交互与输出Jupyter Notebook、rich终端面板/表格美化、tqdm进度条。2.2 四步处理流水线从 demo.py 的run_demo与 HelloAgents Notebook 的实现看每封邮件的处理流程是一致的四步分类classify_email/EmailClassifierTool判断类型、优先级、发件人类型提取extract_info/InformationExtractorTool用正则提取日期、时间、电话、邮箱、待办回复generate_reply/ReplyGeneratorTool检测语言后选择模板生成草稿提醒ReminderCreatorTool/ReminderManager基于日期与待办生成提醒。2.3 两种运行形态仓库同时提供了两条实现路线供不同需求选用脚本/Notebook 直跑demo.py零配置演示、EmailSmartAssistant.ipynb原始完整版含 imaplib/smtplib 真实邮件收发、email_assistant.py配置/模板校验脚本HelloAgents 智能体版EmailSmartAssistant_HelloAgents.ipynb基于SimpleAgent 四个BaseTool与 main.ipynb基于ToolRegistry/Tool/ToolParameter的进阶版支持通过 LLM 环境变量接入 ModelScope 上的 Qwen 模型。三、快速开始从零配置到运行3.1 环境要求Python 3.8requirements.txt中如scikit-learn1.3.2对 Python 版本有下限要求Jupyter Notebook支持 IMAP/SMTP 的邮箱账户可选演示模式不需要。3.2 安装依赖pip install -r requirements.txt若 pip 安装失败README 提供了两条替代方案# 使用 conda 安装核心科学计算库后补齐其余依赖 conda install pandas numpy matplotlib seaborn pip install -r requirements.txt # 或使用清华源加速 pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple/安装完成后建议先运行 test_installation.py 做一次环境体检该脚本会逐一import17 个核心库imaplib、smtplib、jieba、textblob、langdetect、sklearn、dateparser、arrow、jinja2、matplotlib、seaborn、tqdm、rich 等并校验config/email_config.json、templates/reply_templates.json、EmailSmartAssistant.ipynb、requirements.txt、README.md等关键文件是否存在最后用 Rich 表格汇总输出导入成功 n/17文件完整 n/5。3.3 零配置体验演示无需配置邮箱即可体验全部功能这是项目零配置演示亮点的体现# 推荐运行简化演示 python demo.pydemo.py内置了 6 封覆盖典型场景的演示邮件工作会议、客户咨询、系统维护、促销广告、个人聚餐、英文紧急会议输出示例如下 智能邮件助手 - 演示版本 演示邮件数量: 6 处理邮件 1/6: 紧急项目进度汇报会议安排... 处理邮件 2/6: 客户咨询产品功能详情... ... ✅ 处理完成 处理统计: 总邮件数: 6 已分类: 6 生成回复: 5 创建提醒: 8 分类统计: work: 2 customer: 1 personal: 1 spam: 1 other: 13.4 运行 Notebook 版本jupyter notebook选择以下版本之一运行EmailSmartAssistant.ipynb原始完整版本含 imaplib/smtplib 真实邮件收发、Jinja2 模板渲染、提醒管理器与可视化报告EmailSmartAssistant_HelloAgents.ipynbHelloAgents 框架版本将四个功能封装为工具交给SimpleAgent编排main.ipynb进阶版通过ToolRegistry注册Tool带ToolParameter参数声明并通过环境变量接入 ModelScope API。四、邮箱配置详解email_config.json 全字段说明真实邮件处理依赖配置文件 config/email_config.json。该文件由五大部分组成下面的注释版即为仓库中的完整模板{ email_accounts: [ { name: 主邮箱, email: your_emailexample.com, password: your_app_password, imap_server: imap.example.com, imap_port: 993, smtp_server: smtp.example.com, smtp_port: 587, use_ssl: true } ], classification_rules: { work_keywords: [会议, 项目, 工作, 任务, 汇报, meeting, project, work, task], customer_keywords: [客户, 咨询, 购买, 服务, customer, inquiry, purchase, service], personal_keywords: [个人, 家庭, 朋友, personal, family, friend], spam_keywords: [广告, 推广, 营销, advertisement, promotion, marketing] }, priority_rules: { high_priority_senders: [bosscompany.com, importantclient.com], high_priority_keywords: [紧急, urgent, asap, 重要, important], low_priority_keywords: [通知, newsletter, notification, 订阅] }, reply_settings: { formal_tone: true, include_signature: true, auto_cc: [], default_language: zh-CN }, reminder_settings: { advance_days: [1, 3, 7], notification_methods: [email, console], working_hours: { start: 09:00, end: 18:00 } } }4.1 各配置块的作用email_accounts邮箱账户列表支持多邮箱其中use_ssl控制 IMAP/SMTP 是否走 SSL 加密连接imap_port: 993/smtp_port: 587为常见安全端口classification_rules四组关键词工作/客户/个人/垃圾是规则引擎分类的核心输入。从 main.ipynb 的EmailClassificationTool可以看到配置文件缺失时会回退到内置默认关键词如 work 默认词还会追加urgentspam 默认词追加折扣priority_ruleshigh_priority_senders支持按发件人白名单直接判高优先级high/low_priority_keywords则按正文关键词判定reply_settingsformal_tone正式/非正式语气开关对应模板中的 formal/casual 两套文案、include_signature是否附加签名、auto_cc自动抄送列表、default_language默认语言reminder_settingsadvance_days: [1, 3, 7]表示对同一关键日期分别提前 1 天、3 天、7 天创建提醒见ReminderManager.create_reminders的循环逻辑notification_methods支持 email/console 两种通知方式working_hours限定工作时段。4.2 主流邮箱服务器参数README 给出的常见邮箱配置表邮箱服务IMAP服务器IMAP端口SMTP服务器SMTP端口Gmailimap.gmail.com993smtp.gmail.com587Outlookoutlook.office365.com993smtp.office365.com587QQ邮箱imap.qq.com993smtp.qq.com5874.3 安全建议README 原话要点使用应用专用密码不要使用邮箱登录密码而是生成应用专用密码保护配置文件不要将包含密码的配置文件提交到版本控制系统网络安全确保在安全的网络环境下运行程序。应用专用密码设置路径Gmail 在Google 账户 → 安全性 → 应用专用密码Outlook 在Microsoft 账户 → 安全性 → 应用密码QQ 邮箱需在邮箱设置 → 账户中先开启 IMAP/SMTP 服务。五、核心功能源码级剖析5.1 邮件智能分类关键词打分规则引擎分类逻辑在 demo.py 的classify_email、HelloAgents 版的EmailClassifierTool._classify_email、main.ipynb 的EmailClassificationTool.run中三处实现基本一致核心思想是关键词计分 规则判定拼接subject body为text_content并转小写垃圾邮件优先统计spam_keywords命中数若spam_score 2直接判为spam优先级 low、发件人类型 external演示邮件 4限时优惠立即购买享受8折优惠即因此被正确拦截且垃圾邮件不生成回复类型计分分别统计 work/customer/personal 三类关键词命中数取得分最高者若全部为 0 则归为other优先级命中紧急/urgent/asap/重要等词判 high命中通知/newsletter/notification/订阅判 low否则 medium垃圾邮件强制 lowmain.ipynb 中优先级判定严格区分高/低两级关键词默认 medium发件人类型按域名规则推断——含company.com/corp.com判 colleaguenoreply/no-reply判 system客户邮件判 customer否则 external。分类结果示例README 原文{ type: work, # 工作邮件 priority: high, # 高优先级 sender_type: colleague # 同事发送 }5.2 关键信息提取多模式正则 语义句子筛选extract_info/InformationExtractorTool通过正则模式覆盖常见格式日期\d{4}-\d{1,2}-\d{1,2}2024-01-15、\d{1,2}月\d{1,2}日1月15日、\d{1,2}/\d{1,2}、\d{1,2}-\d{1,2}时间\d{1,2}:\d{2}14:30、\d{1,2}点\d{0,2}分?2点30分、\d{1,2}\s*PM/AM联系方式手机号1[3-9]\d{9}中国大陆格式、邮箱[A-Za-z0-9._%-]...待办事项将正文按。.!切句筛选包含需要/请/准备/need/please/prepare/确认/完成/提交且长度 5 的句子上限取 5 条demo.py 中为 3 条。提取结果通过list(set(...))去重后以 JSON 返回作为回复生成与提醒创建的数据输入。5.3 智能回复生成语言检测 场景模板回复生成是多语言、多场景、个性化的核心实现要点见generate_reply与ReplyGenerator语言检测优先用langdetect.detect()失败时回退到 Unicode 中文字符范围判断\u4e00 char \u9fffdemo.py 中直接用中文字符检测简化实现场景映射work →work_meetingcustomer →customer_inquiry其余 →general_acknowledgmentspam 不生成回复模板渲染原始版EmailSmartAssistant.ipynb使用 Jinja2Template.render()填充subject、timeframe默认 24 小时、return_date、emergency_contact等变量并支持 formal/casual 语气切换由reply_settings.formal_tone决定HelloAgents 版使用str.format(subject...)简化实现输出结构统一返回{to, subject(带Re: 前缀), content, language, template_type, tone}。回复草稿示例README 原文{ to: managercompany.com, subject: Re: 紧急项目进度汇报会议安排, content: 感谢您的邮件。关于紧急项目进度汇报会议安排我已收到您的信息。我将在24小时内回复您详细的反馈..., language: zh, template_type: work }模板库 templates/reply_templates.json 提供了四类场景 × 正式/非正式 × 中/英文的完整文案矩阵模板键场景可用语气work_meeting工作/会议formal、casualcustomer_inquiry客户咨询formalgeneral_acknowledgment通用确认formal、casualout_of_office休假自动回复含return_date、emergency_contact占位变量formal以work_meeting.casual.zh为例其文案为收到关于{{subject}}的事情我看到了{{timeframe}}内给你回复。有急事随时找我。——这正是场景化回复与多语言智能亮点的直接体现。5.4 智能提醒日期提前提醒 待办即时提醒提醒模块存在两档实现HelloAgents 版ReminderCreatorTool._create_reminders仅对 high/medium 优先级邮件创建提醒对%Y-%m-%d格式日期解析后提前 1 天生成date_reminder对每个待办事项生成 2 小时后的todo_reminder消息模板为提醒{主题} - 明天到期{日期}完整版ReminderManager.create_reminders对每个关键日期按reminder_settings.advance_days1/3/7 天批量生成多条提醒仅保留未来的提醒并为每条提醒分配唯一 ID{email_id}_{date}_{advance_days}、维护pending/sent状态机支持get_pending_reminders、mark_reminder_sent、get_reminders_summary。六、HelloAgents 智能体化把四步流水线变成四个工具这是项目区别于普通脚本的核心亮点——使用 HelloAgents 框架将邮件处理升级为可由 LLM 编排的 ReAct 智能体。以 EmailSmartAssistant_HelloAgents.ipynb 为例完整链路如下。6.1 导入框架组件from hello_agents import SimpleAgent, HelloAgentsLLM from hello_agents.tools import BaseTool6.2 定义四个工具每个功能一个BaseTool子类工具的统一契约是类属性name工具名description给 LLM 看的说明以及run(self, email_data: str) - str执行方法入参/出参均约定为 JSON 字符串。四个工具分别对应流水线四步email_classifier接收邮件 JSON返回分类结果 JSONinformation_extractor接收邮件 JSON返回提取的关键信息 JSONreply_generator接收{email, classification}返回回复草稿 JSONreminder_creator接收{email, classification, extracted_info}返回提醒列表 JSON。关键设计工具之间通过统一的 JSON 数据格式传递结果MockAgent._mock_process中可以看到典型的串联方式——先调用分类工具拿到classification_result再连同邮件 JSON 组装成reply_input传给回复工具最后把三类结果合并传给提醒工具保证四步流程的连贯性。6.3 创建智能体并注入工具system_prompt 你是一个专业的邮件处理助手具备以下能力 1. 邮件分类能够准确识别邮件类型工作、客户、个人、垃圾邮件和优先级 2. 信息提取从邮件中提取关键信息如日期、时间、联系方式、待办事项 3. 回复生成根据邮件内容和分类生成合适的回复草稿 4. 提醒创建基于提取的信息创建智能提醒 处理邮件时请按以下步骤进行 1. 首先使用email_classifier工具对邮件进行分类 2. 然后使用information_extractor工具提取关键信息 3. 根据分类结果使用reply_generator工具生成回复草稿 4. 最后使用reminder_creator工具创建相应的提醒 llm HelloAgentsLLM(model_namegpt-3.5-turbo, temperature0.1) agent SimpleAgent(name智能邮件助手, llmllm, system_promptsystem_prompt) agent.add_tool(EmailClassifierTool()) agent.add_tool(InformationExtractorTool()) agent.add_tool(ReplyGeneratorTool()) agent.add_tool(ReminderCreatorTool())temperature0.1的设置保证了输出确定性适合邮件处理这类需要稳定的任务。6.4 无 LLM 环境的 MockAgent 兜底该 Notebook 内置了一个MockAgent当HelloAgentsLLM初始化失败时自动降级为规则直调按分类 → 提取 → 回复 → 提醒的顺序依次调用已注册工具并拼接结果。这意味着即使没有 API Key 也能完整演示整个工具链路体现了零配置演示的工程思想。6.5 main.ipynbToolRegistry 进阶写法与 ModelScope 接入main.ipynb 展示了另一套更贴近 HelloAgents 进阶用法的 APIfrom hello_agents import SimpleAgent, HelloAgentsLLM, ToolRegistry from hello_agents.tools import Tool, ToolParameter # 通过环境变量配置 LLMModelScope 上的 Qwen2.5-72B-Instruct os.environ[LLM_MODEL_ID] Qwen/Qwen2.5-72B-Instruct os.environ[LLM_API_KEY] your_api_key_here os.environ[LLM_BASE_URL] https://api-inference.modelscope.cn/v1/ os.environ[LLM_TIMEOUT] 60 tool_registry ToolRegistry() tool_registry.register_tool(EmailClassificationTool()) tool_registry.register_tool(InfoExtractionTool()) tool_registry.register_tool(ReplyGenerationTool()) agent SimpleAgent(name智能邮件助手, llmllm, system_promptsystem_prompt, tool_registrytool_registry)与上一版相比有三个升级点参数声明机制每个Tool通过get_parameters()返回ToolParameter(name, type, description, required)列表向 LLM 显式描述工具入参如sender为必填、subject/body为选填提升工具调用的可靠性工具注册表ToolRegistry.register_tool()统一管理工具集合与SimpleAgent通过tool_registry参数绑定LLM 可配置化通过LLM_MODEL_ID/LLM_API_KEY/LLM_BASE_URL/LLM_TIMEOUT四个环境变量接入 ModelScope 推理服务也可替换为其他兼容 OpenAI 协议的模型。七、运行示例与结果解读7.1 三类典型邮件处理HelloAgents Notebook 提供了三个示例示例 1 基础演示输入演示邮件处理功能MockAgent 自动使用内置演示邮件走完整流程示例 2 客户咨询输入包含产品咨询与演示预约诉求的客户邮件 JSON返回客户分类、联系方式提取与客户场景回复草稿示例 3 英文邮件输入 Urgent: Quarterly Report Meeting验证英文分类urgent → high 优先级与英文模板回复示例 4 批量处理三封邮件系统维护/促销广告/周末聚餐批量处理并用 RichTable输出 work/customer/personal/spam/other 分布统计。7.2 报告生成main.ipynb在处理完成后会自动将结果写入output/reports/email_processing_report_{timestamp}.md仓库中 output 目录 预置了reports/与drafts/两个输出子目录报告包含生成时间、处理邮件数、成功/失败数以及每封邮件的处理详情。7.3 性能评估Notebook 内置了一个可选性能评估单元使用 5 封带预期分类的测试邮件通过time.time()统计总处理时间与单封平均耗时并计算分类准确率最终以表格形式输出总处理邮件数 / 分类准确率 / 总处理时间 / 平均处理时间 / 处理速度。README 基于演示数据给出的效果统计为分类准确率 95%基于关键词匹配和规则引擎、信息提取率 90%、回复生成成功率 100%非垃圾邮件、平均处理时间 1 秒/封。这些数据来自内置演示数据集的规则引擎表现可将其视为项目自述的基准参考而非通用性承诺。八、项目结构与二次开发指南8.1 目录结构README 原文整理EmailSmartAssistant/ ├── EmailSmartAssistant.ipynb # 原始完整版本 ├── EmailSmartAssistant_HelloAgents.ipynb # HelloAgents框架版本 ├── demo.py # 简化演示脚本 ├── email_assistant.py # Python脚本版本 ├── test_installation.py # 安装测试脚本 ├── requirements.txt # 依赖列表 ├── README.md # 项目说明 ├── .env.example # 环境变量示例 ├── config/ # 配置文件目录 │ └── email_config.json # 邮箱配置模板 ├── templates/ # 回复模板目录 │ └── reply_templates.json # 回复模板 └── output/ # 输出目录 ├── reports/ # 处理报告 └── drafts/ # 回复草稿8.2 扩展点提示由代码结构推断分类规则直接在config/email_config.json的classification_rules/priority_rules中增删关键词即可无需改代码main.ipynb 的EmailClassificationTool会在启动时自动加载该文件回复模板向templates/reply_templates.json增加新场景键如out_of_office并在ReplyGenerator.select_template的映射逻辑中补充对应关系新增工具HelloAgents 版只需继承BaseTool实现name/description/run三要素后agent.add_tool()多邮箱email_accounts是数组可追加多个账户条目。九、故障排查9.1 连接失败按 README 的清单逐项检查邮箱服务器地址和端口是否正确对照第 4.2 节表格是否已开启 IMAP/SMTP 服务QQ 邮箱等需在网页端手动开启应用专用密码是否正确而非登录密码防火墙和网络连接是否正常。9.2 依赖安装问题优先使用 conda 安装科学计算栈或切换清华源详见 3.2 节安装后务必运行test_installation.py定位缺失库。也可以先运行 email_assistant.py 做快速校验——它会尝试加载配置文件与模板文件并打印邮箱账户数、分类规则数、回复模板数等摘要信息。9.3 LLM 调用异常HelloAgents Notebook 已内置兜底LLM 创建失败时自动降级为MockAgent规则直调不影响四步流水线的演示。接入真实模型时需确认LLM_BASE_URL、LLM_API_KEY、LLM_MODEL_ID与模型服务商配置一致并适当调大LLM_TIMEOUT。十、总结与展望EmailSmartAssistant 完整演示了从规则引擎到 LLM 编排的邮件处理进阶路径底层用关键词打分与正则提取保证确定的分类与信息抽取能力上层用 HelloAgents 的SimpleAgentTool/BaseTool将能力封装为可被 LLM 推理编排的工具配合 JSON 数据契约实现多工具无缝串联。其零配置演示、模块化工具、多语言模板、应用专用密码安全实践等设计对构建客服工单系统、消息聚合助手等同类文本处理 Agent 具有直接的参考价值。README 与 Notebook 中列出的未来方向包括集成 BERT/GPT 等预训练模型提升分类与提取精度、情感分析驱动语气调整、用户确认后自动发送、日历集成会议自动上日历、团队共享规则模板、RESTful API 与企业级部署、移动端与实时邮件监控等——这些都为后续迭代保留了清晰的扩展路径。【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/datawhalechina/hello-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考