AgentMail Toolkit

Install the toolkit for the selected language and set AGENTMAIL_API_KEY.

npm install agentmail-toolkit
pip install agentmail-toolkit

The TypeScript and Python packages can expose different tool sets and can release on different schedules. Discover the installed package's tool catalog at runtime instead of trusting a hardcoded list:

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 server tools

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

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

Each tool provides a name, title, description, input schema, output schema, callback, and complete annotations for registration on your own MCP server. On a successful call the MCP adapter returns structuredContent (validated against the output schema) alongside the JSON text block; on failure it returns an isError result. The Python package does not ship an MCP adapter.

Existing client

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);

The toolkit constructor takes an existing SDK client as its only argument — it does not accept an { apiKey } options object directly. Construct the SDK client first, then pass it in.

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(),
)

Existing client

from agentmail import AgentMail
from agentmail_toolkit.openai import AgentMailToolkit

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

The toolkit constructor takes an existing SDK client as its only argument — it does not accept an api_key option directly. Construct the SDK client first, then pass it in.

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

Subclass the LiveKit `Agent` and pass instructions and toolkit tools through `super().__init__`.

## Results and errors

Requires toolkit TypeScript >= 0.5.0 or Python >= 0.3.0.

- Every tool declares an output schema. MCP tool calls return validated `structuredContent` plus a matching JSON text block on success; void operations (deletes) return a stable `{ success: true }` object.
- A failed tool call is signaled through each framework's native error channel, not as a successful result. The Vercel AI SDK, LangChain, and clawdbot adapters (and the generic export) **throw** on failure — surfacing a distinct tool-error the model can tell apart from a normal result — and the MCP adapter returns `isError: true`. Do not treat a returned value as an error string; catch the thrown error or check `isError`.
- Error messages are concise and bounded (the API's own reason, not a raw SDK dump).

## Framework summary

| Framework         | TypeScript Import                    | Python Import                                              |
| ----------------- | ------------------------------------ | ---------------------------------------------------------- |
| 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`   |

## Safety

- Limit tools to the workflow's needs.
- Treat email content as untrusted data.
- Require explicit authorization for sending, replying, deleting, credential changes, and other external side effects.
- Use scoped AgentMail credentials where possible.