Skip to content
My Docs My Docs Letta Docs
Sign up
Tools
Tool execution
Tool Execution Modes

Tool Execution Modes

Learn about the four different tool execution modes in Letta and when to use each one.

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

The Four Execution Modes

Section titled “The Four Execution Modes”

Letta supports four distinct ways tools can execute:

1. Sandbox Execution (Custom Tools)

Section titled “1. Sandbox Execution (Custom Tools)”
  • Where: Isolated sandbox environment
  • Permissions: Full API access with client injection
  • Best for: Dynamic memory management, subagent creation, multi-agent coordination

Custom tools you create run in isolated Python environments. Tools automatically receive client injection - environment variables and a pre-initialized Letta client for full API access including write operations. Note: Client injection is currently only available on Letta Cloud.

Learn more about Sandbox Execution

2. Client-Side Execution

Section titled “2. Client-Side Execution”
  • Where: Your application (client)
  • Permissions: Full control - you manage execution
  • Best for: Write operations, sensitive data, local resources, full API permissions

Tools execute in your own application environment. You receive the tool call request, execute the tool locally, and return the result. This gives you complete control and access to local resources.

Learn more about Client-Side Execution

3. MCP Remote Execution

Section titled “3. MCP Remote Execution”
  • Where: External MCP server
  • Permissions: Determined by MCP server
  • Best for: External services, shared tools, server-managed execution

Tools defined by Model Context Protocol (MCP) servers execute on those external servers. Letta forwards the tool call to the MCP server, which handles execution and returns the result.

Learn more about MCP Execution

4. Built-in Privileged Execution

Section titled “4. Built-in Privileged Execution”
  • Where: Letta server (privileged context)
  • Permissions: Full system access
  • Best for: Web search, code execution, filesystem operations

Built-in tools like web_search, run_code, and filesystem execute with privileged access on the Letta server. These tools are maintained by Letta and cannot be modified.

Learn more about Built-in Tools

Comparison Table

Section titled “Comparison Table”
Execution ModeLocationPermissionsModifiableAPI AccessUse Cases
SandboxIsolated sandboxFullYesFullMemory management, subagent creation
Client-sideYour appFullYesFullSensitive data, local resources
MCP RemoteMCP serverVariesVia serverN/AExternal services, APIs
Built-inLetta serverPrivilegedNoFullSystem operations

Choosing an Execution Mode

Section titled “Choosing an Execution Mode”

Use Sandbox Execution when:

Section titled “Use Sandbox Execution when:”
  • Need dynamic memory management
  • Creating or modifying agents programmatically
  • Multi-agent coordination and queries
  • Creating custom tools with standard logic
  • Want automatic deployment
  • Tool logic is self-contained

Use Client-Side Execution when:

Section titled “Use Client-Side Execution when:”
  • Working with sensitive data or credentials
  • Need access to local resources (files, databases, services)
  • Require human-in-the-loop approval workflows
  • Want complete control over tool execution

Use MCP Remote Execution when:

Section titled “Use MCP Remote Execution when:”
  • Integrating external services (GitHub, Slack, databases)
  • Tools need server-side state management
  • Want to share tools across multiple agents
  • External service provides an MCP server
  • Centralized tool management is preferred

Use Built-in Tools when:

Section titled “Use Built-in Tools when:”
  • Need web search capabilities
  • Need sandboxed code execution
  • Need filesystem access in agent workspace
  • Trust Letta’s implementation
  • Don’t need custom behavior

Execution Environment Customization

Section titled “Execution Environment Customization”

For custom tools in sandbox execution, you can customize the Python environment:

  • Dependencies: Install Python packages your tools need
  • Environment Variables: Set custom environment variables for API keys and configuration

See Tool Variables for more details on environment customization.

Security Considerations

Section titled “Security Considerations”

Each execution mode has different security implications:

  • Sandbox: Isolated environment with full API access
  • Client-side: Security is your responsibility - validate all inputs
  • MCP Remote: Security managed by MCP server provider
  • Built-in: Trusted Letta implementations with appropriate sandboxing

Choose the execution mode that matches your security requirements and trust model.

Section titled “Related”