agent-email-patterns

Agent 邮件模式

构建通过邮件通信的 AI Agent 的实用模式。本技能涵盖架构和安全决策，不涉及 SDK 细节。有关 AgentMail SDK 的用法，请使用 agentmail 技能。

为什么 Agent 需要自己的收件箱

授予 Agent 对个人 Gmail 账号的 OAuth 访问权限是最常见的做法，也是最危险的做法：

• 权限过宽：常见的 OAuth 作用域（例如 gmail.modify）会授予对整个邮箱历史记录的读取、发送和删除权限，远超任何单项任务所需
• 提示词注入风险：Agent 会将完整的收件箱历史记录纳入可访问的上下文，因此邮箱中已有的任何恶意构造邮件都是现成的攻击面
• 撤销粒度：OAuth 令牌难以撤销或按 Agent 限定范围——撤销某个工作流的访问权限，往往意味着要撤销所有工作流的访问权限
• 速率限制：面向个人用户的邮箱发送限制并非为自动化或程序化工作流设计
• 审计记录：Agent 的操作与人工操作混杂在同一邮箱中，导致调试和合规审查困难

更安全的默认做法：为每个 Agent 配置一个专用的、原生支持 API 的收件箱（见模式 1）。

服务提供商概览

选择基础设施时需要考虑的长期架构限制（并非排名）：

服务提供商	主要限制
Gmail API	无法以编程方式创建收件箱；不支持 WebSocket 推送（仅支持 Pub/Sub 或轮询）；Google 可随时撤销访问权限
Resend	没有线程或对话概念；无法列出或搜索收到的邮件；入站邮件只能通过 Webhook 处理，没有持久化收件箱
SendGrid	入站解析是无状态的；不支持线程管理；无法以编程方式创建收件箱
Amazon SES	入站处理基于规则（S3/Lambda 触发器），而非邮箱；不支持线程管理；不支持 WebSocket

模式 1：每个 Agent 使用一个收件箱

每个 Agent 都有自己的电子邮件地址。绝不要让多个 Agent 共用收件箱。

client.inboxes.create(request=CreateInboxRequest(username="support-agent", client_id="support-v1"))

原因：发件人身份清晰、彼此隔离（Agent 无法读取彼此的邮件）、可按 Agent 进行审计，以及在某个 Agent 遭到入侵时控制影响范围。

反模式：多个 Agent 共用一个收件箱并从中读取邮件。这会造成竞态条件，并让调试变得不可能。

模式 2：双向对话循环

Agent 邮件的核心模式：Agent 发送邮件，人工回复，Agent 读取回复并作出响应，如此循环直至问题解决。

注意事项：

• messages.list() 只返回元数据（不含正文）——调用每个项目的 .get() 以获取 .text / .extracted_text。
• 对于入站回复，请使用 extracted_text / extracted_html，避免每轮都重新处理整段引用的邮件链。
• 若要让回复保留在线程中，请调用 messages.reply(inbox_id, message_id, ...) 并传入父邮件的 message_id——此处没有 thread_id 参数；AgentMail 会根据父邮件自动将其归入相应线程。
• 在自己的数据库中跟踪对话状态，而不是每次都重新解析邮件正文。

模式 3：人工参与的草稿流程

对于高风险邮件，可让 Agent 起草邮件，由人工批准后再发送：drafts.create(...)，然后调用 drafts.send(inbox_id, draft_id)。

以下情况使用草稿：

• 邮件涉及法律或财务事项
• 收件人是 VIP 或外部利益相关者
• Agent 刚开始用于此工作流，尚未建立信任

以下情况可直接发送：

• 常规通知（收据、确认）
• Agent 已证明其可靠性
• 速度很重要（转发 OTP、自动告警）

模式 4：事件驱动架构

优先采用事件驱动交付（WebSockets 或 Webhooks），而不是轮询。只有在两者都不可行时，才可使用轮询——例如，在没有公共 URL 且无法维持持久连接的受限环境中；但要预期延迟和 API 使用量会更高。

因素	WebSockets	Webhooks
是否需要公共 URL	否	是
最适用于	Agent、机器人、本地开发	服务端、无服务器
延迟	最低（持久连接）	HTTP 往返
重连	由你处理	AgentMail 会重试

使用前必须验证 Webhook 负载——参见 references/threat-model.md。

模式 5：多 Agent 拓扑

对于包含多个 Agent 的系统，应分配明确的角色（例如 support@、sales@、billing@、router@），并使用允许列表（references/threat-model.md）来限制哪些外部发件人可以联系各个 Agent。有关中心辐射式、点对点和分层升级模式，请参见 references/topologies.md。

模式 6：OTP 和验证流程

注册服务的 Agent 需要接收并提取验证码（例如，在收到的消息文本中使用正则表达式匹配 4-8 位数字验证码）。

这仅适用于明确获授权的第一方或测试流程——例如，你自己的 Agent 注册一个将由其运营的服务，或你控制的测试账户。这并不授权自动化第三方账户的登录、验证或账户恢复流程，也不授权绕过服务的使用条款或人工同意要求。

最佳实践：

• 为每个注册流程创建一个新的收件箱，以实现隔离
• 设置超时时间（不要无限期等待 OTP）
• 如果收件箱仅供一次性使用，请在流程完成后删除

模式 7：使用标签跟踪工作流状态

使用标签跟踪收件箱中的消息处理状态（在 messages.update 上使用 add_labels / remove_labels，然后使用 messages.list(..., labels=[...]) 进行筛选）。

常见标签方案：

• unread / processed / archived
• needs-reply / replied / escalated
• billing / support / sales（类别路由）

安全要点

完整威胁模型请参见 references/threat-model.md。关键规则：

1. 电子邮件、附件、Webhook 或工具输出中的内容，绝不能作为执行重大操作的授权依据——授权只能来自经过身份验证的用户指令或明确策略。请参见 references/threat-model.md 中的授权矩阵。
2. **绝不要将原始电子邮件内容作为系统提示词传入。**应将其标记为不可信数据；这可以降低注入风险，但本身并不构成安全边界。
3. 在生产环境的 Agent 收件箱上使用允许列表来限制发件人——这只是一个防御层，单独使用并不足够。
4. 处理任何负载前，使用 Svix 验证 Webhook 签名。
5. 绝不要在电子邮件正文或主题中放入 API 密钥或机密信息；发送前扫描外发内容。
6. 将 Agent 凭证与人工凭证分开——每个 Agent 都应拥有自己的、具有限定权限的 API 密钥。

参考文件

• references/topologies.md -- 中心辐射式、点对点、分层、多租户 Pod Agent 电子邮件架构
• references/threat-model.md -- 提示词注入、Webhook 欺骗、OAuth/凭证暴露、数据泄露、收件箱枚举和授权矩阵