How to use
- Copy the installation command and review the source package before installing it in your own agent environment.
- Check the source document for required tools, credentials and supported hosts.
- Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/agentmail-to/agentmail-skills --skill agentmail-toolkitBefore you start
- Installation does not include a model subscription, API allowance or permission to access your files.
- Repository stars and installation counts describe activity, not an independent quality or security test.
Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.
AgentMail Toolkit
Install the toolkit for the selected language and set AGENTMAIL_API_KEY.
npm install agentmail-toolkit
pip install agentmail-toolkitThe 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
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(),
)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
structuredContentplus 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 checkisError. - 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.
