用途
AgentMail Toolkit 用于为智能体框架添加 AgentMail 邮件工具，使智能体能够在框架内调用邮件相关能力。它提供 TypeScript 和 Python 两种语言版本，可分别对接不同的智能体框架。
主要能力
- 暴露工具集合：工具包可由构造函数创建并使用 getTools()（TypeScript）或 get_tools()（Python）获取工具列表。
- 运行时发现工具目录：资料强调应在运行时发现已安装包的工具目录，而非信任硬编码列表。示例：TypeScript
new AgentMailToolkit().getTools().map((tool) => tool.name)；Python[tool.name for tool in AgentMailToolkit().get_tools()]。 - 支持已有 SDK 客户端：工具包构造函数只接受一个已有的 SDK 客户端作为参数，不接受 { apiKey } 或 api_key 选项对象，需要先构造 SDK 客户端再传入。
- MCP server 工具：每个工具提供 name、title、description、input schema、output schema、callback 以及完整注解，可用于注册到自建的 MCP server。
- 输出与错误处理：每个工具声明输出 schema。MCP 工具调用成功时返回经过校验的 structuredContent 以及匹配的 JSON 文本块；void 操作（删除）返回稳定的 { success: true } 对象。失败通过各框架原生错误通道表示，而非作为成功结果返回。
使用方式
安装：
npm install agentmail-toolkitpip install agentmail-toolkit并设置环境变量 AGENTMAIL_API_KEY。
TypeScript 适配：
- Vercel AI SDK：
import { AgentMailToolkit } from "agentmail-toolkit/ai-sdk"; - LangChain：
import { AgentMailToolkit } from "agentmail-toolkit/langchain"; - MCP server tools：
import { AgentMailToolkit } from "agentmail-toolkit/mcp"; - Clawdbot：
import { AgentMailToolkit } from "agentmail-toolkit/clawdbot";
Python 适配：
- OpenAI Agents SDK：
from agentmail_toolkit.openai import AgentMailToolkit - LangChain：
from agentmail_toolkit.langchain import AgentMailToolkit - LiveKit Agents：
from agentmail_toolkit.livekit import AgentMailToolkit
使用已有客户端时，先构造 SDK 客户端，再传入工具包构造函数：TypeScript 示例 const client = new AgentMailClient({ apiKey: process.env.AGENTMAIL_API_KEY }); const toolkit = new AgentMailToolkit(client);；Python 示例 client = AgentMail(); toolkit = AgentMailToolkit(client=client)。
LiveKit Agents 用法为继承 LiveKit Agent，并在 super().init 中传入 instructions 与工具包工具。
适用场景
- 在 Vercel AI SDK、LangChain、OpenAI Agents SDK、LiveKit Agents 等智能体框架中加入邮件工具。
- 为自建 MCP server 注册邮件相关工具。
- 在智能体工作流中按需调用邮件能力，并结合框架自身的工具错误处理机制。
限制与注意事项
- TypeScript 与 Python 包可能暴露不同的工具集，且发布节奏可能不同，因此应以运行时发现为准。
- Python 包不提供 MCP adapter。
- 工具包构造函数只接受已有 SDK 客户端作为唯一参数，不接受直接传入 apiKey 或 api_key 选项。
- 错误处理要求：不要把返回值当作错误字符串；应捕获抛出的错误或检查 MCP 的 isError。Vercel AI SDK、LangChain、clawdbot 适配器（以及通用导出）在失败时会抛出错误，MCP adapter 则返回 isError: true。
- 结果与错误相关行为需工具包 TypeScript >= 0.5.0 或 Python >= 0.3.0。
安全建议
- 将工具限制在工作流所需范围内。
- 将邮件内容视为不可信数据。
- 发送、回复、删除、凭据更改及其他外部副作用需获得明确授权。
- 尽可能使用限定范围的 AgentMail 凭据。