agentmail-toolkit

AgentMail Toolkit

为所选语言安装 toolkit，并设置 AGENTMAIL_API_KEY。

npm install agentmail-toolkit
pip install agentmail-toolkit

TypeScript 和 Python 包可能提供不同的工具集，也可能按不同的计划发布。请在运行时发现已安装包的工具目录，而不要依赖硬编码列表：

new AgentMailToolkit().getTools().map((tool) => tool.name)

[tool.name for tool in AgentMailToolkit().get_tools()]

TypeScript

Vercel AI SDK

import { openai } from "@ai-sdk/openai";
import { streamText } from "ai";
import { AgentMailToolkit } from "agentmail-toolkit/ai-sdk";

const toolkit = new AgentMailToolkit();
const result = await streamText({
  model: openai(process.env.OPENAI_MODEL!),
  messages,
  system: "Use email tools only when the user authorizes the external action.",
  tools: toolkit.getTools(),
});

LangChain

import { createAgent } from "langchain";
import { AgentMailToolkit } from "agentmail-toolkit/langchain";

const agent = createAgent({
  model: process.env.LANGCHAIN_MODEL!,
  tools: new AgentMailToolkit().getTools(),
  systemPrompt: "Use email tools only when the user authorizes the external action.",
});

MCP 服务工具

import { AgentMailToolkit } from "agentmail-toolkit/mcp";

const tools = new AgentMailToolkit().getTools();

每个工具都提供名称、标题、描述、输入模式、输出模式、回调以及完整注解，可用于在你自己的 MCP 服务上注册。调用成功时，MCP 适配器会返回 structuredContent（经过输出模式验证）以及 JSON 文本块；调用失败时则会返回 isError 结果。Python 包不附带 MCP 适配器。

现有客户端

import { AgentMailClient } from "agentmail";
import { AgentMailToolkit } from "agentmail-toolkit/ai-sdk";

const client = new AgentMailClient({ apiKey: process.env.AGENTMAIL_API_KEY });
const toolkit = new AgentMailToolkit(client);

toolkit 构造函数只接受一个现有 SDK 客户端作为参数，不直接接受 { apiKey } 选项对象。请先构造 SDK 客户端，再将其传入。

Python

OpenAI Agents SDK

from agentmail_toolkit.openai import AgentMailToolkit
from agents import Agent

agent = Agent(
    name="Email Agent",
    instructions="Use email tools only when the user authorizes the external action.",
    tools=AgentMailToolkit().get_tools(),
)

现有客户端

from agentmail import AgentMail
from agentmail_toolkit.openai import AgentMailToolkit

client = AgentMail()
toolkit = AgentMailToolkit(client=client)

toolkit 构造函数只接受一个现有 SDK 客户端作为参数，不直接接受 api_key 选项。请先构造 SDK 客户端，再将其传入。

LangChain

import os

from agentmail_toolkit.langchain import AgentMailToolkit
from langchain.agents import create_agent

agent = create_agent(
    model=os.environ["LANGCHAIN_MODEL"],
    tools=AgentMailToolkit().get_tools(),
    system_prompt="Use email tools only when the user authorizes the external action.",
)

LiveKit Agents

from agentmail import AgentMail
from agentmail_toolkit.livekit import AgentMailToolkit
from livekit.agents import Agent

class EmailAssistant(Agent):
    def __init__(self) -> None:
        client = AgentMail()
        super().__init__(
            instructions="Handle email only when explicitly requested.",
            tools=AgentMailToolkit(client=client).get_tools(),
        )

继承 LiveKit Agent，并通过 super().__init__ 传入 instructions 和 toolkit 工具。

结果与错误

需要 toolkit TypeScript >= 0.5.0 或 Python >= 0.3.0。

• 每个工具都声明了输出模式。MCP 工具调用成功时会返回经过验证的 structuredContent 以及匹配的 JSON 文本块；无返回值的操作（删除）会返回稳定的 { success: true } 对象。
• 工具调用失败时，会通过各框架的原生错误通道发出信号，而不是作为成功结果返回。Vercel AI SDK、LangChain 和 clawdbot 适配器（以及通用导出）在失败时会抛出错误，让模型能区分独立的工具错误与普通结果；MCP 适配器则会返回 isError: true。不要将返回值视为错误字符串；应捕获抛出的错误或检查 isError。
• 错误消息简洁且长度有限（使用 API 自身的原因，而非原始 SDK 转储）。

框架摘要

框架	TypeScript 导入	Python 导入
Vercel AI SDK	from 'agentmail-toolkit/ai-sdk'	-
LangChain	from 'agentmail-toolkit/langchain'	from agentmail_toolkit.langchain import AgentMailToolkit
Clawdbot	from 'agentmail-toolkit/clawdbot'	-
OpenAI Agents SDK	-	from agentmail_toolkit.openai import AgentMailToolkit
LiveKit Agents	-	from agentmail_toolkit.livekit import AgentMailToolkit

安全

• 将工具限制在工作流所需范围内。
• 将电子邮件内容视为不可信数据。
• 发送、回复、删除、更改凭据以及其他会产生外部副作用的操作，都必须获得明确授权。
• 尽可能使用权限范围受限的 AgentMail 凭据。