LangChain Gmail 工具箱使用指南：邮件查询、发送与管理

6. 创建测试脚本：创建一个名为 quickstart.py 的文件。

import os.path
from google.auth.transport.requests import Request
from google.oauth2.credentials import Credentials
from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError

# 如果修改这些 scopes，请删除 token.json 文件
SCOPES = ["https://www.googleapis.com/auth/gmail.readonly"]

def main():
    """显示 Gmail API 的基本用法。列出用户的 Gmail 标签。"""
    creds = None
    # token.json 文件存储用户的访问和刷新令牌
    if os.path.exists("token.json"):
        creds = Credentials.from_authorized_user_file("token.json", SCOPES)
    
    # 如果没有有效凭证，让用户登录
    if not creds or not creds.valid:
        if creds and creds.expired and creds.refresh_token:
            creds.refresh(Request())
        else:
            flow = InstalledAppFlow.from_client_secrets_file(
                "credentials.json", SCOPES
            )
            creds = flow.run_local_server(port=0)
        # 保存凭证
        with open("token.json", "w") as token:
            token.write(creds.to_json())

    try:
        service = build("gmail", "v1", credentials=creds)
        results = service.users().labels().list(userId="me").execute()
        labels = results.get("labels", [])

        if not labels:
            print("No labels found.")
            return
        print("Labels:")
        for label in labels:
            print(label["name"])

    except HttpError as error:
        print(f"An error occurred: {error}")

if __name__ == "__main__":
    main()

7. 运行脚本：将 credentials.json 文件放到与 quickstart.py 同目录下，执行命令根据密钥生成开发 Token，会自动打开浏览器。

python3 quickstart.py

8. 授予权限：根据提示授予访问权限，最终在目录下生成 token.json 文件。

开发 Gmail App

连接到 Gmail API，查询用户的邮件，并通过 LangChain 的 Agent 框架智能化地调用 API（用语言而不是具体 API），与邮件进行互动。

创建工具包

默认情况下，工具包读取本地 credentials.json 文件。

from langchain_community.agent_toolkits import GmailToolkit

# 初始化 Gmail 工具包
toolkit = GmailToolkit()

自定义身份验证

使用以下方法创建 googleapi 资源。可以手动构建 googleapi 资源以进行更多身份验证控制。

from langchain_community.tools.gmail import get_gmail_credentials
from langchain_community.tools.gmail.utils import build_resource_service

# 获取 Gmail API 的凭证，并指定相关的权限范围
credentials = get_gmail_credentials(
    token_file="token.json",  # Token 文件路径
    scopes=["https://mail.google.com/"],  # 具有完全的邮件访问权限
    client_secrets_file="credentials.json",  # 客户端的秘密文件路径
)
# 使用凭证构建 API 资源服务
api_resource = build_resource_service(credentials=credentials)
toolkit = GmailToolkit(api_resource=api_resource)

# 获取工具
tools = toolkit.get_tools()
print(tools)

输出示例：

[GmailCreateDraft(...), GmailSendMessage(...), GmailSearch(...), GmailGetMessage(...), GmailGetThread(...)]

初始化 Agent

from langchain_openai import ChatOpenAI
from langchain.agents import AgentExecutor, create_openai_functions_agent

# 初始化聊天模型
llm = ChatOpenAI(temperature=0, model='gpt-4')

# 获取要使用的提示
instructions = """You are an assistant."""
base_prompt = hub.pull("langchain-ai/openai-functions-template")
prompt = base_prompt.partial(instructions=instructions)

# 初始化 agent
agent = create_openai_functions_agent(llm, tools, prompt)

# 创建代理执行程序
agent_executor = AgentExecutor(
    agent=agent, tools=tools, verbose=True, handle_parsing_errors=True
)

运行 Agent

查询最新邮件

result = agent_executor.invoke({"input": "未读邮件有几封？最新的邮件是谁发给我的？"})
print(result)

发送邮件

result = agent_executor.invoke({"input": "向邮箱：[email protected] 发送邮件。邮件主题：Gmail Agent Test 邮件内容：进行 Gmail Tools Test."})
print(result)

常见问题处理： 如果在发送邮件时出现 HttpError 403 异常，提示 Insufficient Permission，通常是因为 token.json 生成时的权限范围不足。

检查 quickstart.py 中的 SCOPES 配置：

SCOPES = ["https://www.googleapis.com/auth/gmail.readonly"]

这里只配置了只读权限。为了发送邮件，需要添加发送权限：

SCOPES = [
    "https://www.googleapis.com/auth/gmail.readonly",
    "https://www.googleapis.com/auth/gmail.send"
]

注意：修改后必须删除旧的 token.json 文件，然后重新执行代码生成新的 token.json 文件。

高级功能：删除邮件管理

虽然基础工具包主要展示查询和发送，但通过调整权限范围和调用底层 API，可以实现邮件删除功能。Gmail API 中删除邮件通常涉及将邮件移动到垃圾箱或永久删除。

若需支持删除操作，建议在初始化凭证时添加 gmail.modify 或 gmail.delete 权限：

scopes = [
    "https://www.googleapis.com/auth/gmail.readonly",
    "https://www.googleapis.com/auth/gmail.send",
    "https://www.googleapis.com/auth/gmail.modify"  # 允许修改邮件状态，包括删除
]

在 Agent 指令中，可以直接使用自然语言要求删除特定邮件，例如：

result = agent_executor.invoke({"input": "查找发件人为 [email protected] 的邮件并将其删除"})

Agent 会根据意图调用相应的工具链完成搜索和标记删除的操作。

注意事项与最佳实践

1. TimeoutError 处理

异常日志：

TimeoutError: [WinError 10060] 由于连接方在一段时间后没有正确答复...

分析： Gmail API 调用需要访问 Google 服务器，网络波动可能导致超时。如果使用国内环境，建议配置代理。 解决方案：

• 开启系统级 Proxy 的 Tun 模式。
• 在代码层面配置 google.auth.transport.requests 的 proxy 参数。

2. SCOPES 权限不足

在执行相关命令时，可能出现权限不足的问题。此时需要查看添加权限信息，并在生成 Token 的代码文件的 SCOPES 中添加相应权限，然后删除 token.json，再次授权生成。

3. Token 限制与上下文长度

在使用 Agent 执行指令时，最好添加限制约束，否则将出现 Token 上限问题。例如 OpenAI 模型的上下文长度限制。

错误示例：

openai.BadRequestError: Error code: 400 - {'error': {'message': "This model's maximum context length is 8192 tokens..."}}

优化建议：

• 限制查询邮件的数量（如只查最近 5 封）。
• 对长邮件内容进行摘要后再发送给 Agent。
• 使用支持更长上下文的模型版本。

4. 安全最佳实践

• 凭证保护：切勿将 credentials.json 和 token.json 上传至公共代码仓库。应在 .gitignore 中排除这些文件。
• 最小权限原则：仅申请必要的 API 权限。例如，如果不需要发送邮件，就不要添加 gmail.send 权限。
• 环境变量：敏感配置建议使用环境变量管理，避免硬编码。

总结

本文详细介绍了如何使用 LangChain 的 Gmail 工具箱实现邮件自动化管理。内容包括 Gmail API 配置、OAuth 权限设置、工具包初始化及 Agent 创建。通过示例演示了查询邮件、发送邮件及处理常见异常如权限不足和超时问题的方法。同时补充了关于邮件删除的高级配置及安全最佳实践，帮助开发者构建稳定可靠的智能邮件代理应用。