Connecting agents to tools

Tools allow agents to take actions that affect the real world. Letta agents can use tools to manage their own memory, send messages to users, search the web, and more.

You can add custom tools to Letta and customize tool execution environments. You can also import external tool libraries by connecting your Letta agents to Model Context Protocol (MCP) servers. MCP servers expose APIs to Letta agents.

Where to get tools for your agents

There are three main ways to connect tools to your agents:

• Prebuilt tools: Connect to tools that are built into the Letta server, such as memory management tools and web search / code execution.
• Custom tools: Define your own tools in Letta using the SDK and the ADE.
• MCP servers: Connect your agent to tools that run on external MCP servers.

Once you’ve created a tool (if it’s a custom tool) or connected a tool (if it’s a prebuilt tool or MCP server), you can add it to an agent by passing the tool name to the tools parameter in the agent creation:

TypeScript

// create a new agent
const agent = await client.agents.create({
  memory_blocks: [
    { label: "human", limit: 2000, value: "Name: Bob" },
    { label: "persona", limit: 2000, value: "You are a friendly agent" },
  ],
  model: "openai/gpt-4o-mini",
  embedding: "openai/text-embedding-3-small",
  tools: ["my_custom_tool_name"],
});

Python

# create a new agent
agent = client.agents.create(
    memory_blocks=[
        {"label": "human", "limit": 2000, "value": "Name: Bob"},
        {"label": "persona", "limit": 2000, "value": "You are a friendly agent"}
    ],
    model="openai/gpt-4o-mini",
    embedding="openai/text-embedding-3-small",
    tools=["my_custom_tool_name"]
)

Tool execution modes

Tools in Letta can execute in different environments, based on their type. Understanding execution modes helps you choose the right tool approach for your use case.

Letta supports four execution modes:

1. Sandbox execution: Custom tools run in isolated environments (E2B cloud or local sandbox).
2. Client-side execution: Tools run in your application with full permissions.
3. MCP remote execution: Tools run on external MCP servers.
4. Built-in execution: Privileged system tools run on the Letta server.

For a detailed comparison and guide on when to use each mode, see Letta’s tool execution modes.

Tool execution environment

You can customize the environment that your tool runs in (altering the Python package dependencies and environment variables) by setting a tool execution environment. See tool variables for more information.

Tool environment variables

You can set agent-scoped environment variables for your tools. These environment variables are accessible in the sandboxed environment where you run any of the agent tools.

For example, if you define a custom tool that requires an API key to run, you can set the variable (such as EXAMPLE_TOOL_API_KEY) at the time of agent creation by using the secrets parameter:

TypeScript

// create an agent with no tools
const agent = await client.agents.create({
  memory_blocks: [
    { label: "human", limit: 2000, value: "Name: Bob" },
    { label: "persona", limit: 2000, value: "You are a friendly agent" },
  ],
  model: "openai/gpt-4o-mini",
  embedding: "openai/text-embedding-3-small",
  secrets: {
    EXAMPLE_TOOL_API_KEY: "banana",
  },
});

Python

# create an agent with no tools
agent = client.agents.create(
    memory_blocks=[
        {"label": "human", "limit": 2000, "value": "Name: Bob"},
        {"label": "persona", "limit": 2000, "value": "You are a friendly agent"}
    ],
    model="openai/gpt-4o-mini",
    embedding="openai/text-embedding-3-small",
    secrets={
        "EXAMPLE_TOOL_API_KEY": "banana"
    }
)

Tool rules

Tool rules allow you to define graph-like constraints on your tools. For example, you can require a tool to terminate an agent execution or to be followed by another tool.

Read more about tool rules.

External tool libraries

Letta supports connecting to external tool libraries via MCP. You can connect to MCP servers using the Letta SDK (Python and TypeScript/Node.js) or the point-and-click option in the ADE.