AgentMailRetriever 对 AgentMail 收件箱执行关键词搜索。它通过以下方式加载最近的消息 AgentMailLoader，在进程中对它们进行不区分大小写的子字符串匹配评分（主题命中加权 2×），并返回前k 作为 LangChain Document结果。如需语义搜索，请将 AgentMailLoader 与您自己的向量存储配合使用。

概览

设置

安装包：

pip install -qU langchain-agentmail

设置您的 AgentMail API 密钥（在 agentmail.to):

if not os.environ.get("AGENTMAIL_API_KEY"):
    os.environ["AGENTMAIL_API_KEY"] = getpass.getpass("AgentMail API key:\n")

实例化

from langchain_agentmail import AgentMailRetriever

retriever = AgentMailRetriever(
    inbox_id="ib_abc123",
    k=5,              # number of documents to return
    labels=["inbox"], # optional — filter messages by label
    scan_limit=50,    # number of messages to scan before ranking
)

使用方法

docs = retriever.invoke("invoice from acme")
for doc in docs:
    print(doc.metadata["subject"], "—", doc.metadata.get("from"))

检索器返回相同的 Document 格式为 AgentMailLoader —— 完整纯文本正文在 page_content, plus inbox/message/thread/sender metadata.

何时使用加载器

AgentMailRetriever 是“给我匹配 X 的最近消息”的应急方案——无需嵌入，无需向量存储。如果您需要语义检索、按相关性排序或跨数百万条消息进行筛选，请使用 AgentMailLoader 来实例化 Document并将其馈送到真正的向量存储中。请参阅 文档加载器页面 了解该流程。

API 参考

包源代码位于 github.com/agentmail-to/langchain-agentmail.