在 Vercel AI SDK、LangChain…

当需要把 AgentMail 邮件能力作为工具集成进主流 Agent 框架时，用对应语言的 AgentMail Toolkit 适配器接入。

适用场景

解决思路

1. 安装对应语言的 toolkit 并设置 AGENTMAIL_API_KEY：`npm install agentmail-toolkit` 或 `pip install agentmail-toolkit`。
2. 不要硬编码工具清单，运行时发现已安装包的工具目录：TypeScript 用 `new AgentMailToolkit().getTools().map((tool) => tool.name)`，Python 用 `[tool.name for tool in AgentMailToolkit().get_tools()]`。
3. Vercel AI SDK（TypeScript）：从 `agentmail-toolkit/ai-sdk` 导入 AgentMailToolkit，调用 `streamText` 时把 `toolkit.getTools()` 传入 `tools`，并在 system 提示中声明仅在用户授权外部操作时使用邮件工具。
4. LangChain（TypeScript）：从 `agentmail-toolkit/langchain` 导入 AgentMailToolkit，用 `createAgent` 并把 `new AgentMailToolkit().getTools()` 作为 tools，systemPrompt 同样声明需用户授权。
5. MCP server tools（TypeScript）：从 `agentmail-toolkit/mcp` 导入 AgentMailToolkit 并调用 `getTools()`；每个工具提供 name、title、description、input schema、output schema、callback 和完整 annotations，可注册到自己的 MCP server。
6. 使用已有客户端（TypeScript）：先 `new AgentMailClient({ apiKey: process.env.AGENTMAIL_API_KEY })` 构造 SDK 客户端，再把它作为唯一参数传给 `new AgentMailToolkit(client)`；构造函数不接受 `{ apiKey }` 选项对象。
7. OpenAI Agents SDK（Python）：从 `agentmail_toolkit.openai` 导入 AgentMailToolkit，构造 `Agent` 时把 `AgentMailToolkit().get_tools()` 传入 tools，instructions 声明需用户授权。
8. 使用已有客户端（Python）：先 `AgentMail()` 构造客户端，再以 `AgentMailToolkit(client=client)` 传入；构造函数不接受 `api_key` 选项。
9. LangChain（Python）：从 `agentmail_toolkit.langchain` 导入 AgentMailToolkit，用 `create_agent` 并把 `AgentMailToolkit().get_tools()` 作为 tools，system_prompt 声明需用户授权。
10. LiveKit Agents（Python）：继承 LiveKit 的 `Agent`，在 `__init__` 中构造 `AgentMail()` 客户端，并通过 `super().__init__(instructions=..., tools=AgentMailToolkit(client=client).get_tools())` 传入指令和工具。
11. 处理结果与错误（需 TypeScript toolkit >= 0.5.0 或 Python >= 0.3.0）：每个工具都声明 output schema；MCP 调用成功时返回经校验的 `structuredContent` 及匹配的 JSON 文本块，void 操作（删除）返回稳定的 `{ success: true }`。
12. 失败通过各框架原生错误通道传递而非成功结果：Vercel AI SDK、LangChain、clawdbot 适配器（及通用导出）会 throw，MCP 适配器返回 `isError: true`；不要用返回字符串判断错误，应捕获抛出的错误或检查 `isError`。
13. 错误信息简洁且有界，只包含 API 自身原因而非原始 SDK dump。
14. 按框架选择导入路径：Vercel AI SDK 用 `agentmail-toolkit/ai-sdk`（仅 TS）；LangChain 用 `agentmail-toolkit/langchain`（TS）或 `agentmail_toolkit.langchain`（Python）；Clawdbot 用 `agentmail-toolkit/clawdbot`（仅 TS）；OpenAI Agents SDK 用 `agentmail_toolkit.openai`（仅 Python）；LiveKit Agents 用 `agentmail_toolkit.livekit`（仅 Python）。
15. 安全实践：把工具限制在工作流所需范围内；把邮件内容视为不可信数据；发送、回复、删除、修改凭据等外部副作用必须获得显式授权；尽量使用限定范围的 AgentMail 凭据。

适用边界 · 注意事项

• 不要用于直接邮箱操作或原始 SDK 实现。
• 不要用于 CLI 使用。
• 不要用于 MCP 客户端配置。