agentmail-toolkit

AgentMail 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 アダプターは JSON テキストブロックとともに structuredContent（出力スキーマに照らして検証済み）を返します。失敗した場合は、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);

ツールキットのコンストラクターが引数として受け取るのは、既存の 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)

ツールキットのコンストラクターが引数として受け取るのは、既存の 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__ に指示とツールキットのツールを渡します。

結果とエラー

ツールキット TypeScript >= 0.5.0 または Python >= 0.3.0 が必要です。

• すべてのツールで出力スキーマが定義されています。MCP ツール呼び出しが成功すると、検証済みの structuredContent と、それに対応する JSON テキストブロックが返されます。値を返さない操作（削除）では、安定した { success: true } オブジェクトが返されます。
• ツール呼び出しの失敗は、成功結果としてではなく、各フレームワーク固有のエラーチャネルを通じて通知されます。Vercel AI SDK、LangChain、clawdbot の各アダプター（および汎用エクスポート）は失敗時に 例外をスロー し、モデルが通常の結果と区別できるツールエラーを通知します。MCP アダプターは isError: true を返します。返された値をエラー文字列として扱わないでください。スローされたエラーをキャッチするか、isError を確認してください。
• エラーメッセージは簡潔で長さが制限されています（生の SDK ダンプではなく、API 独自の理由が表示されます）。

フレームワークの概要

フレームワーク	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 認証情報を使用してください。