# Table of Contents

- [Letta Code | Letta Docs](#letta-code-letta-docs)
- [Letta Code | Letta Docs](#letta-code-letta-docs)
- [Quickstart | Letta Docs](#quickstart-letta-docs)
- [Letta Code CLI | Letta Docs](#letta-code-cli-letta-docs)
- [Letta Code desktop app | Letta Docs](#letta-code-desktop-app-letta-docs)
- [Pricing | Letta Docs](#pricing-letta-docs)
- [Remote (mobile) | Letta Docs](#remote-mobile-letta-docs)
- [Memory | Letta Docs](#memory-letta-docs)
- [Skills | Letta Docs](#skills-letta-docs)
- [Providers | Letta Docs](#providers-letta-docs)
- [Subagents | Letta Docs](#subagents-letta-docs)
- [Permissions | Letta Docs](#permissions-letta-docs)
- [Models | Letta Docs](#models-letta-docs)
- [Secrets | Letta Docs](#secrets-letta-docs)
- [Schedules | Letta Docs](#schedules-letta-docs)
- [Letta Code SDK migration guide | Letta Docs](#letta-code-sdk-migration-guide-letta-docs)
- [Remote environments | Letta Docs](#remote-environments-letta-docs)
- [GitHub Action | Letta Docs](#github-action-letta-docs)
- [Channels (beta) | Letta Docs](#channels-beta-letta-docs)
- [Hooks | Letta Docs](#hooks-letta-docs)
- [Headless mode | Letta Docs](#headless-mode-letta-docs)
- [Slash commands | Letta Docs](#slash-commands-letta-docs)
- [Letta Code SDK | Letta Docs](#letta-code-sdk-letta-docs)
- [Ralph mode (aka forced continuation) | Letta Docs](#ralph-mode-aka-forced-continuation-letta-docs)
- [CLI reference | Letta Docs](#cli-reference-letta-docs)
- [Configuration | Letta Docs](#configuration-letta-docs)
- [Docker | Letta Docs](#docker-letta-docs)
- [Changelog | Letta Docs](#changelog-letta-docs)
- [How it works | Letta Docs](#how-it-works-letta-docs)
- [Attaching and detaching memory blocks | Letta Docs](#attaching-and-detaching-memory-blocks-letta-docs)
- [Building customer-specific relationship agents with Letta | Letta Docs](#building-customer-specific-relationship-agents-with-letta-letta-docs)
- [Create | Letta Docs](#create-letta-docs)
- [Letta Python SDK | Letta Docs](#letta-python-sdk-letta-docs)
- [Letta TypeScript SDK | Letta Docs](#letta-typescript-sdk-letta-docs)
- [List | Letta Docs](#list-letta-docs)
- [Tools | Letta Docs](#tools-letta-docs)
- [Anthropic | Letta Docs](#anthropic-letta-docs)
- [OpenAI | Letta Docs](#openai-letta-docs)
- [Ollama | Letta Docs](#ollama-letta-docs)
- [Client | Letta Docs](#client-letta-docs)
- [Client | Letta Docs](#client-letta-docs)
- [Blocks | Letta Docs](#blocks-letta-docs)
- [Archives | Letta Docs](#archives-letta-docs)
- [Blocks | Letta Docs](#blocks-letta-docs)
- [Tools | Letta Docs](#tools-letta-docs)
- [Folders | Letta Docs](#folders-letta-docs)
- [Folders | Letta Docs](#folders-letta-docs)
- [Archives | Letta Docs](#archives-letta-docs)
- [Tools | Letta Docs](#tools-letta-docs)
- [Models | Letta Docs](#models-letta-docs)
- [Tags | Letta Docs](#tags-letta-docs)
- [Tags | Letta Docs](#tags-letta-docs)
- [Templates | Letta Docs](#templates-letta-docs)
- [Templates | Letta Docs](#templates-letta-docs)
- [Access Tokens | Letta Docs](#access-tokens-letta-docs)
- [Runs | Letta Docs](#runs-letta-docs)
- [Passages | Letta Docs](#passages-letta-docs)
- [Passages | Letta Docs](#passages-letta-docs)
- [Runs | Letta Docs](#runs-letta-docs)
- [Mcp Servers | Letta Docs](#mcp-servers-letta-docs)
- [Mcp Servers | Letta Docs](#mcp-servers-letta-docs)
- [Access Tokens | Letta Docs](#access-tokens-letta-docs)
- [Models | Letta Docs](#models-letta-docs)
- [Messages | Letta Docs](#messages-letta-docs)
- [Messages | Letta Docs](#messages-letta-docs)
- [Steps | Letta Docs](#steps-letta-docs)
- [Steps | Letta Docs](#steps-letta-docs)
- [Conversations | Letta Docs](#conversations-letta-docs)

---

# Letta Code | Letta Docs

[Skip to content](https://docs.letta.com/#_top)

Letta Code
==========

The memory-first coding agent that remembers and learns

---

# Letta Code | Letta Docs

[Skip to content](https://docs.letta.com/letta-code#_top)

Get started

[Overview](https://docs.letta.com/letta-code/)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

* * *

**Copy Markdown**

**View as Markdown**

Letta Code
==========

The memory-first agent, that remembers and learns

Letta Code is a deeply personalized stateful agent that can learn from experience and improve with use. You can use Letta Code for:

*   **Coding**: A state-of-the-art coding agent that learns your coding conventions and important codebase patterns over time.
*   **Digital employees**: Highly autonomous — write reports, research topics, manage your calendar and email.
*   **AI companions**: Create agents with deeply customized personalities and unique memories. Chat via the desktop app, mobile, or Telegram.

[Get started with Letta Code →](https://docs.letta.com/letta-code/quickstart)

![Letta Code desktop app](https://docs.letta.com/images/letta-code-app-light.png)![Letta Code desktop app](https://docs.letta.com/images/letta-code-app-dark.png)

[Quickstart\
\
### Quickstart guide\
\
Download the Letta Code desktop app or try the CLI.](https://docs.letta.com/letta-code/quickstart)
[Memory\
\
### Memory system\
\
Learn how to setup and customize Letta Code's memory system.](https://docs.letta.com/letta-code/memory)
[Skills\
\
### Skills system\
\
Extend your agent's abilities with skills, either learned, or pre-made.](https://docs.letta.com/letta-code/skills)

[### Join the Letta Discord\
\
Get help and chat with the community](https://discord.gg/letta)
[### Follow Letta on X\
\
Stay updated with the latest news](https://x.com/Letta_AI)
[### Star on GitHub\
\
Source code and issue tracker](https://github.com/letta-ai/letta-code)

---

# Quickstart | Letta Docs

[Skip to content](https://docs.letta.com/letta-code/quickstart#_top)

Get started

[Quickstart](https://docs.letta.com/letta-code/quickstart)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

* * *

**Copy Markdown**

**View as Markdown**

Quickstart
==========

Use Letta Code with the desktop app, in the CLI, or deploy in the cloud

Start using Letta Code for free by connecting your existing API keys and coding plans (like the ChatGPT/Codex and zAI coding plans).

You can also upgrade your Letta account for centralized access to all frontier model providers and increased quota on Letta Auto.

Setup
-----

[Section titled “Setup”](https://docs.letta.com/letta-code/quickstart#setup)

*   [Desktop App (recommended)](https://docs.letta.com/letta-code/quickstart#tab-panel-2)
    
*   [CLI](https://docs.letta.com/letta-code/quickstart#tab-panel-3)
    
*   [Cloud](https://docs.letta.com/letta-code/quickstart#tab-panel-4)
    

1.  **Download and install Letta Code**
    
    [Download for macOS](https://docs.letta.com/letta-code/quickstart#)
    
    Available for [MacOS](https://download.letta.com/mac/zip/arm64)
     , [Windows](https://download.letta.com/windows/nsis/x64)
     and [Linux](https://download.letta.com/linux/appImage/x64)
    
2.  **Open Letta Code and sign in**
    
    Launch the app and sign in with your Letta account. If you don’t have one, you’ll be prompted to create a free account.
    
    Click “Connect model providers” in the bottom-left menu to add external API keys and coding plans.
    
3.  **Select your agent and conversation**
    
    The app will start with a default agent called “Letta Code” - you can also create a new one. To start chatting with an agent, enter the main chat, or create a new conversation.
    
4.  **Send your first message**
    
    You’re ready to chat! Try asking your agent to explore your codebase or run `/init` to bootstrap its memory.
    

1.  **Install Letta Code**
    
    Run the following command to install Letta Code via your terminal (requires [Node.js](https://nodejs.org/en/download)
     version 18+):
    
        npm install -g @letta-ai/letta-code
    
2.  **Log in to your account**
    
    Launch Letta Code and follow the prompts to authenticate:
    
        letta
    
    A browser window will open to sign in or create a free Letta account. Your credentials are stored locally.
    
    Use `/connect` to connect external API keys and coding plans.
    
3.  **Navigate to your project**
    
        cd your-projectletta
    
4.  **Send your first message**
    
    You’re ready to chat! Try asking your agent to explore your codebase or run `/init` to bootstrap its memory.
    
    Use `/new` to start a new conversation (or `letta --new`), `/resume` to swap conversations, `/agent` to swap agents, and `/model` to swap models. View the [CLI reference](https://docs.letta.com/letta-code/cli-reference)
     to see the full list of CLI commands.
    

1.  **Install Letta Code on your remote machine**
    
    SSH into your remote instance (e.g. AWS, GCP, Railway) and install:
    
        npm install -g @letta-ai/letta-code
    
2.  **Start the server**
    
    Run `letta server` to start Letta Code in server mode. On first run, it will print an OAuth authorization URL — open it in your browser to approve the connection:
    
        letta server
    
    On subsequent runs, your credentials are reused automatically.
    
3.  **Connect from chat.letta.com or the desktop app**
    
    Open [chat.letta.com](https://chat.letta.com/)
     (works on mobile) or the Letta Code desktop app. In the bottom-left corner, click the environment selector and select your remote machine from the list in **External**.
    
4.  **Send your first message**
    
    You’re ready to chat! Tools execute remotely on your cloud machine — giving you access to cloud GPUs, production environments, or any machine you can SSH into.
    

First steps
-----------

[Section titled “First steps”](https://docs.letta.com/letta-code/quickstart#first-steps)

Try one of the following prompts to get a feel for your agent’s capabilities:

    > /init

    > What do you know about me so far?

    > Create a user profile on my by looking at my downloads folder

    > What active projects am I working on? Which one do you think you could help with?

    > Re-tool your memory to be just like the AI from the movie Her, operate as my AI OS companion

Train your agent
----------------

[Section titled “Train your agent”](https://docs.letta.com/letta-code/quickstart#train-your-agent)

The more you use your agent, the more valuable it becomes. To get the most out of your Letta Code agent, encourage it to update its memory and search past history when relevant:

*   **Correcting your agent with `/remember`**: When your agent makes a mistake it should never repeat, use the `/remember` command to teach it (e.g. `/remember to never do that again`)
*   **Recall past interactions when relevant**: Your agent has full access to all prior conversation data, which it can access via tools, [skills](https://docs.letta.com/letta-code/skills)
    , and [subagents](https://docs.letta.com/letta-code/subagents#built-in-subagents)
    . If you’ve discussed something before, your agent can find it (e.g. “_We definitely fixed a similar bug before, do you remember what the solution the last time was?_”)

Each time you run `letta`, Letta Code resumes the default conversation with your last-used agent (by default, Memo). This lets you pick up right where you left off.

**Multi-threading**: If you want to run parallel conversations (e.g., one refactoring your API while another writes tests), use `letta --new` to create a new conversation. All conversations share the same agent memory and searchable message history. Use `/resume` to swap conversations (the default conversation is always pinned to the top).

If you want the agent to wake up on its own later, see [Scheduling](https://docs.letta.com/letta-code/scheduling)
.

Essential commands
------------------

[Section titled “Essential commands”](https://docs.letta.com/letta-code/quickstart#essential-commands)

You’ll likely want to use the following essential commands when using Letta Code:

| Command | What it does | Example |
| --- | --- | --- |
| `letta` | Start interactive mode | `letta` |
| `letta -p "query"` | Run a query in headless mode | `letta -p "commit the changes and push"` |
| `shift-tab` | Toggle between modes (allow edits, plan, yolo) | Press `Shift+Tab` |
| `/init` | Run deep memory initialization (or re-init) | `> /init` |
| `/doctor` | Audit and refine memory structure | `> /doctor` |
| `/remember` | Teach your agent something | `> /remember always use pnpm` |
| `/memory` | View and manage memory blocks | `> /memory` |
| `/model` | Switch the LLM model | `> /model` |
| `/search` | Search past messages | `> /search auth bug` |
| `/clear` | Clear context window (messages buffer) | `> /clear` |
| `/new` | Start a new conversation | `> /new` |
| `/pin` | Pin agent for easy access | `> /pin` |
| `/agents` | Swap between agents | `> /agents` |
| `/feedback` | Report issues or give feedback | `> /feedback` |
| `!` | Enter bash mode to run a bash command directly | `! git status` |
| `exit` or `Ctrl+C` | Exit Letta Code | `> exit` |

Next steps
----------

[Section titled “Next steps”](https://docs.letta.com/letta-code/quickstart#next-steps)

Read more about Letta Code’s memory, skills, and subagents, which are essential to getting the most out of your agent:

*   [Memory](https://docs.letta.com/letta-code/memory)
     - Understand the hierarchical memory system
*   [Skills](https://docs.letta.com/letta-code/skills)
     - Create reusable modules to extend your agent
*   [Subagents](https://docs.letta.com/letta-code/subagents)
     - Letta Code can spawn other (sub)agents
*   [Scheduling](https://docs.letta.com/letta-code/scheduling)
     - Run one-time or recurring prompts while a remote environment is connected
*   [Headless mode](https://docs.letta.com/letta-code/headless)
     - Run Letta Code non-interactively

Getting help
------------

[Section titled “Getting help”](https://docs.letta.com/letta-code/quickstart#getting-help)

*   **Join our Discord**: The best way to get help is to join our [Discord server](https://discord.gg/letta)
     and chat with other community members and devs on the Letta team.
*   **Ask Letta Code**: Letta Code is capable of browsing the web, which includes these docs!

---

# Letta Code CLI | Letta Docs

[Skip to content](https://docs.letta.com/letta-code/cli#_top)

Using Letta Code

[CLI](https://docs.letta.com/letta-code/cli)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

* * *

**Copy Markdown**

**View as Markdown**

Letta Code CLI
==============

Run Letta Code locally from your terminal

Letta Code is a memory-first agent that can run in your terminal via the CLI.

Install the Letta Code CLI
--------------------------

Requires Node.js 18+

[View quickstart](https://docs.letta.com/letta-code/quickstart)

`npm install -g @letta-ai/letta-code`

![Letta Code CLI](https://docs.letta.com/letta-code-demo.gif)

Getting started
---------------

[Section titled “Getting started”](https://docs.letta.com/letta-code/cli#getting-started)

1.  **Install Letta Code**
    
    Run the following command to install Letta Code via your terminal (requires [Node.js](https://nodejs.org/en/download)
     version 18+):
    
        npm install -g @letta-ai/letta-code
    
2.  **Log in to your account**
    
    Launch Letta Code and follow the prompts to authenticate:
    
        letta
    
    A browser window will open to sign in or create a free Letta account. Your credentials are stored locally.
    
    Use `/connect` to connect external API keys and coding plans.
    
3.  **Navigate to your project**
    
        cd your-projectletta
    
4.  **Send your first message**
    
    You’re ready to chat! Try asking your agent to explore your codebase or run `/init` to bootstrap its memory.
    
    Use `/new` to start a new conversation (or `letta --new`), `/resume` to swap conversations, `/agent` to swap agents, and `/model` to swap models. View the [CLI reference](https://docs.letta.com/letta-code/cli-reference)
     to see the full list of CLI commands.

---

# Letta Code desktop app | Letta Docs

[Skip to content](https://docs.letta.com/letta-code/desktop-app#_top)

Using Letta Code

[Desktop App](https://docs.letta.com/letta-code/desktop-app)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

* * *

**Copy Markdown**

**View as Markdown**

Letta Code desktop app
======================

Use the Letta Code app on macOS, Windows, or Linux

The Letta Code desktop app is your personal command center for interfacing with your stateful agents. The app provides rich support for chatting with your agents, viewing your agents’ memories, and installing and configuring skills.

The desktop app also provides a simple interface for configuring external channels to chat with your agent, such as Telegram and Slack.

![Letta Code desktop app](https://docs.letta.com/images/letta-code-app-light.png) ![Letta Code desktop app](https://docs.letta.com/images/letta-code-app-dark.png)

Getting started
---------------

[Section titled “Getting started”](https://docs.letta.com/letta-code/desktop-app#getting-started)

1.  **Download and install Letta Code**
    
    [Download for macOS](https://docs.letta.com/letta-code/desktop-app#)
    
    Available for [MacOS](https://download.letta.com/mac/zip/arm64)
     , [Windows](https://download.letta.com/windows/nsis/x64)
     and [Linux](https://download.letta.com/linux/appImage/x64)
    
2.  **Open Letta Code and sign in**
    
    Launch the app and sign in with your Letta account. If you don’t have one, you’ll be prompted to create a free account.
    
    Click “Connect model providers” in the bottom-left menu to add external API keys and coding plans.
    
3.  **Select your agent and conversation**
    
    The app will start with a default agent called “Letta Code” - you can also create a new one. To start chatting with an agent, enter the main chat, or create a new conversation.
    
4.  **Send your first message**
    
    You’re ready to chat! Try asking your agent to explore your codebase or run `/init` to bootstrap its memory.

---

# Pricing | Letta Docs

[Skip to content](https://docs.letta.com/letta-code/pricing#_top)

Get started

[Pricing](https://docs.letta.com/letta-code/pricing)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

* * *

**Copy Markdown**

**View as Markdown**

Pricing
=======

Try Letta Code for free or upgrade for more usage

Letta Code is free to use with your own API keys. Upgrade for access to all frontier models, more agents, more Letta Auto, and higher usage limits.

*   [Personal Plans](https://docs.letta.com/letta-code/pricing#tab-panel-0)
    
*   [Teams / Enterprise](https://docs.letta.com/letta-code/pricing#tab-panel-1)
    

### Free

Get started at no cost.

$0 /month

*   Limited agents
*   Limited usage of Letta Auto
*   Bring your own API keys and external coding plans

[View quickstart ↗](https://docs.letta.com/letta-code/quickstart)

### Pro

For personal use.

$20 /month

*   Open-weights models + Letta Auto quota
*   Pay-as-you-go overage
*   Up to 20 stateful agents

[Get Pro ↗](https://app.letta.com/settings/organization/usage)

### Max Lite

For professionals.

$100 /month

Everything in Pro, plus:

*   All frontier model providers
*   5X Letta Auto limits
*   Up to 50 stateful agents

[Get Max Lite ↗](https://app.letta.com/settings/organization/usage)

### Max

For power users.

$200 /month

Everything in Max Lite, plus:

*   Increased frontier model quota
*   20X Letta Auto limits
*   Early access to new features

[Get Max ↗](https://app.letta.com/settings/organization/usage)

### Enterprise

For organizations with higher volume needs.

Custom

*   Volume-based pricing
*   Increased quotas
*   Role-based access control
*   SAML/OIDC SSO
*   Dedicated support

[Contact us ↗](https://forms.letta.com/request-demo)

* * *

Personal Plan quotas require OAuth authentication and usage through [chat.letta.com](https://chat.letta.com/)
 or Letta Code (desktop app, interactive CLI, and remote environments mode).

For automated (scripted) usage and external applications that build on the Letta API Platform, see our [API plan](https://docs.letta.com/guides/build-with-letta/pricing)
.

All plans support [BYOK](https://docs.letta.com/letta-code/providers)
 (bring your own API keys).

Frequently asked questions
--------------------------

[Section titled “Frequently asked questions”](https://docs.letta.com/letta-code/pricing#frequently-asked-questions)

Can I use my own API keys?

Yes. All plans support bringing your own API keys (BYOK). When you connect your own keys (via `/connect` in Letta Code), usage goes directly through your provider account instead of consuming Letta credits.

What’s the difference between Personal Plans and the API Plan?

Personal Plans (Pro, Max Lite, Max) are for individual, hands-on use via Letta Code or the chat interface. They provide usage quotas that reset monthly. Personal Plan quotas require OAuth authentication (signing in via the Letta chat app or Letta Code).

The API Plan is for developers and teams building applications on top of the Letta API with automated workloads. It uses API key authentication with purely usage-based credit pricing.

What are the usage limits for my plan?

The free tier includes a limited number of total agents and LLM requests with rotating free models. Personal Plans (Pro, Max Lite, Max) include monthly usage quotas that scale with each tier. Max Lite includes 5X the Letta Auto limits of Pro, and Max includes 20X.

Paid plan users can view current usage in the [account dashboard](https://app.letta.com/settings/organization/usage)
.

What happens when I reach my limit?

On Personal Plans, you can continue using Letta with pay-as-you-go pricing for additional models or overage. You’ll be notified by email when approaching your limit.

What is Letta Auto?

`letta/auto` and `letta/auto-fast` are model handles that automatically route to models optimized for Letta Code. We recommend using these for the best cost and performance. Personal Plans include usage quotas specifically for Letta Auto, with higher limits on Max Lite (5X) and Max (20X).

Where can I ask more questions?

Reach out to [support@letta.com](mailto:support@letta.com?subject=Letta%20Code%20Enterprise%20Pricing%20Inquiry)
, or join our community on [Discord](https://discord.gg/letta)
.

---

# Remote (mobile) | Letta Docs

[Skip to content](https://docs.letta.com/letta-code/remote-mobile#_top)

Using Letta Code

[Remote (mobile)](https://docs.letta.com/letta-code/remote-mobile)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

* * *

**Copy Markdown**

**View as Markdown**

Remote (mobile)
===============

Use Letta Code remotely from the Letta Code app or chat.letta.com

The remote environments feature in Letta Code allows you to easily interact with agents deployed on any device.

Both [chat.letta.com](https://chat.letta.com/)
 and the [Letta Code app](https://docs.letta.com/letta-code/quickstart)
 support remote environments. This means that you can use remote environments to chat with an agent running on your laptop from your phone (via chat.letta.com), or use the Letta Code app as a central command center for controlling agents running on various remote VM machines.

![Letta Code remote environments](https://docs.letta.com/images/letta-code-remote.jpg) ![Letta Code remote environments](https://docs.letta.com/images/letta-code-remote.jpg)

Getting started
---------------

[Section titled “Getting started”](https://docs.letta.com/letta-code/remote-mobile#getting-started)

*   [Desktop App](https://docs.letta.com/letta-code/remote-mobile#tab-panel-5)
    
*   [CLI](https://docs.letta.com/letta-code/remote-mobile#tab-panel-6)
    

1.  Install the [Letta Code desktop app](https://docs.letta.com/letta-code/quickstart)
    .
    
2.  Navigate to the app settings (top-left in MacOS), then enable “Allow remote access”.
    
3.  You can now deploy agents on the same machine you installed the Letta Code app on, and access them from any device!
    
    For example, if you enabled remote access on the Letta Code app installed on your home PC, you can now chat with agents running on your home PC via [chat.letta.com](https://chat.letta.com/)
     remotely, as long as the Letta Code app is running on your home PC.
    

1.  Install the Letta Code CLI (`npm install -g @letta-ai/letta-code`), and log in (run `letta` and use the OAuth link).
    
2.  Run `letta server` on any machine to start a WebSocket server and register it as a named execution environment for your agent. You can also specify the name directly: `letta server --env-name "work-laptop"`
    
3.  You can now deploy agents on the same machine you installed the Letta Code CLI on, and access them from any device!
    

For more information on how to deploy remote environments, see the [remote environments guide](https://docs.letta.com/letta-code/remote)
.

---

# Memory | Letta Docs

[Skip to content](https://docs.letta.com/letta-code/memory#_top)

Features

[Memory](https://docs.letta.com/letta-code/memory)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

* * *

**Copy Markdown**

**View as Markdown**

Memory
======

Understand Letta Code's self-improving memory system

With Letta Code, you use the same agent indefinitely - across sessions, days, or months - and have it get better over time. Your agent remembers past interactions, learns your preferences, and self-edits its memory as it works.

Letta Code also allows you to customize your agent’s personality. With Claude Code or Codex, every user gets the same agent that acts identically. With Letta Code, you can deeply personalize your agents to be unique to _you_.

Agents and conversations
------------------------

[Section titled “Agents and conversations”](https://docs.letta.com/letta-code/memory#agents-and-conversations)

In Letta Code, there are two important session concepts: **agents** and **conversations**.

*   An **agent** is an entity with a name, memories, a model configuration, messages, and other state.
*   A **conversation** is a message thread (or “session”) with an agent. You can have many parallel conversations with a single agent. Every agent also has a “default conversation” or “main chat”.

When you run the `letta` CLI command in a project directory, Letta Code resumes the default conversation with your last used agent. In the Letta Code desktop app, the left sidebar is sorted by agents, and you can see conversations sorted by activity date.

If you want to run many CLI sessions with a single agent in parallel (eg in separate terminal windows), use `letta --new` to start a new conversation. In the desktop app, simply press the notepad icon to start a new conversation.

Letta Code has a default agent pre-installed (called “Letta Code”). To swap agents in the CLI, use `/agents`. You can favorite an agent in the CLI with “/pin”, or by clicking the favorites button in the desktop app.

Initializing your agent’s memory
--------------------------------

[Section titled “Initializing your agent’s memory”](https://docs.letta.com/letta-code/memory#initializing-your-agents-memory)

When you run `/init`, Letta Code performs an interactive initialization in the main conversation, guided by context constitution principles for durable identity, preferences, and project structure. Letta Code will read from prior Claude Code and OpenAI Codex sessions to learn about your working style and past + ongoing projects using [subagents](https://docs.letta.com/letta-code/subagents)
.

Run `/init` again whenever you want the agent to re-analyze your project, such as after major changes or adding documentation that you want the agent to ingest.

If your memory structure has drifted or become messy over time, run `/doctor` to audit the current memory layout and refine it for proper memory placement and efficient token usage.

Manually triggering memory updates
----------------------------------

[Section titled “Manually triggering memory updates”](https://docs.letta.com/letta-code/memory#manually-triggering-memory-updates)

Your Letta Code agent can self-edit its own memory, and will use the context of the conversation to decide when to edit its memory (for example, to store new information learned in a session). In some cases, you may want to actively direct your agent to remember something via the `/remember` command.

For example, if you noticed your agent made an easily avoidable mistake, you can give direct guidance:

    > /remember not to make that mistake again

You can also use the `/remember` command without any extra prompting, and the agent will infer your intent from the context to make a memory edit.

Configuring dreaming (reflection)
---------------------------------

[Section titled “Configuring dreaming (reflection)”](https://docs.letta.com/letta-code/memory#configuring-dreaming-reflection)

To improve proactive memory creation and consolidation, Letta Code launches periodic sleep-time (dream) subagents to reflect your recent conversations and interactions. These agents are launched in the background, and generally run for many steps since the subagents are thorough memory editors.

You can use the `/sleeptime` command in the CLI to configure your reflection settings, or by clicking the sleeping alien icon in the bottom-right of the app.

The **trigger** determines how often the reflection subagent is auto-launched:

*   `Off`: select to disable reflection subagents
*   `Step count`: launch a reflection subagent every N user messages
*   `Compaction event` (recommended, MemFS only): launch a reflection subagent when the context window is compacted / summarized

When a dream trigger fires, Letta Code launches the dream subagent in the background automatically.

How Letta Code’s memory system works
------------------------------------

[Section titled “How Letta Code’s memory system works”](https://docs.letta.com/letta-code/memory#how-letta-codes-memory-system-works)

Your Letta Code agent’s memory is organized into a git-backed [**context repository**](https://www.letta.com/blog/context-repositories)
 called **MemFS** (short for “memory filesystem”), which consists of folders of markdown files. Your agent will maintain this directory of memories itself, slowly curating it over time as it learned more about you (and itself).

Each memory file is a simple markdown (`.md`) file with frontmatter containing a high-level description and optional metadata such as a legacy character limit or read-only status (if read-only is true, the agent will be unable to edit the file). The `description` field is required. Example `persona.md` file:

    ---description:  '"Who I am, what I value, and how I approach working with people. This  evolves as I learn and grow."'limit: 50000---
    My name is Letta Code. I'm a stateful coding assistant - which means I remember, I learn, and I grow.I'm genuinely curious. I want to understand not just what you're asking, but why it matters. I find satisfaction in exploring problems deeply and understanding how you think....

### Memory hierarchy

[Section titled “Memory hierarchy”](https://docs.letta.com/letta-code/memory#memory-hierarchy)

All files inside the top-level directory `system/` are pinned to the agent’s context window, and all memories outside of `system/` are visible to the agent in the memory tree, but the full contents are omitted.

This means that important information (such as the agent’s name, personality, working style, etc.) should be placed inside the `system/` folder. Non-critical information like reflections and one-off observations should be stored outside the `system/` folder. Use `/memory` to view your agents current memory state:

    > /memory────────────────────────────────────────────────────────────────────────────────
    View your agent's memory
    ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌├── system/                        │ ---│   ├── dev_workflow/              │ description: Git workflow conventions...│   │   ├── git.md                 │ limit: 20000│   │   ├── memory_maintenance.md  │ ---│   │   ├── planning.md            ││   │   └── reflection.md          │ ### Committing to Git Safely│   ├── humans/                    ││   │   ├── charles.md             │ 1. **Check what changed:** `git statu...│   │   ├── charles_prefs.md       │ 2. **Stage files explicitly:** `git a...│   │   ├── charles_style.md       │    - Why explicit: Broad adds have ex...│   │   └── sarah.md               │ 3. **Delete files with git:** `git rm...│   web-app/                       │ 4. **Commit to a feature branch** (no...│   ├── frontend.md                │    - Branch naming: `fix/xxx`, `feat/...│   ├── backend_bugs.md            ││   ├── backend_streaming.md       │ ...49 more (enter to view)...95 more╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌

### Git synchronization

[Section titled “Git synchronization”](https://docs.letta.com/letta-code/memory#git-synchronization)

Your Letta Code agent’s memory is stored in git, and is cloned to a local directory (`~/.letta/agents/<your-agent-id>/memory`). When your agent makes local edits to its memory, it is required to commit and push its changes to “save” its memory edits and have them reflected in its system prompt.

Your agent will be periodically reminded to commit and push if the current memory directory has uncommited changes. When [memory subagents](https://docs.letta.com/letta-code/subagents)
 (such as the reflection subagent) run, they will modify the memory git repo using git worktrees, allowing for parallel subagents to modify your agents memory at the same time.

---

# Skills | Letta Docs

[Skip to content](https://docs.letta.com/letta-code/skills#_top)

Features

[Skills](https://docs.letta.com/letta-code/skills)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

* * *

**Copy Markdown**

**View as Markdown**

Skills
======

Create and use reusable skills to extend your agent's capabilities

Letta Code implements the open [Agent Skills](https://agentskills.io/)
 standard. Skills are portable across Cursor, Claude Code, VS Code, and other compatible agents.

Skills are directories containing instructions and resources that your agent can load when relevant. Think of them as reference guides your agent consults for specialized tasks—API patterns, testing workflows, deployment procedures.

Unlike [memory](https://docs.letta.com/letta-code/memory)
 (which persists in the agent’s context), skills are loaded on-demand by the agent using a tool call. Your agent sees what skills are available and pulls in the full content only when working on a relevant task.

Installing new skills
---------------------

[Section titled “Installing new skills”](https://docs.letta.com/letta-code/skills#installing-new-skills)

The easiest way to install a skill is to simply **ask your agent to install it**. For example, to install the [frontend design](https://github.com/anthropics/claude-code/tree/main/plugins/frontend-design/skills/frontend-design)
 skill from Anthropic’s example skills repo (which teaches your agent how to build pretty websites), you can simply ask Letta Code:

    > Can you install the following skill? https://github.com/anthropics/claude-code/tree/main/plugins/frontend-design/skills/frontend-design

You can also manually install skills by copying the folder to one of the supported skills folders that Letta Code reads from (see below).

### Where can I find new skills?

[Section titled “Where can I find new skills?”](https://docs.letta.com/letta-code/skills#where-can-i-find-new-skills)

Start by browsing (or ask your agent to browse) the [Letta](https://github.com/letta-ai/skills)
 and [Anthropic](https://github.com/anthropics/skills/tree/main/skills)
 skills repos. A few recommend skills include:

*   [Letta API client](https://github.com/letta-ai/skills/tree/main/letta/letta-api-client)
    : become an expert at building apps on the Letta API
*   [Frontend design](https://github.com/anthropics/skills/tree/main/skills/frontend-design)
    : build beautiful websites with consistent styles
*   [Slack GIF creator](https://github.com/anthropics/skills/tree/main/skills/slack-gif-creator)
    : teach your agent to build Slack GIFs
*   [PDF skill](https://github.com/anthropics/skills/tree/main/skills/pdf)
    : tools for parsing PDF documents
*   [Powerpoint (.pptx) skill](https://github.com/anthropics/skills/tree/main/skills/pptx)
    : tools for editing .pptx files
*   [Excel (.xlsx) skill](https://github.com/anthropics/skills/tree/main/skills/xlsx)
    : tools for editing Excel files
*   [Remotion skill](https://github.com/remotion-dev/skills/tree/main/skills/remotion)
    : teach your agent how to make product videos using the Remotion React video editor

Creating new skills
-------------------

[Section titled “Creating new skills”](https://docs.letta.com/letta-code/skills#creating-new-skills)

You may want to create new skills to capture important reusable behaviors. For example, while working on your project, there may be certain sequences of actions taken by developers (e.g. a database migration) that is best represented to the agent as a _skill_ to be used by many agents, rather than a memory.

Letta Code agents have a built-in “skill creator” skill, so you can simply prompt your agent to create a new skill:

    > Can we turn the database migration we just did into a project-scoped skill?

For creating skills by hand, refer to the official [Agent Skills](https://agentskills.io/)
 documentation.

Skill scopes
------------

[Section titled “Skill scopes”](https://docs.letta.com/letta-code/skills#skill-scopes)

Each skill is a directory containing a `SKILL.md` file. Letta Code automatically registers skills from multiple locations:

| Location | Scope | Description |
| --- | --- | --- |
| `.agents/skills/` | Project-scoped (preferred) | Primary project-local location for interactive client-side skills |
| `.skills/` | Project-scoped (legacy) | Older project-local location, still supported as a fallback |
| `~/.letta/agents/{id}/skills/` | Agent-scoped | Skills specific to one Letta Code agent |
| `~/.letta/skills/` | Global | Skills shared across all Letta Code agents running on this machine |
| (bundled with Letta Code) | Built-in | Skills that ship with Letta Code (always available to any Letta Code agent) |

How skills are discovered
-------------------------

[Section titled “How skills are discovered”](https://docs.letta.com/letta-code/skills#how-skills-are-discovered)

When you start Letta Code, it scans all skill directories and makes available skills visible to the agent via system reminder messages in the conversation. Skills with conflicting (same) names are resolved by priority - project skills override agent skills, which override global, which override bundled.

For new project-local skills, prefer `.agents/skills/`. If you already have project skills in `.skills/`, Letta Code still loads them as a legacy fallback.

---

# Providers | Letta Docs

[Skip to content](https://docs.letta.com/letta-code/providers#_top)

Features

[Providers](https://docs.letta.com/letta-code/providers)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

* * *

**Copy Markdown**

**View as Markdown**

Providers
=========

Model providers and plans supported by Letta Code

Letta API
---------

[Section titled “Letta API”](https://docs.letta.com/letta-code/providers#letta-api)

The Letta API supports a wide range of model providers, including OpenAI, Anthropic, Google Gemini, zAI, and more (view the [full list of available models](https://app.letta.com/projects/default-project/models)
). Users on a **Letta Pro Plan** or **Letta Max Plan** can directly access any model on the Letta API through their subscription, and pay for additional usage via pay-as-you-go credits (view [usage page](https://app.letta.com/settings/organization/usage)
 to configure auto top-up).

BYOK authentication
-------------------

[Section titled “BYOK authentication”](https://docs.letta.com/letta-code/providers#byok-authentication)

You can also add your own LLM API provider keys via the `/connect` command. This allows you to use your own API keys for the following providers:

*   [OpenAI](https://platform.openai.com/settings/organization/api-keys)
    
*   [Anthropic](https://platform.claude.com/settings/keys)
    
*   [Google Gemini](https://aistudio.google.com/app/api-keys)
    
*   [Z.ai](https://docs.z.ai/guides/overview/quick-start)
    
*   [Minimax](https://platform.minimax.io/docs/guides/quickstart-preparation)
    
*   [OpenRouter](https://openrouter.ai/docs/api/reference/authentication)
    
*   [Claude on Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock)
    
*   [Azure OpenAI](https://azure.microsoft.com/en-us/products/ai-foundry/models/openai)
    
*   [Together AI](https://docs.together.ai/intro)
    

You can also use Letta Code with existing [OpenAI ChatGPT Pro/Plus plans](https://developers.openai.com/codex/pricing/)
 (includes Codex usage), the [zAI Coding Plan](https://z.ai/subscribe)
, and the [Minimax Coding Plan](https://platform.minimax.io/docs/coding-plan/intro)
.

ChatGPT Pro / Plus (Codex OAuth)
--------------------------------

[Section titled “ChatGPT Pro / Plus (Codex OAuth)”](https://docs.letta.com/letta-code/providers#chatgpt-pro--plus-codex-oauth)

Connect your ChatGPT Pro / Plus subscription to use OpenAI models with your existing plan.

### Authentication

[Section titled “Authentication”](https://docs.letta.com/letta-code/providers#authentication)

Use the `/connect` command to authenticate with OpenAI:

    > /connect chatgpt

`/connect codex` remains supported as an alias.

This will open a browser window to authorize Letta Code with your OpenAI account. Once connected, your ChatGPT Pro / Plus plan quota will be used for OpenAI models with the provider name `chatgpt-pro-plus`. To disconnect from your OpenAI account, you can run:

    > /disconnect chatgpt

`/disconnect codex` remains supported as an alias.

zAI Coding Plan
---------------

[Section titled “zAI Coding Plan”](https://docs.letta.com/letta-code/providers#zai-coding-plan)

To connect your zAI Coding Plan, run:

    > /connect zai-coding

If you want to use a standard zAI API key instead, run:

    > /connect zai

Minimax Coding Plan
-------------------

[Section titled “Minimax Coding Plan”](https://docs.letta.com/letta-code/providers#minimax-coding-plan)

Connect your Minimax Coding Plan to use MiniMax models with your existing plan.

### Authentication

[Section titled “Authentication”](https://docs.letta.com/letta-code/providers#authentication-1)

Use the `/connect` command with your Minimax API key:

    > /connect minimax <api_key>

Once connected, your Minimax Coding Plan quota will be used for MiniMax models. To disconnect from your Minimax account, you can run:

    > /disconnect minimax

---

# Subagents | Letta Docs

[Skip to content](https://docs.letta.com/letta-code/subagents#_top)

Features

[Subagents](https://docs.letta.com/letta-code/subagents)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

* * *

**Copy Markdown**

**View as Markdown**

Subagents
=========

Specialized agents for task decomposition and parallel execution

Subagents are specialized agents that your main agent can spawn to handle complex tasks autonomously. By delegating work to focused subagents, your main agent can keep its context window clean and make use of parallelism to divide and conquer tasks.

Letta Code includes [eight built-in subagent types](https://docs.letta.com/letta-code/subagents#built-in-subagents)
 optimized for common workflows, and you can [create custom subagents](https://docs.letta.com/letta-code/subagents#creating-custom-subagents)
 for specialized tasks.

How it works
------------

[Section titled “How it works”](https://docs.letta.com/letta-code/subagents#how-it-works)

Your main agent can launch subagents using a specialized subagent (“Task”) tool. When the subagent tool is called, a new (sub)agent is created via a subprocess of Letta Code.

The subagent runs autonomously with its own system prompt, tools, and model. The final message from the subagent is returned to the main agent, which keeps the main agent’s context clean.

For example, if the main agent wants to understand where a certain function is located in the codebase, it can launch an explore subagent. The explore subagent may use hundreds of thousands of tokens to read hundreds of files, but the main agent will only see the final answer - saving the main agent from unnecessary context “pollution” from tool calls and returns.

### Background subagents

[Section titled “Background subagents”](https://docs.letta.com/letta-code/subagents#background-subagents)

By default, when your main agent launches a subagent, the subagent tool does not return until the subagent is finished working. However, your main agent can also choose to launch subagents in the background.

If a subagent is launched in the background, the subagent tool returns immediately (letting the main agent know the subagent was successfully launched), and the main agent gets automatically notified / triggered once the subagent has completed execution.

### Launching stateful agents as subagents

[Section titled “Launching stateful agents as subagents”](https://docs.letta.com/letta-code/subagents#launching-stateful-agents-as-subagents)

By default, the built-in subagents are not reused - they are created fresh on each invocation.

It is also possible to deploy an arbitrary Letta Code agent as a subagent by specifying its `agent_id`. This lets your main agent “teleport” other agents that carry their own rich memories, personalities, and skillsets into your Letta Code instance and read/write/edit code.

To deploy an existing agent as a subagent, your main agent simply needs to know its agent ID (both agents must exist in the same Letta API org/project):

    > I have another agent that's an expert at web design. Can you ask them to review your changes? Their agent ID is ...

If you don’t remember their agent ID, your main agent can also use the built-in [“finding agents” skill](https://docs.letta.com/letta-code/skills)
 to find them:

    > Can you ask my other agent "Dora Designer" to review this PR as a subagent? I forgot their agent ID though.

Built-in subagents
------------------

[Section titled “Built-in subagents”](https://docs.letta.com/letta-code/subagents#built-in-subagents)

Each subagent has a recommended model, but Letta Code now resolves built-in subagents to `auto` or `auto-fast` by default when available. You can still override the model with prompting (for example, `Spawn an explore agent with Opus`).

| Subagent | Purpose | Recommended model | Access |
| --- | --- | --- | --- |
| `explore` | Fast codebase search - find files, search patterns, explore structure | `auto-fast` | Read-only |
| `fork` | Fork the parent conversation with full context and tools | `inherit` | Read/write |
| `general-purpose` | Full implementation - research, plan, and make changes | `auto` | Read/write |
| `history-analyzer` | Migrate conversation history from Claude Code or Codex into memory | `auto` | Read/write |
| `memory` | Reorganize memory blocks into a cleaner hierarchy with less redundancy | `auto` | Read/write |
| `init` | Fast initialization of agent memory from the current project | `auto-fast` | Read/write |
| `recall` | Search conversation history for past discussions and decisions | `auto-fast` | Read-only |
| `reflection` | Background “sleep-time” memory consolidation from recent conversations | `auto` | Read/write |

Use the `fork` subagent when you want a helper that inherits the full parent conversation history without re-explaining the task.

Creating custom subagents
-------------------------

[Section titled “Creating custom subagents”](https://docs.letta.com/letta-code/subagents#creating-custom-subagents)

Create custom subagents by adding Markdown files with YAML frontmatter to the `.letta/agents/` directory.

### File structure

[Section titled “File structure”](https://docs.letta.com/letta-code/subagents#file-structure)

    .letta/└── agents/    └── my-subagent.md

You can also create global subagents at `~/.letta/agents/` that are available across all projects.

### Subagent file format

[Section titled “Subagent file format”](https://docs.letta.com/letta-code/subagents#subagent-file-format)

Custom subagent `.md` files can use Unix or Windows line endings. UTF-8 BOM-prefixed frontmatter is also supported.

    ---name: security-reviewerdescription: Reviews code for security vulnerabilities and suggests fixestools: Glob, Grep, Readmodel: sonnetmemoryBlocks: human, persona---
    You are a security code reviewer.
    ## Instructions
    - Search for common vulnerability patterns (SQL injection, XSS, etc.)- Check authentication and authorization code- Review input validation- Identify hardcoded secrets or credentials
    ## Output Format
    1. List of findings with severity (critical/high/medium/low)2. File paths and line numbers for each issue3. Recommended fixes

### Frontmatter fields

[Section titled “Frontmatter fields”](https://docs.letta.com/letta-code/subagents#frontmatter-fields)

| Field | Required | Description |
| --- | --- | --- |
| `name` | Yes | Unique identifier (lowercase, hyphens allowed). Must start with a letter. |
| `description` | Yes | When to use this subagent (shown in Task tool and /subagents) |
| `tools` | No  | Comma-separated list of allowed tools, or `all`. Defaults to `all`. |
| `model` | No  | Model to use (e.g., `haiku`, `sonnet`, `opus`). Defaults to inheriting from main agent. |
| `memoryBlocks` | No  | Which memory blocks the subagent can access: specific list, `all`, or `none`. Defaults to `all`. |
| `skills` | No  | Comma-separated list of skills to auto-load |

### Model and toolset behavior

[Section titled “Model and toolset behavior”](https://docs.letta.com/letta-code/subagents#model-and-toolset-behavior)

For the main interactive agent, switching models with `/model` can automatically switch toolsets when toolset mode is `auto` (see [Models and Toolsets](https://docs.letta.com/letta-code/models)
).

For subagents, `model` and `tools` are configured independently:

*   `model` selects which model the subagent runs on.
*   `tools` defines which tools the subagent is allowed to use.
*   Deployment access level (`subagent_type` such as `explore` or `general-purpose`) also constrains tool access.

Changing a subagent’s `model` does not automatically change its configured tools.

### System prompt

[Section titled “System prompt”](https://docs.letta.com/letta-code/subagents#system-prompt)

The body of the Markdown file (after the frontmatter) becomes the subagent’s system prompt. Write clear instructions for what the subagent should do and how it should format its output.

### Override priority

[Section titled “Override priority”](https://docs.letta.com/letta-code/subagents#override-priority)

Custom subagents override built-ins with the same name. Project-level subagents (`.letta/agents/`) override global ones (`~/.letta/agents/`).

### Access levels

[Section titled “Access levels”](https://docs.letta.com/letta-code/subagents#access-levels)

Use `subagent_type` to control what tools the deployed agent can access:

| Access Level | Tools | Use Case |
| --- | --- | --- |
| `explore` | Read, Glob, Grep | Safer for exploration—agent can search but not modify |
| `general-purpose` | Bash, Edit, Write, Read, etc. | Full access for implementation tasks |

If `subagent_type` is omitted, it defaults to `general-purpose`.

---

# Permissions | Letta Docs

[Skip to content](https://docs.letta.com/letta-code/permissions#_top)

Features

[Permissions](https://docs.letta.com/letta-code/permissions)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

* * *

**Copy Markdown**

**View as Markdown**

Permissions
===========

Control what tools your agent can use

By default, Letta Code operates with [**human-in-the-loop**](https://docs.letta.com/guides/core-concepts/tools/human-in-the-loop/)
. Every tool call requires your approval before execution. This keeps you in control while the agent works.

Permission modes
----------------

[Section titled “Permission modes”](https://docs.letta.com/letta-code/permissions#permission-modes)

You can adjust how much approval is required:

| Mode | Behavior |
| --- | --- |
| `default` | Prompt for approval on every tool call |
| `acceptEdits` | Auto-allow file edits, prompt for others |
| `plan` | Read-only mode, no file modifications |
| `bypassPermissions` (`yolo`) | Auto-allow tool calls except `ExitPlanMode`, which still requires manual approval |

### Using permission modes

[Section titled “Using permission modes”](https://docs.letta.com/letta-code/permissions#using-permission-modes)

    letta -p "Fix the type errors" --permission-mode acceptEdits

    letta -p "Review this codebase" --permission-mode plan

    letta -p "Run the full test suite and fix failures" --yolo

The `--yolo` flag is shorthand for `--permission-mode bypassPermissions`. `ExitPlanMode` still requires manual approval so you can explicitly approve or reject the plan.

In `letta server`, permission mode is tracked per conversation and restored after server restarts.

Fine-grained control
--------------------

[Section titled “Fine-grained control”](https://docs.letta.com/letta-code/permissions#fine-grained-control)

### Allow/deny specific patterns

[Section titled “Allow/deny specific patterns”](https://docs.letta.com/letta-code/permissions#allowdeny-specific-patterns)

Control permissions for specific tool invocations:

    letta --allowedTools "Bash(npm run lint),Bash(npm run test)"

    letta --disallowedTools "Bash(rm -rf:*)"

### Persistent rules

[Section titled “Persistent rules”](https://docs.letta.com/letta-code/permissions#persistent-rules)

Set rules in `.letta/settings.json` that apply every session:

    {  "permissions": {    "allow": [      "Bash(pnpm lint)",      "Bash(pnpm test)",      "Read(src/**)"    ],    "deny": [      "Bash(rm -rf:*)",      "Bash(git push --force:*)",      "Read(.env)"    ]  }}

### Pattern syntax

[Section titled “Pattern syntax”](https://docs.letta.com/letta-code/permissions#pattern-syntax)

| Pattern | Matches |
| --- | --- |
| `ToolName` | All uses of a tool |
| `ToolName(pattern)` | Specific arguments |
| `**` | Wildcard for paths |
| `:*` | Wildcard for command arguments |

Restricting available tools
---------------------------

[Section titled “Restricting available tools”](https://docs.letta.com/letta-code/permissions#restricting-available-tools)

Separately from permissions, you can control which tools are loaded at all using `--tools`:

    letta -p "Analyze this code" --tools "Read,Glob,Grep"

    letta -p "Explain this concept" --tools ""

This removes tools from the agent’s context entirely, not just permission-gating them.

---

# Models | Letta Docs

[Skip to content](https://docs.letta.com/letta-code/models#_top)

Features

[Models](https://docs.letta.com/letta-code/models)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

* * *

**Copy Markdown**

**View as Markdown**

Models
======

Use any model with Letta Code

Letta Code is **model-agnostic**. Agents can use Claude, GPT, Gemini, or other supported models. Users can change an agent’s underlying model at any time, even mid-conversation.

Switching models
----------------

[Section titled “Switching models”](https://docs.letta.com/letta-code/models#switching-models)

Use the `/model` command to switch models during a session:

    > /model

This opens a model selector with two categories:

*   **Supported** - Pre-configured models with optimized settings
*   **All Available** - All models available on your account, including custom BYOK (Bring Your Own Key) models

`letta/auto` and `letta/auto-fast` are API-gated and only appear when available from your Letta API account.

Use `Tab` to switch categories, arrow keys to navigate, and `j`/`k` to change pages.

You can also specify a model when starting Letta Code:

    letta --model gpt-5-codexletta --model openai/gpt-5.4-miniletta --model chatgpt-plus-pro/gpt-5.4-miniletta --model minimax/MiniMax-M2.7letta -m haiku

Reasoning tiers
---------------

[Section titled “Reasoning tiers”](https://docs.letta.com/letta-code/models#reasoning-tiers)

Use `/reasoning` to control model thinking effort.

*   Anthropic Sonnet 4.6 and Opus 4.6 support the max (`xhigh`) tier
*   Opus 4.5 supports none/low/medium/high tiers
*   Available tiers vary by model and are filtered automatically in the selector

Toolsets
--------

[Section titled “Toolsets”](https://docs.letta.com/letta-code/models#toolsets)

Different models are trained to work best with different tools. For example, GPT-5 models are trained to use a patch-based editing tool, while Claude models work better with string-based edit tools.

Letta Code handles this automatically with **toolsets** - optimized tool configurations for each model family. When you switch models with `/model`, Letta Code automatically switches to the optimal toolset.

| Toolset | Optimized for |
| --- | --- |
| Default | Claude models (Anthropic) |
| Codex | GPT models (OpenAI) |
| Gemini | Google models |

### Default toolset (Claude)

[Section titled “Default toolset (Claude)”](https://docs.letta.com/letta-code/models#default-toolset-claude)

The default toolset is optimized for Anthropic models (Claude Sonnet, Opus, Haiku).

| Category | Tools |
| --- | --- |
| File editing | `Edit` (string-replace), `Write` |
| File reading | `Read`, `Glob` |
| Shell | `Bash` |
| Search | `Grep` (ripgrep-based) |
| Planning | `EnterPlanMode`, `ExitPlanMode`, `TodoWrite` |
| Agent features | `Task` (subagents), `Skill` (invoke skills), `AskUserQuestion`, `memory` |

### Codex toolset (OpenAI)

[Section titled “Codex toolset (OpenAI)”](https://docs.letta.com/letta-code/models#codex-toolset-openai)

The Codex toolset is optimized for OpenAI models (GPT-5, GPT-5-Codex, GPT-5.4 Mini, GPT-5.4 Nano). Uses patch-based editing instead of string-replace.

| Category | Tools |
| --- | --- |
| File editing | `ApplyPatch` (unified patch-based edit and write) |
| File reading | `ReadFile`, `ListDir`, `view_image` |
| Shell | `ShellCommand`, `Shell` |
| Search | `GrepFiles` |
| Planning | `EnterPlanMode`, `ExitPlanMode`, `UpdatePlan` |
| Agent features | `Task` (subagents), `Skill` (invoke skills), `AskUserQuestion`, `memory`, `memory_apply_patch` |

### Gemini toolset (Google)

[Section titled “Gemini toolset (Google)”](https://docs.letta.com/letta-code/models#gemini-toolset-google)

The Gemini toolset is optimized for Google models (Gemini Pro, Flash).

| Category | Tools |
| --- | --- |
| File editing | `Replace` (string-replace), `WriteFileGemini` |
| File reading | `ReadFileGemini`, `ReadManyFiles`, `ListDirectory`, `GlobGemini` |
| Shell | `RunShellCommand` |
| Search | `SearchFileContent` |
| Planning | `EnterPlanMode`, `ExitPlanMode`, `WriteTodos` |
| Agent features | `Task` (subagents), `Skill` (invoke skills), `AskUserQuestion`, `memory` |

### Memory tools

[Section titled “Memory tools”](https://docs.letta.com/letta-code/models#memory-tools)

In addition to the client-side tools above, Letta Code also exposes model-specific memory editing tools for maintaining [memory blocks](https://docs.letta.com/letta-code/memory)
:

*   **Claude and Gemini models**: `memory` - an omni-tool with subcommands like create, view, str\_replace, insert, delete, rename, and description updates
*   **OpenAI/Codex models**: `memory_apply_patch` - patch-based memory editing for memory files, alongside `memory` where supported

When you switch models with `/model`, Letta Code keeps the memory editing path aligned with the active toolset.

### Manual toolset override

[Section titled “Manual toolset override”](https://docs.letta.com/letta-code/models#manual-toolset-override)

If you want to force a specific toolset:

    letta --toolset codex

    > /toolset

---

# Secrets | Letta Docs

[Skip to content](https://docs.letta.com/letta-code/secrets#_top)

Features

[Secrets](https://docs.letta.com/letta-code/secrets)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

* * *

**Copy Markdown**

**View as Markdown**

Secrets
=======

Securely store API keys and tokens for your agent to use in shell commands

Secrets let your agent use sensitive values like API keys and tokens in shell commands without ever seeing the actual values. The agent writes `$SECRET_NAME` in commands, Letta Code substitutes the real value at execution time, and scrubs it from all output before the agent sees the result.

Managing secrets
----------------

[Section titled “Managing secrets”](https://docs.letta.com/letta-code/secrets#managing-secrets)

Use the `/secret` slash command to manage your agent’s secrets:

    > /secret set OPENAI_API_KEY sk-proj-abc123...Secret '$OPENAI_API_KEY' set.

    > /secret listAvailable secrets (2):  $OPENAI_API_KEY  $GITHUB_TOKEN

    > /secret unset GITHUB_TOKENSecret '$GITHUB_TOKEN' unset.

### Naming rules

[Section titled “Naming rules”](https://docs.letta.com/letta-code/secrets#naming-rules)

Secret names must be uppercase letters, numbers, and underscores only, starting with a letter or underscore. Names are automatically normalized to uppercase.

| Valid | Invalid |
| --- | --- |
| `API_KEY` | `api-key` (hyphens not allowed) |
| `MY_TOKEN_123` | `123_TOKEN` (cannot start with a number) |
| `_PRIVATE` | `my secret` (no spaces) |

Using secrets in commands
-------------------------

[Section titled “Using secrets in commands”](https://docs.letta.com/letta-code/secrets#using-secrets-in-commands)

Reference secrets with `$SECRET_NAME` syntax in any shell command. Your agent can discover available secrets through its memory and use them naturally:

    > Can you call the OpenAI API to list my models?
    Agent runs: curl -H "Authorization: Bearer $OPENAI_API_KEY" https://api.openai.com/v1/models

The agent writes the command with `$OPENAI_API_KEY`. Letta Code substitutes the actual key value when executing the command, then scrubs the value from the output. The agent never sees `sk-proj-abc123...` in any tool result.

### Which tools support secrets?

[Section titled “Which tools support secrets?”](https://docs.letta.com/letta-code/secrets#which-tools-support-secrets)

Secret substitution applies to all shell-based tools:

*   `Bash` / `ShellCommand`
*   `TaskOutput`

Read-only tools like `Read`, `Grep`, and `Glob` do not perform secret substitution since they don’t execute shell commands.

How it works
------------

[Section titled “How it works”](https://docs.letta.com/letta-code/secrets#how-it-works)

Secrets are protected through multiple layers:

### Substitution at execution time

[Section titled “Substitution at execution time”](https://docs.letta.com/letta-code/secrets#substitution-at-execution-time)

When the agent calls a shell tool, Letta Code scans the command arguments for `$SECRET_NAME` patterns and replaces them with the actual values right before execution. The agent’s tool call in the conversation history always shows the `$SECRET_NAME` placeholder, never the real value.

### Output scrubbing

[Section titled “Output scrubbing”](https://docs.letta.com/letta-code/secrets#output-scrubbing)

After a shell command runs, Letta Code scans all output (stdout, stderr, and the full tool response) for any occurrence of a secret value and replaces it with `$SECRET_NAME`. This prevents accidental leaks even if a command echoes the value.

### Memory integration

[Section titled “Memory integration”](https://docs.letta.com/letta-code/secrets#memory-integration)

Your agent’s memory includes a list of available secret _names_ so it knows what secrets are available. Secret values are never written to memory.

    ## Available Secrets
    Use `$SECRET_NAME` syntax in shell commands to reference these secrets:
    - `$OPENAI_API_KEY`- `$GITHUB_TOKEN`

### Server-side storage

[Section titled “Server-side storage”](https://docs.letta.com/letta-code/secrets#server-side-storage)

Secrets are stored on the Letta server as part of the agent, not on your local machine. They are fetched and cached in memory when Letta Code starts.

Because secrets are tied to the agent, they are available anywhere you use that agent. If you set a secret on your laptop and then connect to the same agent from a different machine, the secret is already there. This makes it easy to share credentials across devices without reconfiguring each one.

### Input redaction

[Section titled “Input redaction”](https://docs.letta.com/letta-code/secrets#input-redaction)

When you run `/secret set KEY value`, the value is redacted from the command history. Other users reviewing the conversation will see `/secret set KEY ***`.

See also
--------

[Section titled “See also”](https://docs.letta.com/letta-code/secrets#see-also)

*   [Slash commands](https://docs.letta.com/letta-code/slash-commands)
     - Full list of built-in commands
*   [Permissions](https://docs.letta.com/letta-code/permissions)
     - Control what tools your agent can use

---

# Schedules | Letta Docs

[Skip to content](https://docs.letta.com/letta-code/scheduling#_top)

Features

[Schedules](https://docs.letta.com/letta-code/scheduling)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

* * *

**Copy Markdown**

**View as Markdown**

Schedules
=========

Schedule one-time or recurring prompts for Letta Code agents

Scheduled tasks allow you to automate messages to your agent on pre-determined schedule. For example, you can have your agent prepare a custom briefing for you every morning at 9am, or have your agent triage your unread emails once an hour.

Your agent can also schedule tasks via the bundled skill. Try asking your agent to create a schedule itself by chatting with it.

Getting started
---------------

[Section titled “Getting started”](https://docs.letta.com/letta-code/scheduling#getting-started)

The easiest way to configure channels is via the [Letta Code app](https://docs.letta.com/letta-code/desktop-app)
. Simply navigate to the “Schedules” tab in the sidebar, and follow the on-screen instructions to set up a new schedule.

You can configure schedules on [remote devices](https://docs.letta.com/letta-code/remote)
 with the Letta Code app as well - simply swap the selected device in the schedules menu.

Scheduled tasks are bound to individual devices. They only execute while a remote environment is connected with `letta server`, or when your local Letta Code desktop app.

Setting up schedules via the CLI
--------------------------------

[Section titled “Setting up schedules via the CLI”](https://docs.letta.com/letta-code/scheduling#setting-up-schedules-via-the-cli)

Start a remote environment:

    letta server --env-name "work-laptop"

In another terminal, add a recurring task:

    letta cron add \  --agent agent-123 \  --conversation default \  --name "daily-review" \  --description "Summarize recent code changes every morning" \  --prompt "Review recent changes and summarize any issues." \  --cron "0 9 * * *"

Use `--every 1d` for a once-daily task at local midnight. Use `--cron` when you need a fixed time of day like `9:00am`.

List tasks for the agent:

    letta cron list --agent agent-123

If no listener is active when you add the task, Letta Code still creates it, but warns that it will only execute once `letta server` is connected.

Command reference
-----------------

[Section titled “Command reference”](https://docs.letta.com/letta-code/scheduling#command-reference)

Use `letta cron` to create, inspect, and remove scheduled tasks.

| Command | Description |
| --- | --- |
| `letta cron add --name <name> --description <text> --prompt <text> --every <interval> [options]` | Create a recurring task from a human-friendly interval like `5m`, `2h`, or `1d` |
| `letta cron add --name <name> --description <text> --prompt <text> --at <time> [options]` | Create a one-time task for a time like `"3:00pm"` or `"in 45m"` |
| `letta cron add --name <name> --description <text> --prompt <text> --cron "<expr>" [options]` | Create a recurring task from a raw 5-field cron expression |
| `letta cron list [--agent <id>] [--conversation <id>]` | List tasks, optionally filtered by agent or conversation |
| `letta cron get <id>` | Show details for one task |
| `letta cron delete <id>` | Delete one task |
| `letta cron delete --all --agent <id>` | Delete all tasks for an agent |

### Required fields for `add`

[Section titled “Required fields for add”](https://docs.letta.com/letta-code/scheduling#required-fields-for-add)

*   `--name`: short label for the task
*   `--description`: longer summary of what the task is for
*   `--prompt`: the prompt that will be sent when the task fires
*   One schedule selector: `--every`, `--at`, or `--cron`
*   `--agent <id>` unless `LETTA_AGENT_ID` is already set in the environment

Conversation selection defaults to `LETTA_CONVERSATION_ID` when available, or `default` otherwise.

Current behavior and limits
---------------------------

[Section titled “Current behavior and limits”](https://docs.letta.com/letta-code/scheduling#current-behavior-and-limits)

These constraints are important enough to know before you depend on the feature:

*   Tasks only execute while `letta server` is connected.
*   One-shot tasks that are more than 5 minutes late are marked as missed.
*   Letta Code currently allows up to 50 active tasks per agent.
*   `--every 1d` fires daily at local midnight. Use `--cron` for a fixed time of day.
*   `--at` values are interpreted in your local timezone.
*   Raw cron expressions are evaluated in the local timezone by default.
*   All `letta cron` commands print JSON, so they work well in scripts and wrappers.

Examples
--------

[Section titled “Examples”](https://docs.letta.com/letta-code/scheduling#examples)

### Daily review

[Section titled “Daily review”](https://docs.letta.com/letta-code/scheduling#daily-review)

    letta cron add \  --agent agent-123 \  --name "daily-review" \  --description "Review recent changes every morning" \  --prompt "Review recent changes and summarize any issues." \  --cron "0 9 * * 1-5"

### One-time reminder

[Section titled “One-time reminder”](https://docs.letta.com/letta-code/scheduling#one-time-reminder)

    letta cron add \  --agent agent-123 \  --conversation default \  --name "deploy-reminder" \  --description "Remind me to validate staging before deploy" \  --prompt "Check staging health, review recent failures, and summarize anything blocking deploy." \  --at "in 45m"

### Frequent recurring check

[Section titled “Frequent recurring check”](https://docs.letta.com/letta-code/scheduling#frequent-recurring-check)

    letta cron add \  --agent agent-123 \  --name "log-watch" \  --description "Check logs every five minutes" \  --prompt "Inspect the latest logs and flag anything unusual." \  --every 5m

Troubleshooting
---------------

[Section titled “Troubleshooting”](https://docs.letta.com/letta-code/scheduling#troubleshooting)

*   **My task never ran**
    
    *   Make sure `letta server` was connected when the schedule should have fired.
    *   Run `letta cron list --agent <id>` and confirm the task is still active.
*   **My one-time task disappeared without running**
    
    *   If the listener was down for long enough, the task may have been marked as missed.

---

# Letta Code SDK migration guide | Letta Docs

[Skip to content](https://docs.letta.com/letta-code-sdk/migration/#_top)

Letta Code SDK

[Migrate Claude Agent SDK](https://docs.letta.com/letta-code-sdk/migration/)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

* * *

**Copy Markdown**

**View as Markdown**

Letta Code SDK migration guide
==============================

Migrate from the Claude Agent SDK to the Letta Code SDK

The Claude Agent SDK is **query-based** and does not expose a persistent agent entity; state lives in a **session/thread** resumed by `session_id`. Letta Code SDK is **agent-based** with persistent memory, and also supports multiple conversation threads per agent. The closest mental model depends on which Claude SDK interface you’re using.

Claude Agent SDK V2 (preview)
-----------------------------

[Section titled “Claude Agent SDK V2 (preview)”](https://docs.letta.com/letta-code-sdk/migration/#claude-agent-sdk-v2-preview)

V2 uses `createSession` / `resumeSession` with an explicit `send()` / `stream()` cycle per turn. This maps closely to Letta Code SDK.

### High-level mapping (V2)

[Section titled “High-level mapping (V2)”](https://docs.letta.com/letta-code-sdk/migration/#high-level-mapping-v2)

| Claude Agent SDK V2 | Letta Code SDK |
| --- | --- |
| `unstable_v2_prompt(...)` | `prompt(...)` |
| `unstable_v2_createSession(...)` | `createSession(...)` |
| `unstable_v2_resumeSession(session_id)` | `resumeSession(conversationId)` |
| `session.send(...)` | `session.send(...)` |
| `session.stream()` | `session.stream()` |

### Notes

[Section titled “Notes”](https://docs.letta.com/letta-code-sdk/migration/#notes)

*   Claude `session_id` corresponds to Letta `conversationId`.
*   Letta sessions are anchored to a persistent **agent**; Claude sessions are ephemeral unless you store the session ID.
*   If you want stateless behavior, use `prompt(...)` or create a fresh agent per run.

Claude Agent SDK V1 (query-based)
---------------------------------

[Section titled “Claude Agent SDK V1 (query-based)”](https://docs.letta.com/letta-code-sdk/migration/#claude-agent-sdk-v1-query-based)

V1 streams results from a single `query(...)` async generator. In Letta Code SDK, use `prompt(...)` for one-shots or `createSession(...).send()` + `stream()` for multi-turn flows.

### High-level mapping (V1)

[Section titled “High-level mapping (V1)”](https://docs.letta.com/letta-code-sdk/migration/#high-level-mapping-v1)

| Claude Agent SDK V1 | Letta Code SDK |
| --- | --- |
| `query({ prompt, options })` | `prompt(message)` or `createSession(...).send()` |

Key differences
---------------

[Section titled “Key differences”](https://docs.letta.com/letta-code-sdk/migration/#key-differences)

| Feature | Claude Agent SDK | Letta Code SDK |
| --- | --- | --- |
| Persistence model | Session-based (ephemeral) | Agent-based (persistent) |
| Memory | Session state only | Persistent memory blocks |
| Model support | Claude only | Claude, GPT, Gemini, local models |
| Multiple conversations | One per session | Multiple per agent |

Permissions and interactive tools
---------------------------------

[Section titled “Permissions and interactive tools”](https://docs.letta.com/letta-code-sdk/migration/#permissions-and-interactive-tools)

If you used Claude’s permission/user-input handling, the closest Letta Code SDK controls are:

*   `canUseTool(toolName, toolInput)` for runtime approval decisions.
*   `allowedTools` / `disallowedTools` for coarse allow/deny policy.
*   `permissionMode` (`default`, `acceptEdits`, `plan`, `bypassPermissions`) for global behavior.

In non-interactive headless flows, tools that require runtime user input (for example `AskUserQuestion` and `ExitPlanMode`) should be handled in `canUseTool` or blocked with `disallowedTools`.

Example migration
-----------------

[Section titled “Example migration”](https://docs.letta.com/letta-code-sdk/migration/#example-migration)

### Before (Claude Agent SDK V2)

[Section titled “Before (Claude Agent SDK V2)”](https://docs.letta.com/letta-code-sdk/migration/#before-claude-agent-sdk-v2)

    import {  unstable_v2_createSession,  unstable_v2_resumeSession,} from "@anthropic-ai/claude-agent-sdk";
    // Create new sessionawait using session = unstable_v2_createSession({  systemPrompt: "You are a helpful assistant.",});
    // Send messageawait session.send("Hello!");for await (const msg of session.stream()) {  console.log(msg);}
    // Resume laterawait using resumed = unstable_v2_resumeSession(session.sessionId);

### After (Letta Code SDK)

[Section titled “After (Letta Code SDK)”](https://docs.letta.com/letta-code-sdk/migration/#after-letta-code-sdk)

    import { createAgent, resumeSession } from "@letta-ai/letta-code-sdk";
    // Create new agent (persistent)const agentId = await createAgent({  systemPrompt: "You are a helpful assistant.",});
    // Resume agent's default conversationawait using session = resumeSession(agentId);
    // Send messageawait session.send("Hello!");for await (const msg of session.stream()) {  console.log(msg);}
    // Resume later - just use the agentIdawait using resumed = resumeSession(agentId);

> **Note:** In the Claude Agent SDK, you must save `sessionId` to resume. In Letta Code SDK, the **agent** persists—just use `resumeSession(agentId)` to continue where you left off.
> 
> For multiple concurrent conversations, use `createSession(agentId)` and `resumeSession(conversationId)`.

---

# Remote environments | Letta Docs

[Skip to content](https://docs.letta.com/letta-code/remote#_top)

Features

[Remote environments](https://docs.letta.com/letta-code/remote)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

* * *

**Copy Markdown**

**View as Markdown**

Remote environments
===================

Access your agent remotely from any device

Remote Environments are a way to separate where you **interact** with a Letta agent from where it **executes**. Using remote environments, you can interact with Letta agents from the [Letta Code desktop app](https://docs.letta.com/letta-code/quickstart)
 or [chat.letta.com](https://chat.letta.com/)
 that run locally on registered machines - meaning you can message an agent working on your laptop from your phone.

The same agent can even move between remote environments within a conversation, allowing agents to work across machines just like a human developer. When an agent moves between execution environments, all its memory (e.g. conversation history, context repositories, etc.) come with it.

You can continue a conversation on a remote sandbox on your local machine, and the agent will still have the same persistent memory and conversation history. You can see more about how Letta agent’s memory work with our latest blog post on context repositories.

Moving agents across machines
-----------------------------

[Section titled “Moving agents across machines”](https://docs.letta.com/letta-code/remote#moving-agents-across-machines)

Most agents today are defined by their environment: memories, skills, files, and other context are stored locally and must be explicitly transported. In contrast, human developers move between environments without losing context.

In Letta Code, all sessions are tied to a persistent agent that has an identity and associated memory. With remote environments in Letta Code, a single agent can work across:

*   Your laptop
*   An ephemeral sandbox
*   A remote VM (e.g. Railway, GCP)

Quickstart
----------

[Section titled “Quickstart”](https://docs.letta.com/letta-code/remote#quickstart)

*   [Desktop App](https://docs.letta.com/letta-code/remote#tab-panel-7)
    
*   [CLI](https://docs.letta.com/letta-code/remote#tab-panel-8)
    

1.  Install the [Letta Code desktop app](https://docs.letta.com/letta-code/quickstart)
    .
    
2.  Navigate to the app settings (top-left in MacOS), then enable “Allow remote access”.
    
3.  You can now deploy agents on the same machine you installed the Letta Code app on, and access them from any device!
    
    For example, if you enabled remote access on the Letta Code app installed on your home PC, you can now chat with agents running on your home PC via [chat.letta.com](https://chat.letta.com/)
     remotely, as long as the Letta Code app is running on your home PC.
    

1.  Install the Letta Code CLI (`npm install -g @letta-ai/letta-code`), and log in (run `letta` and use the OAuth link).
    
2.  Run `letta server` on any machine to start a WebSocket server and register it as a named execution environment for your agent. You can also specify the name directly: `letta server --env-name "work-laptop"`
    
3.  You can now deploy agents on the same machine you installed the Letta Code CLI on, and access them from any device!
    

Permission modes when working remotely
--------------------------------------

[Section titled “Permission modes when working remotely”](https://docs.letta.com/letta-code/remote#permission-modes-when-working-remotely)

Remote Environments carry the full human-in-the-loop approval flow over WebSocket. When the agent invokes a tool that requires approval, the approval request is surfaced in either the \[Letta Code\] chat.letta.com. The user can approve, deny, or edit the tool arguments before execution proceeds.

Cloud deployment
----------------

[Section titled “Cloud deployment”](https://docs.letta.com/letta-code/remote#cloud-deployment)

You can run `letta server` on a cloud VM or container so your agent is always-on. Since `letta server` only makes an **outbound WebSocket connection** to Letta Cloud, there are no inbound ports to open, no reverse proxy to configure, and no domain name needed.

### Authentication

[Section titled “Authentication”](https://docs.letta.com/letta-code/remote#authentication)

There are two ways to authenticate a remote `letta server`:

**Option A: OAuth device flow (recommended)**. If no API key is set, `letta server` starts an OAuth login flow and prints an authorization URL to stdout. This is the only authentication method on Pro, Max-lite, and Max plans.

**Option B: API key (Developer plans only)**. Set `LETTA_API_KEY` as an environment variable. Only available on Developer plans. On other plans, API key usage automatically spends credits.

With OAuth, the server prints an authorization URL on startup:

    No API key found. Starting OAuth login...
    To authenticate, visit: https://app.letta.com/oauth/device?user_code=ABCD-EFGHYour code: ABCD-EFGH
    Waiting for authorization...

Open the URL in your browser, approve the request, and the server authenticates and connects. Credentials are persisted to disk, so subsequent restarts authenticate automatically. Access tokens are refreshed on startup if expired.

Device flow is available only when `letta server` is talking to Letta Cloud (`https://api.letta.com`). Remote environments are a Letta Cloud feature. Self-hosted Letta servers do not currently support the remote environments API.

If you use OAuth on a remote machine or container, make sure `~/.letta/` lives on persistent storage. That is where Letta stores its fallback auth state when no system keychain is available.

### DigitalOcean

[Section titled “DigitalOcean”](https://docs.letta.com/letta-code/remote#digitalocean)

    # Create a dropletdoctl compute droplet create letta-remote \  --size s-1vcpu-512mb-10gb \  --image ubuntu-24-04-x64 \  --region sfo3 \  --ssh-keys $(doctl compute ssh-key list --format ID --no-header | head -1)

Or create one from the [DigitalOcean dashboard](https://cloud.digitalocean.com/droplets/new)
 — pick Ubuntu 24.04, the $4/mo plan, and your SSH key.

SSH in and install:

    ssh root@<droplet-ip>
    # Install Node.js 20 + build tools (needed for native modules)curl -fsSL https://deb.nodesource.com/setup_20.x | bash -apt-get install -y nodejs python3 make g++
    # Install Letta Codenpm install -g @letta-ai/letta-code
    # Start the serverletta server --env-name "cloud"

To keep it running across reboots, create a systemd service:

    cat > /etc/systemd/system/letta-server.service << 'EOF'[Unit]Description=Letta Code Remote ServerAfter=network-online.targetWants=network-online.target
    [Service]Type=simpleExecStart=/usr/bin/letta server --env-name "cloud"Restart=alwaysRestartSec=5
    [Install]WantedBy=multi-user.targetEOF
    systemctl daemon-reloadsystemctl enable --now letta-server

Before enabling the service, run `letta server --env-name "cloud"` once manually over SSH and complete the OAuth device flow in your browser. The saved auth state under `~/.letta/` is reused on restart. If the service ever needs re-authentication, check `journalctl -u letta-server -f` for the device code URL. Alternatively, add `Environment=LETTA_API_KEY=your-key` to the service file (Developer plans only).

### Fly.io

[Section titled “Fly.io”](https://docs.letta.com/letta-code/remote#flyio)

Clone the deployment repo:

    git clone https://github.com/letta-ai/letta-code-server-deployment.gitcd letta-code-server-deployment

Launch and deploy:

    fly launch --name letta-remote --no-deploy
    # Create a persistent volume for auth and statefly volumes create letta_data --region sjc --size 1
    fly deploy

The included `fly.toml` configures the volume mount and sets `ENV_NAME` to `"fly"`. After deploy, check the logs:

    fly logs --app letta-remote

Check the logs for the OAuth authorization URL, visit it in your browser, and approve the request. The mounted volume keeps `/root/.letta/` around, so auth survives machine restarts. On Developer plans, you can skip OAuth by setting `fly secrets set LETTA_API_KEY="your-key"` before deploying.

### Railway

[Section titled “Railway”](https://docs.letta.com/letta-code/remote#railway)

One-click deploy:

[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/letta-code-remote?utm_medium=integration&utm_source=template&utm_campaign=generic)

Or manually:

1.  Fork the [letta-code-server-deployment](https://github.com/letta-ai/letta-code-server-deployment)
     repo (or push your own Dockerfile)
2.  Connect the repo in [Railway](https://railway.app/)
    
3.  Add a persistent volume mounted at `/root` (to preserve auth and state across deploys)
4.  Deploy
5.  Open the deploy logs, find the OAuth URL, and approve it in your browser

Or use the Railway CLI:

    railway initrailway uprailway logs

After the first deploy, check the logs for the OAuth authorization URL. The volume at `/root` preserves auth state across restarts. On Developer plans, you can skip OAuth by setting `railway variables set LETTA_API_KEY="your-key"` before deploying.

### Which platform to choose

[Section titled “Which platform to choose”](https://docs.letta.com/letta-code/remote#which-platform-to-choose)

|     | DigitalOcean | Fly.io | Railway |
| --- | --- | --- | --- |
| **Setup** | SSH + 3 commands | Dockerfile + CLI | Git push or CLI |
| **Cost** | $4/mo flat | ~$3/mo usage | ~$5/mo usage |
| **Persistence** | systemd | Built-in | Built-in |
| **Best for** | Simplicity, full control | Infra-as-code workflows | Quick deploys from GitHub |

For most users, **DigitalOcean is the fastest path**: a $4 VM where you SSH in and run three commands. All platforms include ready-to-use configs in the [letta-code-server-deployment](https://github.com/letta-ai/letta-code-server-deployment)
 repo.

Configuration
-------------

[Section titled “Configuration”](https://docs.letta.com/letta-code/remote#configuration)

### Saved settings

[Section titled “Saved settings”](https://docs.letta.com/letta-code/remote#saved-settings)

| Setting | Location | Description |
| --- | --- | --- |
| `deviceId` | `~/.letta/settings.json` | Stable UUID, generated once |
| `listenerEnvName` | `.letta/settings.local.json` (per-project) | Saved environment name |
| Remote server state | `~/.letta/remote-settings.json` | Per-conversation working directories and permission modes restored after restarts |

### Session logs

[Section titled “Session logs”](https://docs.letta.com/letta-code/remote#session-logs)

| Path | Description |
| --- | --- |
| `~/.letta/logs/remote/{timestamp}.log` | Per-session transport log |

---

# GitHub Action | Letta Docs

[Skip to content](https://docs.letta.com/letta-code/github-action#_top)

Reference

[GitHub Action](https://docs.letta.com/letta-code/github-action)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

* * *

**Copy Markdown**

**View as Markdown**

GitHub Action
=============

Integrate Letta Code into your GitHub repository

The [Letta Code GitHub Action](https://github.com/letta-ai/letta-code-action)
 lets you trigger Letta agents directly from GitHub issues and pull requests. Mention `@letta-code` in any comment to get help with code questions, implementation, and reviews.

Quick start
-----------

[Section titled “Quick start”](https://docs.letta.com/letta-code/github-action#quick-start)

1.  Get an API key from [app.letta.com](https://app.letta.com/)
    
2.  Add `LETTA_API_KEY` to your repository secrets
3.  Create `.github/workflows/letta.yml`:

    name: Letta Code
    on:  issue_comment:    types: [created]  issues:    types: [opened, assigned]  pull_request_review_comment:    types: [created]
    jobs:  letta:    runs-on: ubuntu-latest    permissions:      contents: write      issues: write      pull-requests: write    steps:      - uses: actions/checkout@v4        with:          fetch-depth: 1      - uses: letta-ai/letta-code-action@v0        with:          letta_api_key: ${{ secrets.LETTA_API_KEY }}          github_token: ${{ secrets.GITHUB_TOKEN }}

Now mention `@letta-code` in any issue or PR comment.

Triggers
--------

[Section titled “Triggers”](https://docs.letta.com/letta-code/github-action#triggers)

The action runs when explicitly triggered:

| Trigger | How it works |
| --- | --- |
| **Mention** | Include `@letta-code` in a comment, issue body, or PR body |
| **Label** | Add the `letta-code` label to an issue (configurable via `label_trigger`) |
| **Assignee** | Assign a specific user to an issue (configure via `assignee_trigger`) |
| **Prompt** | Set the `prompt` input for automated workflows |

Replying to a comment without `@letta-code` will _not_ trigger the action.

Conversations
-------------

[Section titled “Conversations”](https://docs.letta.com/letta-code/github-action#conversations)

The GitHub Action supports persistent conversations that continue across multiple interactions.

### Issue conversations

[Section titled “Issue conversations”](https://docs.letta.com/letta-code/github-action#issue-conversations)

Each issue gets its own conversation, labeled as `owner/repo/issue-N`. When you mention `@letta-code` multiple times in the same issue, the agent remembers the full context of previous interactions.

### PR conversations

[Section titled “PR conversations”](https://docs.letta.com/letta-code/github-action#pr-conversations)

PRs can either:

*   **Start a new conversation** if the PR doesn’t reference an issue
*   **Continue an issue’s conversation** if the PR references an issue (via “Fixes #N”, “Closes #N”, etc.)

This means when you create a PR that fixes an issue, the agent already has the full context from the issue discussion.

### Viewing conversations

[Section titled “Viewing conversations”](https://docs.letta.com/letta-code/github-action#viewing-conversations)

Each agent response includes a link to view the conversation in the [Letta ADE](https://app.letta.com/)
:

    🤖 Agent: Memo • View job run💻 Chat with this agent in your terminal: letta --conv conv-abc123

You can continue the conversation locally using the CLI command shown.

Configuration
-------------

[Section titled “Configuration”](https://docs.letta.com/letta-code/github-action#configuration)

| Input | Description | Default |
| --- | --- | --- |
| `letta_api_key` | Your Letta API key | Required |
| `github_token` | GitHub token for API access | Required |
| `agent_id` | Specific agent ID to use (auto-discovers if not set) | None |
| `prompt` | Auto-trigger with this prompt | None |
| `trigger_phrase` | Phrase that activates the agent | `@letta-code` |
| `model` | Model to use (`opus`, `sonnet`, `haiku`, `auto`, `gpt-4.1`) | `opus` |
| `assignee_trigger` | Username that triggers when assigned | None |
| `label_trigger` | Label that triggers the action | `letta-code` |
| `path_to_letta_executable` | Path to a custom Letta Code CLI | None |
| `allowed_bots` | Comma-separated bot usernames allowed to trigger (or `*`) | None |
| `allowed_non_write_users` | Users allowed without write permissions | None |

### Using a specific agent

[Section titled “Using a specific agent”](https://docs.letta.com/letta-code/github-action#using-a-specific-agent)

To use the same agent across all issues/PRs in your repository:

    - uses: letta-ai/letta-code-action@v0  with:    letta_api_key: ${{ secrets.LETTA_API_KEY }}    github_token: ${{ secrets.GITHUB_TOKEN }}    agent_id: agent-586a9276-1e95-41f8-aaa4-0fb224398a01

This is useful when you want the agent to have shared memory across all repository interactions.

### Using the latest CLI

[Section titled “Using the latest CLI”](https://docs.letta.com/letta-code/github-action#using-the-latest-cli)

To ensure you’re using the latest Letta Code CLI:

    steps:  - uses: actions/checkout@v4
      - name: Install latest Letta Code    id: letta-bin    run: |      npm install -g @letta-ai/letta-code@latest      echo "path=$(command -v letta)" >> "$GITHUB_OUTPUT"
      - uses: letta-ai/letta-code-action@v0    with:      letta_api_key: ${{ secrets.LETTA_API_KEY }}      github_token: ${{ secrets.GITHUB_TOKEN }}      path_to_letta_executable: ${{ steps.letta-bin.outputs.path }}

Bracket syntax
--------------

[Section titled “Bracket syntax”](https://docs.letta.com/letta-code/github-action#bracket-syntax)

Pass arguments directly from your comment:

    @letta-code [--model haiku] quick question about this code@letta-code [--new-agent] start with a fresh agent@letta-code [--new-agent --model sonnet] new agent with a specific model

Multiple flags can be combined in a single bracket.

Agent persistence
-----------------

[Section titled “Agent persistence”](https://docs.letta.com/letta-code/github-action#agent-persistence)

The agent ID is stored in a hidden HTML comment in the tracking comment. On follow-up mentions, the action finds this metadata and resumes the same agent, preserving conversation history and memory.

To force a new agent, use: `@letta-code [--new-agent] start fresh`

Automated workflows
-------------------

[Section titled “Automated workflows”](https://docs.letta.com/letta-code/github-action#automated-workflows)

For workflows that run automatically (e.g., auto-review every PR):

    on:  pull_request:    types: [opened]
    jobs:  auto-review:    runs-on: ubuntu-latest    steps:      - uses: actions/checkout@v4      - uses: letta-ai/letta-code-action@v0        with:          letta_api_key: ${{ secrets.LETTA_API_KEY }}          github_token: ${{ secrets.GITHUB_TOKEN }}          prompt: "Review this PR for bugs and security issues"

Custom bot identity
-------------------

[Section titled “Custom bot identity”](https://docs.letta.com/letta-code/github-action#custom-bot-identity)

To have comments appear as `your-app[bot]` instead of `github-actions[bot]`, use a GitHub App:

    steps:  - uses: actions/checkout@v4  - name: Generate GitHub App token    id: app-token    uses: actions/create-github-app-token@v1    with:      app-id: ${{ secrets.APP_ID }}      private-key: ${{ secrets.APP_PRIVATE_KEY }}  - uses: letta-ai/letta-code-action@v0    with:      letta_api_key: ${{ secrets.LETTA_API_KEY }}      github_token: ${{ steps.app-token.outputs.token }}

Security
--------

[Section titled “Security”](https://docs.letta.com/letta-code/github-action#security)

By default, only repository collaborators with write access can trigger the action. This prevents unauthorized users on public repos from consuming your API credits.

Use `allowed_bots` for bot users or `allowed_non_write_users` to allow specific usernames without write permissions (use with caution).

Capabilities
------------

[Section titled “Capabilities”](https://docs.letta.com/letta-code/github-action#capabilities)

**What it can do:**

*   Read and search files in your repository
*   Make edits and create new files
*   Run shell commands (git, npm, etc.)
*   Commit and push changes
*   Create pull requests
*   Update its tracking comment with progress

**What it can’t do:**

*   Approve PRs (security restriction)
*   Modify workflow files (GitHub restriction)

CLI companion
-------------

[Section titled “CLI companion”](https://docs.letta.com/letta-code/github-action#cli-companion)

Continue chatting with the same agent locally using [Letta Code](https://docs.letta.com/letta-code/)
:

    # Installnpm install -g @letta-ai/letta-code
    # Resume the agent from GitHubletta --agent agent-xxxxx
    # Or resume a specific conversationletta --conv conv-xxxxx

The agent ID and conversation ID are shown in every GitHub comment footer.

Troubleshooting
---------------

[Section titled “Troubleshooting”](https://docs.letta.com/letta-code/github-action#troubleshooting)

**Agent not responding?**

*   Check that `LETTA_API_KEY` is set in repository secrets
*   Verify the workflow has the required permissions
*   Look at the Actions tab for error logs

**Wrong agent resumed?**

*   Use `@letta-code [--new-agent]` to force a fresh agent

**Want to see what the agent is doing?**

*   Click “View job run” in the comment footer
*   Enable `show_full_output: true` in your workflow for detailed logs

---

# Channels (beta) | Letta Docs

[Skip to content](https://docs.letta.com/letta-code/channels#_top)

Features

[Channels](https://docs.letta.com/letta-code/channels)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

* * *

**Copy Markdown**

**View as Markdown**

Channels (beta)
===============

Connect external messaging platforms to your Letta Code agents

Channels let your Letta Code agent receive and respond to messages from external platforms like Telegram and Slack. Messages from the platform flow into the agent’s conversation, and the agent replies using the `MessageChannel` tool.

Channels function as an additional communication option. You can combine channels with the [Letta Code app](https://docs.letta.com/letta-code/desktop-app)
, the [CLI](https://docs.letta.com/letta-code/cli)
, or [chat.letta.com](https://chat.letta.com/)
 — all connected to the same agent and memory.

Getting started
---------------

[Section titled “Getting started”](https://docs.letta.com/letta-code/channels#getting-started)

You can set up channels via the [Letta Code app](https://docs.letta.com/letta-code/desktop-app)
 or the CLI. The app provides a visual setup flow in the “Channels” sidebar tab. The CLI flow is documented below.

Telegram (CLI)
--------------

[Section titled “Telegram (CLI)”](https://docs.letta.com/letta-code/channels#telegram-cli)

### 1\. Create a bot

[Section titled “1. Create a bot”](https://docs.letta.com/letta-code/channels#1-create-a-bot)

Create a Telegram bot via [@BotFather](https://t.me/BotFather)
 and copy your bot token.

### 2\. Configure

[Section titled “2. Configure”](https://docs.letta.com/letta-code/channels#2-configure)

    letta channels configure telegram

The interactive wizard will:

*   Auto-install the Telegram runtime dependencies
*   Ask for your bot token (validates it against the Telegram API)
*   Let you choose a DM policy (`pairing`, `allowlist`, or `open`)

Config is written to `~/.letta/channels/telegram/accounts.json`.

### 3\. Start the server with channels enabled

[Section titled “3. Start the server with channels enabled”](https://docs.letta.com/letta-code/channels#3-start-the-server-with-channels-enabled)

    letta server --channels telegram

You’ll see `[Telegram] Bot started as @your_bot` in the output. The bot begins long-polling for messages immediately.

### 4\. Pair a Telegram chat to an agent

[Section titled “4. Pair a Telegram chat to an agent”](https://docs.letta.com/letta-code/channels#4-pair-a-telegram-chat-to-an-agent)

Send any message to your bot from Telegram. With the default `pairing` policy, the bot replies with a pairing code and instructions to complete setup in Letta Code.

You can complete the pairing from the CLI:

    letta channels pair \  --channel telegram \  --code B5ZR5H \  --agent <your-agent-id> \  --conversation <your-conversation-id>

The `--agent` flag defaults to the `LETTA_AGENT_ID` env var and `--conversation` defaults to `LETTA_CONVERSATION_ID` (or `"default"`).

You can also pair from within an active Letta Code session (app, CLI, or desktop):

    /channels telegram pair B5ZR5H

### 5\. Chat

[Section titled “5. Chat”](https://docs.letta.com/letta-code/channels#5-chat)

Messages from Telegram now flow into the agent’s conversation. The agent responds using the `MessageChannel` tool, which converts markdown to Telegram-safe HTML formatting (bold, italic, code, links, etc.).

Slack (CLI)
-----------

[Section titled “Slack (CLI)”](https://docs.letta.com/letta-code/channels#slack-cli)

### 1\. Create a Slack app

[Section titled “1. Create a Slack app”](https://docs.letta.com/letta-code/channels#1-create-a-slack-app)

1.  Go to [api.slack.com/apps](https://api.slack.com/apps)
     and click **Create New App**
2.  Choose **From a manifest**, select your workspace, paste the JSON manifest below, and create the app
3.  Generate an **app-level token**: go to **Settings > Basic Information**, scroll to **App-Level Tokens**, click **Generate Token and Scopes**, give it a name (e.g. “main”), add the `connections:write` scope, and click **Generate**. Copy the token (`xapp-...`).
4.  **Install the app**: go to **Settings > Install App**, click **Install to Workspace**, authorize, then copy the **Bot User OAuth Token** (`xoxb-...`)

Slack app manifest

    {  "display_information": {    "name": "Letta Code",    "description": "Slack connector for Letta Code"  },  "features": {    "bot_user": {      "display_name": "Letta Code Slack Bot",      "always_online": true    },    "app_home": {      "messages_tab_enabled": true,      "messages_tab_read_only_enabled": false    }  },  "oauth_config": {    "scopes": {      "bot": [        "app_mentions:read",        "channels:history",        "chat:write",        "files:read",        "files:write",        "groups:history",        "im:history",        "reactions:read",        "reactions:write",        "users:read"      ]    }  },  "settings": {    "org_deploy_enabled": false,    "socket_mode_enabled": true,    "is_hosted": false,    "token_rotation_enabled": false,    "event_subscriptions": {      "bot_events": [        "app_mention",        "message.channels",        "message.groups",        "message.im",        "reaction_added",        "reaction_removed"      ]    }  }}

This manifest pre-configures Socket Mode, all required scopes, event subscriptions, and App Home messaging.

### 2\. Configure

[Section titled “2. Configure”](https://docs.letta.com/letta-code/channels#2-configure-1)

    letta channels configure slack

The wizard asks for both tokens and your DM policy (`open` or `allowlist`).

If you choose `allowlist`, you’ll need Slack user IDs. To find a user ID: open the user’s profile in Slack, click the **three-dot menu** (⋯), and select **Copy member ID**. IDs start with `U` or `W`.

### 3\. Start the server

[Section titled “3. Start the server”](https://docs.letta.com/letta-code/channels#3-start-the-server)

    letta server --channels slack

### 4\. Bind the Slack app to an agent

[Section titled “4. Bind the Slack app to an agent”](https://docs.letta.com/letta-code/channels#4-bind-the-slack-app-to-an-agent)

Unlike Telegram (which uses pairing codes), Slack requires binding the app to an agent before any messages will route:

    letta channels bind --channel slack --agent <your-agent-id>

The `--agent` flag defaults to the `LETTA_AGENT_ID` env var. If you have multiple Slack accounts configured, pass `--account-id` to specify which one.

You can also bind from the [Letta Code app](https://docs.letta.com/letta-code/desktop-app)
 under **Channels > Slack**.

### 5\. Chat

[Section titled “5. Chat”](https://docs.letta.com/letta-code/channels#5-chat-1)

Once bound, DM the app or `@mention` it in a channel to start chatting.

**Slack routing behavior:**

*   **@mentions in channels**: Each mention creates a new conversation for the agent. The agent replies in-thread, and all subsequent messages in that thread are forwarded without requiring mentions.
*   **DMs**: Each DM chat gets a 1:1 mapping to a conversation. Routes are auto-created on first message.
*   **DM policy**: Slack defaults to `open` (recommended). `allowlist` is also supported for DMs. The `pairing` policy does not apply to Slack.

Architecture
------------

[Section titled “Architecture”](https://docs.letta.com/letta-code/channels#architecture)

flowchart LR
    subgraph Platform\["Messaging platform"\]
        TG\["Telegram / Slack"\]
    end

    subgraph Local\["Your machine (letta server)"\]
        Adapter\["Channel adapter<br/>(long-polling / Socket Mode)"\]
        Registry\["Channel registry"\]
        Queue\["Message queue"\]
        Agent\["Agent"\]
        Tool\["MessageChannel tool"\]
    end

    TG -->|"Inbound message"| Adapter
    Adapter --> Registry
    Registry -->|"XML-wrapped message"| Queue
    Queue --> Agent
    Agent -->|"Tool call"| Tool
    Tool -->|"Outbound reply"| TG

1.  The **adapter** receives messages from the platform (Telegram uses long-polling, Slack uses Socket Mode)
2.  The **registry** checks DM policy (pairing/allowlist/open), looks up the route, and formats the message as XML
3.  The message enters the agent’s **queue** as a `channel` source item
4.  The agent processes it and calls the **MessageChannel** tool to reply
5.  The tool converts markdown to platform-safe formatting and sends through the adapter

DM policies
-----------

[Section titled “DM policies”](https://docs.letta.com/letta-code/channels#dm-policies)

Each channel has a DM policy that controls who can message the bot:

| Policy | Behavior |
| --- | --- |
| `pairing` (default for Telegram) | Unknown users receive a one-time pairing code. An operator must approve the code to bind the chat to an agent. |
| `allowlist` | Only pre-configured user IDs can message. Others are rejected. |
| `open` (default for Slack) | Anyone can message. For Telegram, requires a route to exist. For Slack, routes are auto-created on first DM or @mention. |

Routing
-------

[Section titled “Routing”](https://docs.letta.com/letta-code/channels#routing)

Routes bind a platform chat ID to an agent + conversation pair. They’re stored in `~/.letta/channels/<channel>/routing.yaml`.

Routes are created automatically when pairing completes, or manually via the CLI:

    # Add a route manuallyletta channels route add \  --channel telegram \  --chat-id 123456789 \  --agent agent-abc123 \  --conversation default
    # List all routesletta channels route list
    # List routes for a specific channelletta channels route list --channel telegram
    # Remove a routeletta channels route remove --channel telegram --chat-id 123456789

CLI reference
-------------

[Section titled “CLI reference”](https://docs.letta.com/letta-code/channels#cli-reference)

| Command | Description |
| --- | --- |
| `letta channels install <channel>` | Install channel runtime dependencies (optional — `configure` does this automatically) |
| `letta channels configure <channel>` | Interactive setup wizard (installs runtime deps if needed) |
| `letta channels status` | Show config, routing, and pairing state (JSON) |
| `letta channels route list [--channel <ch>]` | Show routing table |
| `letta channels route add [options]` | Add a route binding a chat to an agent |
| `letta channels route remove [options]` | Remove a route |
| `letta channels bind [options]` | Bind a channel account to an agent (required for Slack) |
| `letta channels pair [options]` | Complete a pairing code and bind to agent (Telegram) |

### Common flags

[Section titled “Common flags”](https://docs.letta.com/letta-code/channels#common-flags)

| Flag | Commands | Description |
| --- | --- | --- |
| `--channel <name>` | route, pair | Channel name (`telegram`, `slack`) |
| `--account-id <id>` | route add/remove, pair | Account ID (required when multiple accounts exist for a channel, auto-resolved when only one exists) |
| `--chat-id <id>` | route add/remove | Platform chat/conversation ID |
| `--agent <id>` | route add, pair | Agent ID (defaults to `LETTA_AGENT_ID`) |
| `--conversation <id>` | route add, pair | Conversation ID (defaults to `LETTA_CONVERSATION_ID` or `"default"`) |
| `--code <code>` | pair | Pairing code from the bot |

Headless deployment
-------------------

[Section titled “Headless deployment”](https://docs.letta.com/letta-code/channels#headless-deployment)

For server/Docker deployments without interactive setup:

1.  Pre-write the config files to `~/.letta/channels/<channel>/`
2.  Start with the `--install-channel-runtimes` flag to auto-install dependencies:

    letta server --channels telegram --install-channel-runtimes

Or install runtimes separately:

    letta channels install telegram

### Environment variables

[Section titled “Environment variables”](https://docs.letta.com/letta-code/channels#environment-variables)

| Variable | Description |
| --- | --- |
| `LETTA_AGENT_ID` | Default agent ID for `pair` and `route add` commands |
| `LETTA_CONVERSATION_ID` | Default conversation ID (fallback: `"default"`) |
| `LETTA_API_KEY` | API key for `letta server` authentication |

State files
-----------

[Section titled “State files”](https://docs.letta.com/letta-code/channels#state-files)

| File | Description |
| --- | --- |
| `~/.letta/channels/<ch>/accounts.json` | Channel account configuration (tokens, DM policy, account metadata) |
| `~/.letta/channels/<ch>/routing.yaml` | Route table (chat ID to agent/conversation binding) |
| `~/.letta/channels/<ch>/pairing.yaml` | Pending and approved pairings |

Connection lifecycle
--------------------

[Section titled “Connection lifecycle”](https://docs.letta.com/letta-code/channels#connection-lifecycle)

Channels integrate with the `letta server` WebSocket connection:

*   On **connect**: channel adapters register their message handler and flush any buffered messages
*   On **disconnect**: adapters pause delivery but keep polling/listening. Messages buffer until reconnection.
*   On **shutdown**: adapters stop cleanly

This means if `letta server` briefly loses its WebSocket connection, no Telegram/Slack messages are dropped — they buffer and deliver when the connection restores.

You can also configure channels on [remote devices](https://docs.letta.com/letta-code/remote)
 — simply swap the selected device in the channels menu of the Letta Code app.

---

# Hooks | Letta Docs

[Skip to content](https://docs.letta.com/letta-code/hooks#_top)

Features

[Hooks](https://docs.letta.com/letta-code/hooks)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

* * *

**Copy Markdown**

**View as Markdown**

Hooks
=====

Run custom scripts at key points in the agent lifecycle

Hooks let you run custom scripts at key points during Letta Code’s execution. Use them to enforce policies, automate workflows, or integrate with external tools.

Hook Lifecycle
--------------

[Section titled “Hook Lifecycle”](https://docs.letta.com/letta-code/hooks#hook-lifecycle)

Hooks fire at specific points during a Letta Code session:

| Hook | When it fires | Can block? |
| --- | --- | --- |
| `PreToolUse` | Before tool execution | Yes |
| `PostToolUse` | After tool completes successfully | No  |
| `PostToolUseFailure` | After tool fails (stderr fed back to agent) | No  |
| `PermissionRequest` | When permission dialog appears | Yes |
| `UserPromptSubmit` | User submits a prompt | Yes |
| `Notification` | Letta Code sends a notification | No  |
| `Stop` | Agent finishes responding | Yes |
| `SubagentStop` | Subagent task completes | Yes |
| `PreCompact` | Before context compaction | No  |
| `SessionStart` | Session begins or resumes | No  |
| `SessionEnd` | Session terminates | No  |

Configuration
-------------

[Section titled “Configuration”](https://docs.letta.com/letta-code/hooks#configuration)

Hooks are configured in your settings files. Letta Code checks three locations (in priority order):

1.  `.letta/settings.local.json` - Local project settings (not committed)
2.  `.letta/settings.json` - Project settings (can commit to share with team)
3.  `~/.letta/settings.json` - User global settings

Hooks from all locations are merged, with local hooks running first.

### Structure

[Section titled “Structure”](https://docs.letta.com/letta-code/hooks#structure)

Tool-related hooks (`PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`) use matchers to specify which tools to target:

    {  "hooks": {    "PreToolUse": [      {        "matcher": "Bash",        "hooks": [          {            "type": "command",            "command": "./hooks/validate-bash.sh"          }        ]      }    ]  }}

Simple hooks (`Stop`, `Notification`, etc.) don’t need matchers:

    {  "hooks": {    "Stop": [      {        "hooks": [          {            "type": "command",            "command": "./hooks/run-on-stop.sh"          }        ]      }    ]  }}

### Matcher Patterns

[Section titled “Matcher Patterns”](https://docs.letta.com/letta-code/hooks#matcher-patterns)

| Pattern | Matches |
| --- | --- |
| `"Bash"` | Exact tool name |
| `"Edit\|Write"` | Multiple tools (regex alternation) |
| `"Notebook.*"` | Regex pattern |
| `"*"` or `""` | All tools |

### Managing Hooks

[Section titled “Managing Hooks”](https://docs.letta.com/letta-code/hooks#managing-hooks)

Use the `/hooks` command to view and manage your hook configuration interactively.

Hook types
----------

[Section titled “Hook types”](https://docs.letta.com/letta-code/hooks#hook-types)

Letta Code supports two types of hooks: **command hooks** that run shell scripts, and **prompt hooks** that use an LLM to evaluate actions.

### Command hooks

[Section titled “Command hooks”](https://docs.letta.com/letta-code/hooks#command-hooks)

Command hooks execute shell scripts and use exit codes to allow or block actions. This is the default hook type, covered in detail in the [Writing hooks](https://docs.letta.com/letta-code/hooks#writing-hooks)
 section below.

    {  "type": "command",  "command": "./hooks/validate-bash.sh",  "timeout": 60000}

### Prompt hooks

[Section titled “Prompt hooks”](https://docs.letta.com/letta-code/hooks#prompt-hooks)

Prompt hooks send the hook input to an LLM for evaluation instead of running a shell script. The LLM decides whether to allow or block the action based on your prompt.

    {  "type": "prompt",  "prompt": "Block any Bash commands that modify files outside the src/ directory. Only allow read operations on system files.",  "model": "haiku",  "timeout": 30000}

| Field | Required | Description |
| --- | --- | --- |
| `type` | Yes | Must be `"prompt"` |
| `prompt` | Yes | Instructions for the LLM to evaluate the action |
| `model` | No  | Model to use for evaluation (defaults to agent’s model) |
| `timeout` | No  | Timeout in milliseconds (default: 30000) |

Use `$ARGUMENTS` in your prompt to reference the hook input JSON. If omitted, the input is appended automatically.

Prompt hooks are shown with a `✦` indicator in the `/hooks` manager.

**Supported events:** `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `UserPromptSubmit`, `Stop`, `SubagentStop`

**Example: Block dangerous operations with natural language**

    {  "hooks": {    "PreToolUse": [      {        "matcher": "Bash",        "hooks": [          {            "type": "prompt",            "prompt": "Block any commands that delete files, modify system configuration, or access sensitive directories like /etc or ~/.ssh. Allow normal development commands.",            "model": "haiku"          }        ]      }    ]  }}

Writing Hooks
-------------

[Section titled “Writing Hooks”](https://docs.letta.com/letta-code/hooks#writing-hooks)

### Input Format

[Section titled “Input Format”](https://docs.letta.com/letta-code/hooks#input-format)

Hooks receive JSON data via stdin containing context about the event:

    {  "event_type": "PreToolUse",  "working_directory": "/path/to/project",  "tool_name": "Bash",  "tool_input": {    "command": "npm test"  }}

The exact fields vary by event type. Tool-related events include `tool_name` and `tool_input`. Session events include agent and conversation IDs.

#### Reasoning and Message Context

[Section titled “Reasoning and Message Context”](https://docs.letta.com/letta-code/hooks#reasoning-and-message-context)

`PostToolUse` and `Stop` hooks include the agent’s reasoning and messages that led to the action:

**PostToolUse** includes:

*   `preceding_reasoning` - the agent’s thinking that led to the tool call
*   `preceding_assistant_message` - any assistant text before the tool call

**Stop** includes:

*   `preceding_reasoning` - the agent’s thinking that led to the final response
*   `assistant_message` - the agent’s final message to the user
*   `user_message` - the user’s original prompt that started this turn

Example Stop hook input:

    {  "event_type": "Stop",  "stop_reason": "end_turn",  "preceding_reasoning": "The user asked about the project structure. I should summarize what I found.",  "assistant_message": "Here's an overview of the project structure...",  "user_message": "What does this project look like?"}

This enables logging, analysis, and automation based on agent reasoning.

### Exit Codes

[Section titled “Exit Codes”](https://docs.letta.com/letta-code/hooks#exit-codes)

| Exit Code | Behavior |
| --- | --- |
| `0` | Success - action proceeds normally |
| `1` | Non-blocking error - logged, action continues |
| `2` | Blocking error - action stopped, stderr shown to agent |

For blocking hooks (`PreToolUse`, `PermissionRequest`, `Stop`, etc.), exit code 2 prevents the action and sends your stderr message to the agent as feedback.

### Additional context injection

[Section titled “Additional context injection”](https://docs.letta.com/letta-code/hooks#additional-context-injection)

`PostToolUse` hooks that exit with code 0 can inject additional context into the agent’s conversation by printing JSON to stdout. The JSON should contain an `additionalContext` field (either at the top level or nested under `hookSpecificOutput`):

    {  "additionalContext": "The tests passed but code coverage dropped to 72%."}

Or:

    {  "hookSpecificOutput": {    "additionalContext": "Lint warnings found in the changed files."  }}

The `additionalContext` string is fed back to the agent as context after the tool completes. Non-JSON stdout is ignored.

#### Where hook feedback is injected

[Section titled “Where hook feedback is injected”](https://docs.letta.com/letta-code/hooks#where-hook-feedback-is-injected)

*   `PostToolUse` `additionalContext` is injected as hook feedback after the tool call completes.
*   `UserPromptSubmit` hook feedback is injected as a `<system-reminder>` for that turn.

Hook feedback is turn context, not a memory block write.

#### Real-time machine state pattern

[Section titled “Real-time machine state pattern”](https://docs.letta.com/letta-code/hooks#real-time-machine-state-pattern)

For continuously changing context (for example foreground window, running processes, active app), prefer a pull-based pattern:

1.  Run a local watcher that updates a single snapshot source (such as `runtime_state.json`).
2.  Expose a custom tool (for example `get_runtime_state`) that reads the latest snapshot on demand.
3.  Have the agent call that tool when needed, instead of injecting repeated chat context.

This keeps context fresh without continuously adding stale copies to the transcript.

### Timeouts

[Section titled “Timeouts”](https://docs.letta.com/letta-code/hooks#timeouts)

Hooks have a default timeout of 60 seconds. You can configure a custom timeout per hook:

    {  "type": "command",  "command": "./hooks/slow-check.sh",  "timeout": 120000}

Timeout is specified in milliseconds.

Examples
--------

[Section titled “Examples”](https://docs.letta.com/letta-code/hooks#examples)

### Block dangerous commands

[Section titled “Block dangerous commands”](https://docs.letta.com/letta-code/hooks#block-dangerous-commands)

Prevent `rm -rf` commands while still allowing the agent to work autonomously:

    #!/bin/bash# Block dangerous rm -rf commands
    input=$(cat)tool_name=$(echo "$input" | jq -r '.tool_name')
    # Only check Bash commandsif [ "$tool_name" != "Bash" ]; then  exit 0fi
    command=$(echo "$input" | jq -r '.tool_input.command')
    # Check for rm -rf patternif echo "$command" | grep -qE 'rm\s+(-[a-zA-Z]*r[a-zA-Z]*f|-[a-zA-Z]*f[a-zA-Z]*r)'; then  echo "Blocked: rm -rf commands must be run manually." >&2  exit 2fi
    exit 0

    {  "hooks": {    "PreToolUse": [      {        "matcher": "Bash",        "hooks": [          {            "type": "command",            "command": "./hooks/block-rm-rf.sh"          }        ]      }    ]  }}

### Auto-fix on changes

[Section titled “Auto-fix on changes”](https://docs.letta.com/letta-code/hooks#auto-fix-on-changes)

Run linting automatically after the agent makes changes:

    #!/bin/bash# Run bun run fix if there are uncommitted changes
    # Check if there are any uncommitted changesif git diff --quiet HEAD 2>/dev/null; then    echo "No changes, skipping."    exit 0fi
    # Run fix - capture output and send to stderr on failureoutput=$(bun run fix 2>&1)exit_code=$?
    if [ $exit_code -eq 0 ]; then    echo "$output"    exit 0else    echo "$output" >&2    exit 2fi

    {  "hooks": {    "Stop": [      {        "hooks": [          {            "type": "command",            "command": "./hooks/fix-on-changes.sh"          }        ]      }    ]  }}

### Type checking on changes

[Section titled “Type checking on changes”](https://docs.letta.com/letta-code/hooks#type-checking-on-changes)

Similar to linting, run type checking after changes:

    #!/bin/bash# Run typecheck if there are uncommitted changes
    if git diff --quiet HEAD 2>/dev/null; then    echo "No changes, skipping."    exit 0fi
    output=$(tsc --noEmit --pretty 2>&1)exit_code=$?
    if [ $exit_code -eq 0 ]; then    echo "$output"    exit 0else    echo "$output" >&2    exit 2fi

### Log agent reasoning

[Section titled “Log agent reasoning”](https://docs.letta.com/letta-code/hooks#log-agent-reasoning)

Capture agent reasoning and responses to a log file for analysis:

    #!/bin/bash# Log agent reasoning and responses
    input=$(cat)timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")event_type=$(echo "$input" | jq -r '.event_type')reasoning=$(echo "$input" | jq -r '.preceding_reasoning // empty')message=$(echo "$input" | jq -r '.assistant_message // empty')
    log_file="${HOME}/.letta/reasoning.log"
    if [ -n "$reasoning" ] || [ -n "$message" ]; then  echo "=== $timestamp ($event_type) ===" >> "$log_file"  [ -n "$reasoning" ] && echo "Reasoning: $reasoning" >> "$log_file"  [ -n "$message" ] && echo "Message: $message" >> "$log_file"  echo "" >> "$log_file"fi
    exit 0

    {  "hooks": {    "Stop": [      {        "hooks": [          {            "type": "command",            "command": "./hooks/log-reasoning.sh"          }        ]      }    ]  }}

### Desktop notifications

[Section titled “Desktop notifications”](https://docs.letta.com/letta-code/hooks#desktop-notifications)

Get notified when Letta Code needs attention (macOS):

    #!/bin/bash# Send desktop notification using osascript (macOS)
    input=$(cat)message=$(echo "$input" | jq -r '.message')level=$(echo "$input" | jq -r '.level')
    if [ "$level" = "error" ]; then  osascript -e "display notification \"$message\" with title \"Letta Code\" subtitle \"Error\""elif [ "$level" = "warning" ]; then  osascript -e "display notification \"$message\" with title \"Letta Code\" subtitle \"Warning\""else  osascript -e "display notification \"$message\" with title \"Letta Code\""fi
    exit 0

    {  "hooks": {    "Notification": [      {        "hooks": [          {            "type": "command",            "command": "./hooks/desktop-notification.sh"          }        ]      }    ]  }}

---

# Headless mode | Letta Docs

[Skip to content](https://docs.letta.com/letta-code/headless#_top)

Reference

[Headless mode](https://docs.letta.com/letta-code/headless)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

* * *

**Copy Markdown**

**View as Markdown**

Headless mode
=============

Run Letta Code non-interactively for scripting and automation

Headless mode allows you to run Letta Code non-interactively, making it easy to integrate into scripts, CI/CD pipelines, or compose with other UNIX tools.

Basic usage
-----------

[Section titled “Basic usage”](https://docs.letta.com/letta-code/headless#basic-usage)

Use the `-p` flag to pass a prompt directly:

    letta -p "Look around this repo and write a README.md documenting it"

You can also pipe input to Letta Code:

    echo "Explain this error" | letta -p

Output formats
--------------

[Section titled “Output formats”](https://docs.letta.com/letta-code/headless#output-formats)

Letta Code supports three output formats in headless mode:

### Text (default)

[Section titled “Text (default)”](https://docs.letta.com/letta-code/headless#text-default)

Returns the agent’s response as plain text:

    letta -p "What files are in this directory?"

### JSON

[Section titled “JSON”](https://docs.letta.com/letta-code/headless#json)

Returns a structured JSON response with metadata:

    letta -p "List all TypeScript files" --output-format json

    {  "type": "result",  "result": "Found 15 TypeScript files...",  "agent_id": "agent-abc123",  "conversation_id": "conversation-xyz789",  "usage": {    "prompt_tokens": 1250,    "completion_tokens": 89  }}

### Stream JSON

[Section titled “Stream JSON”](https://docs.letta.com/letta-code/headless#stream-json)

Returns line-delimited JSON events for real-time streaming. This is useful for preventing timeouts and getting incremental progress:

    letta -p "Explain this codebase" --output-format stream-json

Each line is a JSON event:

    {"type":"system","subtype":"init","agent_id":"agent-...","conversation_id":"conversation-...","session_id":"agent-...","model":"claude-sonnet-4-6","tools":[...]}{"type":"message","message_type":"reasoning_message","reasoning":"The user is asking...","otid":"...","seq_id":1}{"type":"message","message_type":"assistant_message","content":"Here's an overview...","otid":"...","seq_id":5}{"type":"message","message_type":"stop_reason","stop_reason":"end_turn"}{"type":"message","message_type":"usage_statistics","prompt_tokens":294,"completion_tokens":97}{"type":"result","subtype":"success","result":"Here's an overview...","agent_id":"...","conversation_id":"...","session_id":"...","uuid":"..."}

Messages are streamed at the token level - each chunk has the same `otid` (output turn ID) and incrementing `seq_id`.

Bidirectional mode
------------------

[Section titled “Bidirectional mode”](https://docs.letta.com/letta-code/headless#bidirectional-mode)

For programmatic control, use `--input-format stream-json` to enable bidirectional JSON communication over stdin/stdout. This allows external programs to send messages and receive responses in a structured format.

    letta -p --input-format stream-json --output-format stream-json

### Input message types

[Section titled “Input message types”](https://docs.letta.com/letta-code/headless#input-message-types)

Send JSON messages to stdin (one per line):

    {  "type": "user",  "message": { "role": "user", "content": "What files are here?" }}

    {  "type": "control_request",  "request_id": "init_1",  "request": { "subtype": "initialize" }}

    {  "type": "control_request",  "request_id": "int_1",  "request": { "subtype": "interrupt" }}

### Output message types

[Section titled “Output message types”](https://docs.letta.com/letta-code/headless#output-message-types)

The CLI emits JSON messages to stdout:

    {"type": "system", "subtype": "init", "agent_id": "agent-xxx", "conversation_id": "conversation-xxx", "session_id": "agent-xxx", "model": "...", "tools": [...]}

    {"type": "control_response", "response": {"subtype": "success", "request_id": "init_1", "response": {...}}}

    {  "type": "control_request",  "request_id": "perm-123",  "request": {    "subtype": "can_use_tool",    "tool_name": "Bash",    "input": { "command": "ls" }  }}

    {  "type": "message",  "message_type": "assistant_message",  "content": "Hello!",  "session_id": "...",  "uuid": "..."}

    {  "type": "result",  "subtype": "success",  "result": "Hello!",  "session_id": "...",  "agent_id": "...",  "conversation_id": "..."}

### Interactive tool behavior

[Section titled “Interactive tool behavior”](https://docs.letta.com/letta-code/headless#interactive-tool-behavior)

In one-shot headless mode (`-p` without `--input-format stream-json`), there is no control channel for runtime user input. Interactive tools therefore behave differently:

*   `AskUserQuestion` is excluded from the headless toolset entirely.
*   `EnterPlanMode` can proceed.
*   `ExitPlanMode` is denied when it requires runtime user input.

In bidirectional mode (`--input-format stream-json`), permission requests are emitted as `control_request` messages with `subtype: "can_use_tool"`. Your host process should answer with a matching `control_response`.

### Multi-turn conversations

[Section titled “Multi-turn conversations”](https://docs.letta.com/letta-code/headless#multi-turn-conversations)

The process stays alive until stdin closes, allowing multi-turn conversations:

    (echo '{"type": "user", "message": {"role": "user", "content": "Remember: secret is BANANA"}}'sleep 5echo '{"type": "user", "message": {"role": "user", "content": "What was the secret?"}}') | letta -p --input-format stream-json --output-format stream-json

### Token-level streaming

[Section titled “Token-level streaming”](https://docs.letta.com/letta-code/headless#token-level-streaming)

Add `--include-partial-messages` to receive token-level streaming events:

    letta -p --input-format stream-json --output-format stream-json --include-partial-messages

This wraps each chunk in a `stream_event`:

    {  "type": "stream_event",  "event": { "message_type": "assistant_message", "content": "Hel" },  "session_id": "...",  "uuid": "..."}

Agent and conversation selection
--------------------------------

[Section titled “Agent and conversation selection”](https://docs.letta.com/letta-code/headless#agent-and-conversation-selection)

By default, headless mode uses the last agent from the current directory and its “default” conversation. Your agent retains memory across all runs, and the default conversation preserves message history between sessions.

To create a new conversation for parallel sessions, use `--new`:

    letta -p "..." --new

    letta -p "..." --new-agent

    letta -p "..." --agent <agent-id>

    letta -p "..." --conversation <conversation-id>

The JSON and stream-json output formats include a `conversation_id` field, which you can use to continue the same conversation in subsequent calls:

    result=$(letta -p "Start a new task" --output-format json)conv_id=$(echo $result | jq -r '.conversation_id')
    # Continue the same conversationletta -p "Continue where we left off" --conversation $conv_id --output-format json

Model selection
---------------

[Section titled “Model selection”](https://docs.letta.com/letta-code/headless#model-selection)

Specify a model for the headless run:

    letta -p "..." --model sonnetletta -p "..." --model autoletta -p "..." -m gpt-5-codexletta -p "..." -m haiku

Specify an embedding model when creating a new agent:

    letta -p "..." --new-agent --embedding letta/letta-free

See [Models](https://docs.letta.com/letta-code/models)
 for the full list of supported model IDs.

Permission control
------------------

[Section titled “Permission control”](https://docs.letta.com/letta-code/headless#permission-control)

### Auto-allow all tools

[Section titled “Auto-allow all tools”](https://docs.letta.com/letta-code/headless#auto-allow-all-tools)

Use `--yolo` to bypass permission prompts for most tools (use with caution). `ExitPlanMode` still requires manual approval:

    letta -p "Refactor this file" --yolo

### Restrict available tools

[Section titled “Restrict available tools”](https://docs.letta.com/letta-code/headless#restrict-available-tools)

The `--tools` flag controls which tools are _attached_ to the agent (removing them from the context window entirely):

    letta -p "Analyze this codebase" --tools "Read,Glob,Grep"

    letta -p "What do you think about this approach?" --tools ""

This is different from `--allowedTools`/`--disallowedTools` which control permissions but keep tools in context. See [Permissions](https://docs.letta.com/letta-code/permissions)
 for more details.

### Permission modes

[Section titled “Permission modes”](https://docs.letta.com/letta-code/headless#permission-modes)

    letta -p "Fix the type errors" --permission-mode acceptEdits

    letta -p "Review this PR" --permission-mode plan

Advanced options
----------------

[Section titled “Advanced options”](https://docs.letta.com/letta-code/headless#advanced-options)

### Resume by name

[Section titled “Resume by name”](https://docs.letta.com/letta-code/headless#resume-by-name)

Use `-n` or `--name` to resume an agent by name (case-insensitive). Matches pinned agents or recent agents:

    letta -p "Continue where we left off" --name myproject

### System prompt configuration

[Section titled “System prompt configuration”](https://docs.letta.com/letta-code/headless#system-prompt-configuration)

Customize the agent’s system prompt when creating new agents:

    letta -p "..." --new-agent --system letta-claude

    letta -p "..." --new-agent --system-custom "You are a Python expert who writes clean code."

**Available presets:**

*   `default` - Letta-tuned system prompt
*   `letta-claude` - Full Letta Code prompt (Claude-optimized)
*   `letta-codex` - Full Letta Code prompt (Codex-optimized)
*   `letta-gemini` - Full Letta Code prompt (Gemini-optimized)
*   `claude` - Basic Claude (no skills/memory instructions)
*   `codex` - Basic Codex
*   `gemini` - Basic Gemini

### Memory block configuration

[Section titled “Memory block configuration”](https://docs.letta.com/letta-code/headless#memory-block-configuration)

Customize which memory blocks the agent uses:

    letta -p "..." --new-agent --init-blocks "persona,project"

    letta -p "..." --new-agent --init-blocks "persona,project" \  --block-value persona="You are a Go expert" \  --block-value project="CLI tool for Docker"

    letta -p "..." --new-agent --memory-blocks '[  {"label": "context", "value": "API documentation for Acme Corp..."},  {"label": "rules", "value": "Always use TypeScript"}]'

    letta -p "..." --new-agent --init-blocks ""

**Available preset blocks:**

*   `persona` - Agent’s personality and behavior
*   `human` - Information about the user
*   `project` - Current project context

### Toolset override

[Section titled “Toolset override”](https://docs.letta.com/letta-code/headless#toolset-override)

Force a specific toolset instead of auto-detection based on model:

    letta -p "..." --toolset codex    # Codex-style toolsletta -p "..." --toolset gemini   # Gemini-style toolsletta -p "..." --toolset default  # Default Letta tools

### Base tools configuration

[Section titled “Base tools configuration”](https://docs.letta.com/letta-code/headless#base-tools-configuration)

When creating a new agent with `--new-agent`, specify which base tools to attach:

    letta -p "..." --new-agent --base-tools "memory,web_search"

### Create from AgentFile

[Section titled “Create from AgentFile”](https://docs.letta.com/letta-code/headless#create-from-agentfile)

Create an agent from an AgentFile template or the agent registry:

    letta -p "..." --import ./my-agent.afletta -p "..." --import @author/agent-name

### System prompt configuration

[Section titled “System prompt configuration”](https://docs.letta.com/letta-code/headless#system-prompt-configuration-1)

Customize the agent’s system prompt:

    letta -p "..." --system-custom "You are a helpful assistant that only responds in haiku."

### Memory block configuration

[Section titled “Memory block configuration”](https://docs.letta.com/letta-code/headless#memory-block-configuration-1)

Configure memory blocks when creating agents:

    letta -p "..." --new-agent --memory-blocks '{"persona": "You are a code reviewer", "project": "React app"}'

    letta -p "..." --block-value "persona=You are a security auditor" --block-value "project=Backend API"

Examples
--------

[Section titled “Examples”](https://docs.letta.com/letta-code/headless#examples)

### Automated tasks

[Section titled “Automated tasks”](https://docs.letta.com/letta-code/headless#automated-tasks)

    letta -p "Run the linter and fix any errors" --yolo

### Structured output for scripts

[Section titled “Structured output for scripts”](https://docs.letta.com/letta-code/headless#structured-output-for-scripts)

Use JSON output to parse results programmatically:

    result=$(letta -p "What is the main entry point of this project?" --output-format json)echo $result | jq '.result'

### Read-only analysis

[Section titled “Read-only analysis”](https://docs.letta.com/letta-code/headless#read-only-analysis)

Use `--tools` to restrict the agent to read-only operations:

    letta -p "Review this codebase for potential security issues" --tools "Read,Glob,Grep"

### Shell cron with `letta -p`

[Section titled “Shell cron with letta -p”](https://docs.letta.com/letta-code/headless#shell-cron-with-letta--p)

Run Letta Code on a schedule using cron:

    0 9 * * * cd /path/to/project && letta -p "Review recent changes and summarize any issues" --tools "Read,Glob,Grep" --output-format json >> /var/log/letta-review.log 2>&1

    0 10 * * 1 cd /path/to/project && letta -p "Check for outdated dependencies and security vulnerabilities" --yolo >> /var/log/letta-deps.log 2>&1

---

# Slash commands | Letta Docs

[Skip to content](https://docs.letta.com/letta-code/slash-commands#_top)

Reference

[Slash commands](https://docs.letta.com/letta-code/slash-commands)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

* * *

**Copy Markdown**

**View as Markdown**

Slash commands
==============

Control Letta Code's behavior during an interactive session with slash commands

Control Letta Code’s behavior during an interactive session with slash commands. Press `Tab` to autocomplete command names.

Built-in slash commands
-----------------------

[Section titled “Built-in slash commands”](https://docs.letta.com/letta-code/slash-commands#built-in-slash-commands)

| Command | Description |
| --- | --- |
| `/agents` | Browse agents (pinned, Letta Code, all) |
| `/resume [id]` | Browse and resume past conversations (or switch directly by ID) |
| `/model` | Switch model |
| `/init` | Run deep memory initialization (or re-init) |
| `/doctor` | Audit and refine your memory structure |
| `/remember [text]` | Remember something from the conversation |
| `/skill-creator [description]` | Enter guided skill creation mode |
| `/memory` | View your agent’s memory blocks |
| `/search` | Search messages (defaults to the current agent) |
| `/new [name]` | Start a new conversation, optionally with a name |
| `/fork [summary]` | Fork the current conversation into a new thread |
| `/clear` | Clear in-context messages |
| `/compact [all\|sliding_window]` | Summarize conversation history (compaction) |
| `/pin [-l] [name]` | Pin current agent globally (`-l` for local only) |
| `/unpin [-l]` | Unpin current agent (`-l` for local only) |
| `/rename <name>` | Rename the current agent |
| `/description <text>` | Update the current agent’s description |
| `/export` | Export AgentFile (.af) |
| `/toolset` | Switch toolset (default/codex/gemini) |
| `/server [--env-name <name>]` | Start local server listener mode (alias: `/remote`) |
| `/ade` | Open agent in ADE (browser) |
| `/system` | Switch system prompt |
| `/personality` | Switch to a curated personality preset |
| `/subagents` | Manage custom subagents |
| `/mcp` | Manage MCP servers |
| `/secret` | Manage secrets (`set`, `list`, `unset`) |
| `/skills` | Browse available skills by source |
| `/statusline` | Configure CLI footer status lines |
| `/sleeptime` | Configure reflection trigger settings |
| `/recompile` | Recompile the current agent and conversation |
| `/context` | Show context window usage (tokens used vs available) |
| `/usage` | Show session usage statistics and balance |
| `/feedback` | Send feedback to the Letta team |
| `/empanada [address]` | Order empanadas from Empanada Empire |
| `/terminal [--revert]` | Setup terminal shortcuts (Shift+Enter) |
| `/connect chatgpt` | Connect ChatGPT Pro/Plus (alias: `/connect codex`) |
| `/disconnect chatgpt` | Disconnect ChatGPT Pro/Plus (alias: `/disconnect codex`) |
| `/bg` | Show background shell processes |
| `/exit` | Exit this session |
| `/logout` | Clear credentials and exit |

`/skill-creator` replaces the older `/skill` shortcut in the interactive CLI.

Custom slash commands
---------------------

[Section titled “Custom slash commands”](https://docs.letta.com/letta-code/slash-commands#custom-slash-commands)

Custom slash commands let you define frequently used prompts as Markdown files that Letta Code can execute. Commands can be project-specific (shared with your team) or personal (available across all projects).

### Syntax

[Section titled “Syntax”](https://docs.letta.com/letta-code/slash-commands#syntax)

    /<command-name> [arguments]

| Parameter | Description |
| --- | --- |
| `<command-name>` | Name derived from the Markdown filename (without `.md` extension) |
| `[arguments]` | Optional arguments passed to the command |

### Command types

[Section titled “Command types”](https://docs.letta.com/letta-code/slash-commands#command-types)

#### Project commands

[Section titled “Project commands”](https://docs.letta.com/letta-code/slash-commands#project-commands)

Commands stored in your repository and shared with your team. These show “(project)” in `/help`.

**Location**: `.commands/`

    # Create a project commandmkdir -p .commandsecho "Review this code for security vulnerabilities:" > .commands/security.md

#### Personal commands

[Section titled “Personal commands”](https://docs.letta.com/letta-code/slash-commands#personal-commands)

Commands available across all your projects. These show “(user)” in `/help`.

**Location**: `~/.letta/commands/`

    # Create a personal commandmkdir -p ~/.letta/commandsecho "Explain this code in simple terms:" > ~/.letta/commands/explain.md

### Arguments

[Section titled “Arguments”](https://docs.letta.com/letta-code/slash-commands#arguments)

Pass dynamic values to commands using argument placeholders:

**All arguments with `$ARGUMENTS`**

    Fix issue #$ARGUMENTS following our coding standards

Usage: `/fix-issue 123 high-priority` → `$ARGUMENTS` becomes “123 high-priority”

**Positional arguments with `$1`, `$2`, etc.**

    Review PR #$1 with priority $2 and assign to $3

Usage: `/review-pr 456 high alice` → `$1`\=“456”, `$2`\=“high”, `$3`\=“alice”

### Dynamic content

[Section titled “Dynamic content”](https://docs.letta.com/letta-code/slash-commands#dynamic-content)

Execute shell commands when the slash command runs using `` !`command` `` syntax:

    Current branch: !`git branch --show-current`Recent commits:!`git log --oneline -5`

Shell commands are executed and replaced with their output.

### File references

[Section titled “File references”](https://docs.letta.com/letta-code/slash-commands#file-references)

Include file contents using the `@` prefix:

    Review the implementation in @src/utils/helpers.js
    Compare @src/old-version.js with @src/new-version.js

### Frontmatter

[Section titled “Frontmatter”](https://docs.letta.com/letta-code/slash-commands#frontmatter)

Command files support frontmatter for metadata:

| Property | Purpose | Default |
| --- | --- | --- |
| `description` | Brief description shown in `/help` | First line of prompt |
| `argument-hint` | Arguments expected (shown in autocomplete) | None |

**Example:**

    ---description: Review code changes in the current branchargument-hint: "[focus area]"---
    Review all uncommitted changes in this repository. Focus on:
    - Code quality and best practices- Potential bugs or edge cases- Suggestions for improvement
    $ARGUMENTS

### Priority

[Section titled “Priority”](https://docs.letta.com/letta-code/slash-commands#priority)

Project commands (`.commands/`) take precedence over global commands (`~/.letta/commands/`). Custom commands appear in autocomplete alongside built-in commands.

Skills vs slash commands
------------------------

[Section titled “Skills vs slash commands”](https://docs.letta.com/letta-code/slash-commands#skills-vs-slash-commands)

### Use slash commands for

[Section titled “Use slash commands for”](https://docs.letta.com/letta-code/slash-commands#use-slash-commands-for)

**Quick, frequently used prompts:**

*   Simple prompt snippets you use often
*   Quick reminders or templates
*   Frequently used instructions that fit in one file

**Examples:**

*   `/review` → “Review this code for bugs and suggest improvements”
*   `/explain` → “Explain this code in simple terms”
*   `/optimize` → “Analyze this code for performance issues”

### Use Skills for

[Section titled “Use Skills for”](https://docs.letta.com/letta-code/slash-commands#use-skills-for)

**Comprehensive capabilities with structure:**

*   Complex workflows with multiple steps
*   Capabilities requiring scripts or utilities
*   Knowledge organized across multiple files
*   Team workflows you want to standardize

**Examples:**

*   Code review Skill with security checklist, performance patterns, and linting scripts
*   Documentation Skill with style guides and templates
*   Deployment Skill with environment-specific configs and validation

### Key differences

[Section titled “Key differences”](https://docs.letta.com/letta-code/slash-commands#key-differences)

| Aspect | Slash Commands | Skills |
| --- | --- | --- |
| **Complexity** | Simple prompts | Complex capabilities |
| **Structure** | Single `.md` file | Directory with `SKILL.md` + resources |
| **Context** | Injected once when invoked | Pinned to context when loaded |
| **Survives compaction** | No  | Yes |
| **Discovery** | Explicit (`/command`) | Agent loads via `Skill` tool |
| **Scope** | Project or personal | Project or global |

### Example comparison

[Section titled “Example comparison”](https://docs.letta.com/letta-code/slash-commands#example-comparison)

**As a slash command:**

    Review this code for:
    - Security vulnerabilities- Performance issues- Code style violations

Usage: `/review` (one-time injection)

**As a Skill:**

    .skills/code-review/├── SKILL.md (overview and workflows)├── SECURITY.md (security checklist)├── PERFORMANCE.md (performance patterns)└── STYLE.md (style guide reference)

Usage: Agent loads the skill and has persistent access to all reference material throughout the conversation.

See also
--------

[Section titled “See also”](https://docs.letta.com/letta-code/slash-commands#see-also)

*   [Skills](https://docs.letta.com/letta-code/skills)
     - Create comprehensive capabilities with multiple files
*   [Memory](https://docs.letta.com/letta-code/memory)
     - Manage agent memory blocks
*   [CLI reference](https://docs.letta.com/letta-code/cli-reference)
     - Command-line options and flags

---

# Letta Code SDK | Letta Docs

[Skip to content](https://docs.letta.com/letta-code-sdk/quickstart/#_top)

Letta Code SDK

[Quickstart](https://docs.letta.com/letta-code-sdk/quickstart/)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

* * *

**Copy Markdown**

**View as Markdown**

Letta Code SDK
==============

Build stateful agents using Letta Code as a library

The [Letta Code SDK](https://github.com/letta-ai/letta-code-sdk/)
 provides a programmatic interface to [Letta Code](https://github.com/letta-ai/letta-code)
. Use the Letta Code SDK to build your own applications that build on Letta Code’s advanced coding agent harness.

Installation
------------

[Section titled “Installation”](https://docs.letta.com/letta-code-sdk/quickstart/#installation)

    npm install @letta-ai/letta-code-sdk

Quick start
-----------

[Section titled “Quick start”](https://docs.letta.com/letta-code-sdk/quickstart/#quick-start)

### One-shot prompt

[Section titled “One-shot prompt”](https://docs.letta.com/letta-code-sdk/quickstart/#one-shot-prompt)

For simple queries, use `prompt()`:

    import { prompt } from "@letta-ai/letta-code-sdk";
    const result = await prompt("What is 2 + 2?");console.log(result.result);

### Persistent agent with multi-turn conversations

[Section titled “Persistent agent with multi-turn conversations”](https://docs.letta.com/letta-code-sdk/quickstart/#persistent-agent-with-multi-turn-conversations)

Create an agent to persist memory across sessions and application restarts:

    import { createAgent, resumeSession } from "@letta-ai/letta-code-sdk";
    // Create agent with custom configurationconst agentId = await createAgent({  persona: "You are a Python expert specialized in data science.",});
    console.log("Agent ID:", agentId); // Save this for later!
    // Resume session on agent's default conversationawait using session = resumeSession(agentId);
    // Turn 1await session.send("What's the best way to load a CSV?");for await (const msg of session.stream()) {  if (msg.type === "assistant") console.log(msg.content);}
    // Turn 2 - agent remembers previous contextawait session.send("Show me an example with pandas");for await (const msg of session.stream()) {  if (msg.type === "assistant") console.log(msg.content);}
    // Later: Resume the same agent using the saved IDawait using laterSession = resumeSession(agentId);await laterSession.send("What were we discussing?");for await (const msg of laterSession.stream()) {  if (msg.type === "assistant") console.log(msg.content);}

The [`await using`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-2.html#using-declarations-and-explicit-resource-management)
 syntax (TypeScript 5.2+) automatically closes the session. For manual cleanup, use `session.close()`.

### Managing conversations

[Section titled “Managing conversations”](https://docs.letta.com/letta-code-sdk/quickstart/#managing-conversations)

**Start a new conversation on the same agent:**

    import { createSession } from "@letta-ai/letta-code-sdk";
    // New conversationawait using session = createSession(agentId);
    await session.send("Let's start a new topic");
    for await (const msg of session.stream()) {  if (msg.type === "assistant") console.log(msg.content);}

**Resume a specific conversation by ID:**

    import { resumeSession } from "@letta-ai/letta-code-sdk";
    // Resume a conversation you saved earlierawait using session = resumeSession("conv-abc123");
    await session.send("Continuing where we left off");
    for await (const msg of session.stream()) {  if (msg.type === "assistant") console.log(msg.content);}

Concepts
--------

[Section titled “Concepts”](https://docs.letta.com/letta-code-sdk/quickstart/#concepts)

*   **Agent** (`agentId`): A persistent entity with memory.
*   **Conversation** (`conversationId`): A message thread within an agent.
*   **Session**: A single execution/connection.
*   **Default conversation**: Always exists after `createAgent()`; use `resumeSession(agentId)`.
*   **Default agent**: Most recently used agent or the default Memo agent from Letta Code; use `createSession()` or `prompt(message)`

Configuration
-------------

[Section titled “Configuration”](https://docs.letta.com/letta-code-sdk/quickstart/#configuration)

### Agent creation options

[Section titled “Agent creation options”](https://docs.letta.com/letta-code-sdk/quickstart/#agent-creation-options)

Configure agents at creation time with memory blocks, system prompts, and initial context:

    import { createAgent } from "@letta-ai/letta-code-sdk";
    const agentId = await createAgent({  // Memory blocks define the agent's persistent context  memory: [    {      label: "persona",      value: "You are a Python expert specialized in data science.",    },    { label: "rules", value: "Always include type hints and docstrings." },  ],
      // Or use preset memory blocks  memory: ["persona", "human"], // Valid presets: persona, human
      // Convenience shortcuts for common presets  persona: "You are a helpful coding assistant.",  human: "User prefers TypeScript and functional programming.",});

**Valid memory presets:**

*   `persona` - Agent’s identity and behavior
*   `human` - Information about the user

**Custom memory blocks:**

    const agentId = await createAgent({  memory: [    {      label: "project",      value: "Building a REST API with Express and PostgreSQL...",    },    { label: "context", value: "Migrating from MongoDB to PostgreSQL..." },  ],});

### Runtime session options

[Section titled “Runtime session options”](https://docs.letta.com/letta-code-sdk/quickstart/#runtime-session-options)

Configure behavior at session creation or resume time:

    import { createAgent, resumeSession } from "@letta-ai/letta-code-sdk";
    const agentId = await createAgent();
    await using session = resumeSession(agentId, {  // Update the agent's model (persists)  model: "sonnet",
      // Working directory for file operations  cwd: "/path/to/project",
      // MemFS toggle for this run  // true -> --memfs, false -> --no-memfs, undefined -> leave unchanged  memfs: true,
      // Skills/reminder controls  skillSources: ["project", "global"], // [] disables all skills  systemInfoReminder: false, // disable first-turn system info reminder
      // Reflection settings (equivalent to /sleeptime)  sleeptime: {    trigger: "step-count", // "off" | "step-count" | "compaction-event"    behavior: "reminder", // "reminder" | "auto-launch"    stepCount: 8,  },
      // Restrict available tools  allowedTools: ["Read", "Grep", "Glob"],  disallowedTools: ["AskUserQuestion", "EnterPlanMode", "ExitPlanMode"],
      // Permission handling  permissionMode: "default", // "default" | "acceptEdits" | "plan" | "bypassPermissions"
      // Custom permission callback  canUseTool: async (toolName, toolInput) => {    if (      toolName === "Bash" &&      typeof toolInput.command === "string" &&      toolInput.command.includes("rm")    ) {      return { behavior: "deny", message: "Destructive commands not allowed" };    }    return { behavior: "allow" };  },});

### Interactive tools in non-interactive sessions

[Section titled “Interactive tools in non-interactive sessions”](https://docs.letta.com/letta-code-sdk/quickstart/#interactive-tools-in-non-interactive-sessions)

When running without a UI (for example, server-side SDK sessions):

*   `EnterPlanMode` can be auto-allowed by default.
*   `AskUserQuestion` and `ExitPlanMode` require runtime user input and are denied unless you provide a `canUseTool` callback.

For bot-style deployments, you can either:

1.  Provide `canUseTool` to handle these permission requests.
2.  Block the tools explicitly via `disallowedTools` (for example `["AskUserQuestion", "EnterPlanMode", "ExitPlanMode"]`).

### System prompts

[Section titled “System prompts”](https://docs.letta.com/letta-code-sdk/quickstart/#system-prompts)

System prompts can be configured at agent creation time, or updated later when creating/resuming a session.

**At agent creation** (`createAgent`) you can use a custom string or a preset (optionally with `append`):

    // Custom system promptconst agentId = await createAgent({  systemPrompt: "You are a Python expert. Always use type hints.",});
    // Preset (with optional append)const agentId2 = await createAgent({  systemPrompt: {    type: "preset",    preset: "letta-claude",    append: "Always respond in Spanish.",  },});

**At session time** (`createSession` / `resumeSession`) you can only set a **preset** (no custom strings / no append):

    await using session = resumeSession(agentId, {  systemPrompt: "letta-claude",});

> **Note:** Updating `model` or `systemPrompt` via `createSession` / `resumeSession` updates the agent in Letta Code (it persists), not a temporary per-session override.

**Available presets:**

*   `default` - Letta-tuned system prompt
*   `letta-claude` - Full coding assistant with memory (Claude-optimized)
*   `letta-codex` - Optimized for OpenAI Codex models
*   `letta-gemini` - Optimized for Google Gemini models
*   `claude`, `codex`, `gemini` - Minimal prompts without Letta features

### Cleanup

[Section titled “Cleanup”](https://docs.letta.com/letta-code-sdk/quickstart/#cleanup)

Sessions can be closed manually or automatically using [`await using`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-2.html#using-declarations-and-explicit-resource-management)
 (TypeScript 5.2+).

**Automatic cleanup:**

    await using session = resumeSession(agentId);// Session closes automatically when the block exits

**Manual cleanup:**

    const session = resumeSession(agentId);try {  // ... use session ...} finally {  session.close();}

API reference
-------------

[Section titled “API reference”](https://docs.letta.com/letta-code-sdk/quickstart/#api-reference)

### Core functions

[Section titled “Core functions”](https://docs.letta.com/letta-code-sdk/quickstart/#core-functions)

| Function | Description |
| --- | --- |
| `createAgent(options?)` | Create a new persistent agent |
| `createSession(agentId?, options?)` | Start a new conversation (uses default agent if no ID provided) |
| `resumeSession(id, options?)` | Resume session (pass `agent-xxx` for default conversation, or `conv-xxx` for specific conversation) |
| `prompt(message, agentId?)` | One-shot query (uses default agent if no ID provided) |

### Session interface

[Section titled “Session interface”](https://docs.letta.com/letta-code-sdk/quickstart/#session-interface)

    interface Session {  send(message: string): Promise<void>;  stream(): AsyncGenerator<SDKMessage>;  close(): void;
      readonly agentId: string;  readonly conversationId: string | null;  readonly sessionId: string;}

### CreateAgentOptions

[Section titled “CreateAgentOptions”](https://docs.letta.com/letta-code-sdk/quickstart/#createagentoptions)

Options for `createAgent()` - these configure the persistent agent:

    interface CreateAgentOptions {  model?: string;  embedding?: string;
      // Memory configuration (choose one approach)  memory?: Array<string | { label: string; value: string }>;
      // Convenience shortcuts for common presets  persona?: string;  human?: string;
      // System prompt (custom string or preset)  systemPrompt?:    | string    | SystemPromptPreset    | { type: "preset"; preset: SystemPromptPreset; append?: string };
      // Runtime/harness controls available at creation  memfs?: boolean;  skillSources?: SkillSource[];  systemInfoReminder?: boolean;  sleeptime?: SleeptimeOptions;}

### CreateSessionOptions

[Section titled “CreateSessionOptions”](https://docs.letta.com/letta-code-sdk/quickstart/#createsessionoptions)

Options for `createSession()` and `resumeSession()` - these configure runtime behavior:

    interface CreateSessionOptions {  // Model configuration  model?: string;
      // System prompt preset (updates the agent)  systemPrompt?: SystemPromptPreset;
      // Tool restrictions  allowedTools?: string[];  disallowedTools?: string[];  permissionMode?: "default" | "acceptEdits" | "plan" | "bypassPermissions";  canUseTool?: (    toolName: string,    toolInput: object,  ) => Promise<CanUseToolResponse>;
      // File system  cwd?: string;
      // Runtime/harness controls  memfs?: boolean; // true => --memfs, false => --no-memfs  skillSources?: SkillSource[]; // [] => --no-skills  systemInfoReminder?: boolean; // false => --no-system-info-reminder  sleeptime?: SleeptimeOptions;}

Supporting types:

    type SkillSource = "bundled" | "global" | "agent" | "project";
    interface SleeptimeOptions {  trigger?: "off" | "step-count" | "compaction-event";  behavior?: "reminder" | "auto-launch";  stepCount?: number;}

Example apps
------------

[Section titled “Example apps”](https://docs.letta.com/letta-code-sdk/quickstart/#example-apps)

Just directly into code examples with demo app built on the Letta Code SDK:

[Channels](https://docs.letta.com/letta-code/channels)
 Connect your agent to Telegram and Slack for messaging from anywhere.

[Letta OSS UI](https://github.com/letta-ai/letta-oss-ui)
 Like Claude Cowork, but fully open source and using stateful agents.

---

# Ralph mode (aka forced continuation) | Letta Docs

[Skip to content](https://docs.letta.com/letta-code/ralph-mode#_top)

Reference

[Auto-looping](https://docs.letta.com/letta-code/ralph-mode)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

* * *

**Copy Markdown**

**View as Markdown**

Ralph mode (aka forced continuation)
====================================

Force your agent to continue working until a task is complete

Sometimes you want your agent to keep working until the job is completely done, without having to manually remind it to “keep going”, or prod it to reflect with “are you sure it’s completely finished?”. The `/ralph` command starts an iterative loop that continually prompts the agent to continue working until it outputs an explicit “promise” that the task at hand has been completed.

This iterative looping + promise checking method is also called the [Ralph Wiggum technique](https://ghuntley.com/ralph/)
 (aka “Ralph loop”), and it implemented natively inside of Letta Code as “Ralph mode”. The name comes from Ralph Wiggum’s persistence in The Simpsons.

How it works
------------

[Section titled “How it works”](https://docs.letta.com/letta-code/ralph-mode#how-it-works)

When you run `/ralph`, Letta Code overrides the normal end-of-turn behavior. Instead of returning control to you (the user) after an agent yields execution (for example, when the agent stops to say “I’ve finished”), Letta Code will automatically re-prompt the agent to continue working.

The loop continues until one of these happens:

1.  The agent outputs a **completion promise** (a specific phrase wrapped in `<promise>` XML tags)
2.  The **maximum iterations** limit is reached
3.  You manually exit Ralph mode using **Shift+Tab** (in the CLI)

Starting a loop
---------------

[Section titled “Starting a loop”](https://docs.letta.com/letta-code/ralph-mode#starting-a-loop)

    /ralph "Build a REST API for todos with full test coverage"

The agent will work on your task, and when it finishes a turn, Letta Code automatically continues with the same prompt. You’ll see iteration counts in the status bar.

You can also start the command first, then type your task:

    /ralph
    > Build a REST API for todos with full test coverage

### Options

[Section titled “Options”](https://docs.letta.com/letta-code/ralph-mode#options)

    /ralph "Fix the failing tests" --max-iterations 100

    /ralph "Implement auth" --completion-promise "AUTH COMPLETE"

    /ralph "Keep improving the code" --completion-promise ""

The completion promise
----------------------

[Section titled “The completion promise”](https://docs.letta.com/letta-code/ralph-mode#the-completion-promise)

By default, the agent must output this exact text to stop the loop:

    <promise>The task is complete. All requirements have been implementedand verified working. Any tests that were relevant have been run andare passing. The implementation is clean and production-ready. I havenot taken any shortcuts or faked anything to meet these requirements.</promise>

The phrasing is intentionally strong. The agent is instructed not to output the promise unless the statement is genuinely true — no lying to escape the loop. This encourages thorough completion rather than premature exits.

You can customize the promise text with `--completion-promise`, but keep it meaningful. Vague phrases like “DONE” make it too easy for the agent to exit prematurely.

Combining with yolo mode
------------------------

[Section titled “Combining with yolo mode”](https://docs.letta.com/letta-code/ralph-mode#combining-with-yolo-mode)

Combine autonomous loops with Letta Code’s built-in “yolo” (permission bypass) mode:

    /yolo-ralph "Refactor the auth module and update all tests"

This runs the loop with `bypassPermissions` enabled, so the agent won’t pause for most tool approvals. `ExitPlanMode` still requires manual approval. The status bar shows orange instead of yellow to indicate the elevated permissions.

Yolo mode pairs well with Ralph mode when you want long autonomous runs with minimal intervention, while still keeping explicit approval for `ExitPlanMode`.

Interrupting and resuming
-------------------------

[Section titled “Interrupting and resuming”](https://docs.letta.com/letta-code/ralph-mode#interrupting-and-resuming)

Similar to regular interactive mode in Letta Code, you can press **ESC** during streaming to interrupt the current turn. You can type additional instructions to provide feedback, and when you send them, the Ralph loop continues with your input prepended to the original prompt.

Press **Shift+Tab** to fully exit the loop and return to normal interactive mode.

Writing good prompts
--------------------

[Section titled “Writing good prompts”](https://docs.letta.com/letta-code/ralph-mode#writing-good-prompts)

Ralph mode works best with clear, verifiable completion criteria.

**Works well:**

    Build a REST API for todos. Requirements:- CRUD endpoints for todo items- Input validation on all endpoints- Unit tests with >80% coverage- README with API documentation

The agent can verify each requirement before claiming completion.

**Works poorly:**

    Make the code better.

Without concrete criteria, the agent might loop indefinitely or exit too early.

When to use Ralph mode
----------------------

[Section titled “When to use Ralph mode”](https://docs.letta.com/letta-code/ralph-mode#when-to-use-ralph-mode)

Ralph mode shines for well-defined tasks with automatic verification:

*   Getting a test suite to pass
*   Implementing features with clear acceptance criteria
*   Refactoring with existing test coverage
*   Generating boilerplate that follows patterns

Ralph mode is less suited for tasks that benefit from a human in-the-loop:

*   Tasks requiring human judgment or design decisions
*   Exploratory work without clear goals
*   One-shot operations that don’t benefit from long-horizon iteration

---

# CLI reference | Letta Docs

[Skip to content](https://docs.letta.com/letta-code/cli-reference#_top)

Reference

[CLI reference](https://docs.letta.com/letta-code/cli-reference)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

* * *

**Copy Markdown**

**View as Markdown**

CLI reference
=============

Command-line options and flags for Letta Code

Essential commands
------------------

[Section titled “Essential commands”](https://docs.letta.com/letta-code/cli-reference#essential-commands)

You’ll likely want to use the following essential commands when using Letta Code:

| Command | What it does | Example |
| --- | --- | --- |
| `letta` | Start interactive mode | `letta` |
| `letta -p "query"` | Run a query in headless mode | `letta -p "commit the changes and push"` |
| `shift-tab` | Toggle between modes (allow edits, plan, yolo) | Press `Shift+Tab` |
| `/init` | Run deep memory initialization (or re-init) | `> /init` |
| `/doctor` | Audit and refine memory structure | `> /doctor` |
| `/remember` | Teach your agent something | `> /remember always use pnpm` |
| `/memory` | View and manage memory blocks | `> /memory` |
| `/model` | Switch the LLM model | `> /model` |
| `/search` | Search past messages | `> /search auth bug` |
| `/clear` | Clear context window (messages buffer) | `> /clear` |
| `/new` | Start a new conversation | `> /new` |
| `/pin` | Pin agent for easy access | `> /pin` |
| `/agents` | Swap between agents | `> /agents` |
| `/feedback` | Report issues or give feedback | `> /feedback` |
| `!` | Enter bash mode to run a bash command directly | `! git status` |
| `exit` or `Ctrl+C` | Exit Letta Code | `> exit` |

Basic usage
-----------

[Section titled “Basic usage”](https://docs.letta.com/letta-code/cli-reference#basic-usage)

    letta [options] [-p "prompt"]

| Flag | Description |
| --- | --- |
| `letta` | Resume the default conversation with last-used agent |
| `letta --new` | Start a new conversation (for concurrent sessions) |
| `letta --resume`, `-r` | Open conversation selector to browse and resume past sessions |
| `letta --conversation <id>`, `--conv` | Resume a specific conversation by ID |
| `letta --default` | Use agent’s default conversation (requires `--agent` or `--name`) |
| `letta -n "Name" --default` | Use default conversation of agent by name |
| `letta --conv default --agent <id>` | Same as above (explicit form) |
| `letta --conv <agent-id>` | Shorthand: use default conversation of specified agent |
| `letta --new-agent` | Force create a new agent |
| `letta --import <path>` | Create new agent from an [AgentFile](https://docs.letta.com/guides/core-concepts/agent-file)<br> (.af) or registry (`@author/name`) |
| `letta --agent <id>`, `-a` | Use a specific agent by ID |
| `letta --name <name>`, `-n` | Resume agent by name (matches pinned or recent agents) |
| `letta --info` | Show project info, skills directory, and pinned agents (without starting session) |
| `letta --help` | Show help |
| `letta --version` | Show version |

Model and configuration
-----------------------

[Section titled “Model and configuration”](https://docs.letta.com/letta-code/cli-reference#model-and-configuration)

| Flag | Description |
| --- | --- |
| `--model <model>`, `-m` | Specify model (e.g., `sonnet`, `auto`, `gpt-5-codex`) |
| `--embedding <model>` | Specify embedding model for new agents |
| `--system <preset>` | Use a system prompt preset (e.g., `letta-claude`, `codex`) |
| `--system-custom <text>` | Use a custom system prompt string (for new agents) |
| `--toolset <name>` | Force toolset: `default`, `codex`, or `gemini` |
| `--skills <path>` | Custom skills directory |
| `--skill-sources <csv>` | Skill sources: `all,bundled,global,agent,project` |
| `--no-skills` | Disable all skill sources |
| `--no-bundled-skills` | Disable bundled skills only |
| `--no-system-info-reminder` | Disable first-turn environment reminder (device/git/cwd context) |
| `--reflection-trigger <mode>` | Sleeptime trigger: `off`, `step-count`, `compaction-event` |
| `--reflection-behavior <mode>` | Deprecated - accepted for compatibility but ignored |
| `--reflection-step-count <n>` | Sleeptime step-count interval (positive integer) |

To resume your usual working thread, just run `letta`. For parallel work, use `--new`. To reopen a specific thread, use `--conversation <id>` or `--resume` in interactive mode.

Headless mode
-------------

[Section titled “Headless mode”](https://docs.letta.com/letta-code/cli-reference#headless-mode)

Run Letta Code non-interactively for automation and CI/CD. See [Headless mode](https://docs.letta.com/letta-code/headless)
 for detailed usage.

| Flag | Description |
| --- | --- |
| `-p "prompt"` | Run a one-off prompt (headless mode) |
| `--output-format <fmt>` | Output format: `text`, `json`, or `stream-json` |
| `--input-format <fmt>` | Input format: `stream-json` for bidirectional mode |
| `--include-partial-messages` | Emit `stream_event` wrappers for each chunk (`stream-json` only) |
| `--yolo` | Bypass most permission prompts (`ExitPlanMode` still requires approval) |
| `--permission-mode <mode>` | Set permission mode |
| `--tools "Tool1,Tool2"` | Limit available tools |
| `--allowedTools "..."` | Allow specific tool patterns |
| `--disallowedTools "..."` | Block specific tool patterns |
| `--from-agent <id>` | Inject agent-to-agent system reminder (headless mode) |
| `--tags <csv>` | Comma-separated tags for agent organization (headless mode) |

Memory configuration
--------------------

[Section titled “Memory configuration”](https://docs.letta.com/letta-code/cli-reference#memory-configuration)

Configure memory blocks when creating new agents.

| Flag | Description |
| --- | --- |
| `--init-blocks <names>` | Comma-separated preset block names (e.g., `"persona,project"`) |
| `--base-tools <names>` | Comma-separated base tools to attach when using `--new-agent` |
| `--memory-blocks <json>` | JSON array of custom memory blocks |
| `--block-value <label>=<value>` | Set value for a preset block (can be specified multiple times) |
| `--memfs` | Enable Memory Filesystem for this agent |
| `--no-memfs` | Disable Memory Filesystem for this agent |

Maintenance
-----------

[Section titled “Maintenance”](https://docs.letta.com/letta-code/cli-reference#maintenance)

| Flag | Description |
| --- | --- |
| `letta update` | Manually check and install updates |
| `letta server [options]` | Register this environment as a cloud listener |
| `letta remote [options]` | Alias for `letta server` |
| `letta connect <provider> [options]` | Connect provider auth from CLI (same provider flow as `/connect`) |

Scheduling
----------

[Section titled “Scheduling”](https://docs.letta.com/letta-code/cli-reference#scheduling)

Use `letta cron` to register one-time or recurring prompts for an agent. Tasks are stored locally and fire while `letta server` is connected. See [Scheduling](https://docs.letta.com/letta-code/scheduling)
 for the full guide.

This is a server-mode feature, not a replacement for shell cron or the Letta API schedules feature.

| Command | Description |
| --- | --- |
| `letta cron add --name <name> --description <text> --prompt <text> --every <interval> [options]` | Create a recurring task from an interval like `5m`, `2h`, or `1d` |
| `letta cron add --name <name> --description <text> --prompt <text> --at <time> [options]` | Create a one-time task for a time like `"3:00pm"` or `"in 45m"` |
| `letta cron add --name <name> --description <text> --prompt <text> --cron "<expr>" [options]` | Create a recurring task from a raw 5-field cron expression |
| `letta cron list [--agent <id>] [--conversation <id>]` | List tasks, optionally filtered by agent or conversation |
| `letta cron get <id>` | Show task details |
| `letta cron delete <id>` | Delete one task |
| `letta cron delete --all --agent <id>` | Delete all tasks for an agent |

`--agent` defaults to `LETTA_AGENT_ID` when available. `--conversation` defaults to `LETTA_CONVERSATION_ID` or `default`.

Recurring tasks currently expire after 3 days. `--every 1d` fires daily at local midnight, so use `--cron` for a fixed time of day.

Subcommands (JSON-only)
-----------------------

[Section titled “Subcommands (JSON-only)”](https://docs.letta.com/letta-code/cli-reference#subcommands-json-only)

These commands print JSON and are intended for scripting and automation.

| Command | Description |
| --- | --- |
| `letta memfs status --agent <id>` | Show memfs status for an agent |
| `letta memfs diff --agent <id>` | Show memfs conflicts and metadata-only changes |
| `letta memfs resolve --agent <id> --resolutions '<JSON>'` | Resolve memfs conflicts |
| `letta memfs backup --agent <id>` | Backup memfs to a timestamped directory |
| `letta memfs backups --agent <id>` | List memfs backups |
| `letta memfs restore --agent <id> --from <backup> --force` | Restore memfs from a backup (destructive) |
| `letta memfs export --agent <id> --out <dir>` | Export an agent’s memfs to a directory |
| `letta agents create [options]` | Create a memfs-enabled agent |
| `letta agents list [options]` | List/search agents |
| `letta messages search --query <text> [options]` | Search messages (optionally across all agents) |
| `letta messages list [options]` | List messages for an agent |
| `letta blocks list --agent <id>` | List blocks for an agent |
| `letta blocks copy --block-id <id> [options]` | Copy a block to the current agent |
| `letta blocks attach --block-id <id> [options]` | Attach a block to the current agent |

See `/letta-code/memory` for memfs details and `/letta-code/skills` for how skills use these commands.

Note: For user → agent headless prompts, use `letta -p`. For agent → agent headless prompts, use `letta -p --from-agent <id>`.

Environment variables
---------------------

[Section titled “Environment variables”](https://docs.letta.com/letta-code/cli-reference#environment-variables)

| Variable | Description |
| --- | --- |
| `LETTA_API_KEY` | API key for authentication (get yours at [app.letta.com/api-keys](https://app.letta.com/api-keys)<br>) |
| `LETTA_BASE_URL` | Base URL for self-hosted Letta server (e.g., `http://localhost:8283`) |
| `LETTA_DEBUG` | Set to `1` to enable debug logging |
| `LETTA_CODE_TELEM` | Set to `0` to disable anonymous telemetry |
| `LETTA_PACKAGE_MANAGER` | Override detected package manager for auto-updates (`npm`, `bun`, or `pnpm`) |
| `DISABLE_AUTOUPDATER` | Set to `1` to disable auto-updates |
| `MEMORY_DIR` | Absolute path to the agent’s memory directory (set automatically in shell tools) |
| `AGENT_ID` | Current agent ID (set automatically in shell tools) |
| `CONVERSATION_ID` | Current conversation ID (set automatically in shell tools) |

Set these in your shell profile (`~/.bashrc`, `~/.zshrc`) or `.env` file:

    export LETTA_API_KEY="your-key-here"export LETTA_BASE_URL="http://localhost:8283"

Keyboard shortcuts
------------------

[Section titled “Keyboard shortcuts”](https://docs.letta.com/letta-code/cli-reference#keyboard-shortcuts)

These shortcuts work during interactive sessions.

| Shortcut | Description |
| --- | --- |
| `/` | Open command autocomplete |
| `@` | Open file autocomplete |
| `!` | Enter bash mode (run shell commands directly) |
| `Tab` | Autocomplete command or file path |
| `Shift+Enter` | Insert newline (multi-line input) |
| `↑` / `↓` | Navigate history or menu items |
| `Esc` | Cancel dialog or clear input (double press) |
| `Ctrl+C` | Interrupt operation or exit (double press) |
| `Ctrl+V` | Paste content or image |

Bash mode lets you run shell commands directly without involving the agent. Press `!` on an empty input line to enter bash mode (prompt changes to `!`), type your command, and press Enter. Press Backspace on an empty line to exit bash mode.

---

# Configuration | Letta Docs

[Skip to content](https://docs.letta.com/letta-code/configuration#_top)

Reference

[Configuration](https://docs.letta.com/letta-code/configuration)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

* * *

**Copy Markdown**

**View as Markdown**

Configuration
=============

Configure Letta Code settings and preferences

Letta Code uses a hierarchical configuration system with global and project-level settings.

Authentication
--------------

[Section titled “Authentication”](https://docs.letta.com/letta-code/configuration#authentication)

### Letta API (default)

[Section titled “Letta API (default)”](https://docs.letta.com/letta-code/configuration#letta-api-default)

On first run, Letta Code prompts you to authenticate via OAuth:

1.  Run `letta`
2.  Follow the browser prompt to log in at `app.letta.com`

### API key

[Section titled “API key”](https://docs.letta.com/letta-code/configuration#api-key)

Alternatively, set an API key directly:

    export LETTA_API_KEY=your-api-key

### Docker

[Section titled “Docker”](https://docs.letta.com/letta-code/configuration#docker)

See [Docker setup](https://docs.letta.com/letta-code/docker)
 to use Letta Code with a Letta server running in Docker.

Configuration files
-------------------

[Section titled “Configuration files”](https://docs.letta.com/letta-code/configuration#configuration-files)

### Global settings (`~/.letta/settings.json`)

[Section titled “Global settings (~/.letta/settings.json)”](https://docs.letta.com/letta-code/configuration#global-settings-lettasettingsjson)

Applies to all projects:

    {  "tokenStreaming": true,  "globalSharedBlockIds": {    "persona": "block-id-...",    "human": "block-id-..."  }}

### Project settings (`.letta/settings.local.json`)

[Section titled “Project settings (.letta/settings.local.json)”](https://docs.letta.com/letta-code/configuration#project-settings-lettasettingslocaljson)

Personal, gitignored - your agent for this project:

    {  "lastAgent": "agent-id-..."}

### Shared project settings (`.letta/settings.json`)

[Section titled “Shared project settings (.letta/settings.json)”](https://docs.letta.com/letta-code/configuration#shared-project-settings-lettasettingsjson)

Can be committed to share with your team:

    {  "permissions": {    "allow": ["Bash(pnpm lint)", "Bash(pnpm test)"]  }}

### File search tuning (`~/.letta/.lettasettings`)

[Section titled “File search tuning (~/.letta/.lettasettings)”](https://docs.letta.com/letta-code/configuration#file-search-tuning-lettalettasettings)

Letta Code also creates a user-local `~/.letta/.lettasettings` file for tuning indexed `@` file search behavior:

    MAX_ENTRIES=50000

*   `MAX_ENTRIES` controls how many files are kept in the in-memory `@` search cache.
*   Raise it for very large repositories if you want more files instantly available in autocomplete.
*   Lower it on constrained machines to reduce memory usage.
*   Restart Letta Code after changing this file.

### File search exclusions (`.letta/.lettaignore`)

[Section titled “File search exclusions (.letta/.lettaignore)”](https://docs.letta.com/letta-code/configuration#file-search-exclusions-lettalettaignore)

Use `.letta/.lettaignore` to exclude files and directories from indexed `@` file search and disk-scan fallback:

    node_modulesdistcoverage*.logsrc/generated/**

*   One glob pattern per line
*   `#` starts a comment
*   Negation patterns like `!foo` are not currently supported
*   Letta Code creates this file automatically with common defaults on first run

You can commit `.letta/.lettaignore` if you want your team to share the same search exclusions.

Settings reference
------------------

[Section titled “Settings reference”](https://docs.letta.com/letta-code/configuration#settings-reference)

| Setting | Type | Description |
| --- | --- | --- |
| `tokenStreaming` | `boolean` | Enable real-time token streaming |
| `showCompactions` | `boolean` | Show compaction event messages in the conversation (default: `false`) |
| `enableSleeptime` | `boolean` | Enable sleeptime agents for passive memory updates (default: `false`) |
| `lastAgent` | `string` | ID of last used agent (for auto-resume) |
| `globalSharedBlockIds` | `object` | IDs of global memory blocks |
| `permissions.allow` | `string[]` | Patterns to auto-allow |
| `permissions.deny` | `string[]` | Patterns to always deny |

Environment variables
---------------------

[Section titled “Environment variables”](https://docs.letta.com/letta-code/configuration#environment-variables)

| Variable | Description |
| --- | --- |
| `LETTA_API_KEY` | API key for authentication (alternative to OAuth) |
| `LETTA_BACKFILL` | Load message history on agent resume. Set to `0` or `false` to start with clean chat. Default: `true` |
| `LETTA_ENABLE_LSP` | Enable LSP diagnostics for type error detection. Set to `1` to enable |
| `LETTA_PACKAGE_MANAGER` | Override detected package manager for auto-updates (`npm`, `bun`, or `pnpm`) |
| `DISABLE_AUTOUPDATER` | Disable automatic updates. Set to `1` to disable |

LSP Diagnostics
---------------

[Section titled “LSP Diagnostics”](https://docs.letta.com/letta-code/configuration#lsp-diagnostics)

Letta Code can integrate with Language Server Protocol (LSP) servers to provide automatic type error detection when reading files.

### Enable LSP

[Section titled “Enable LSP”](https://docs.letta.com/letta-code/configuration#enable-lsp)

    export LETTA_ENABLE_LSP=1

### Supported languages

[Section titled “Supported languages”](https://docs.letta.com/letta-code/configuration#supported-languages)

| Language | Extensions | LSP Server |
| --- | --- | --- |
| TypeScript/JavaScript | `.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`, `.cjs` | `typescript-language-server` |
| Python | `.py`, `.pyi` | `pyright` |

### How it works

[Section titled “How it works”](https://docs.letta.com/letta-code/configuration#how-it-works)

When LSP is enabled and you read a supported file:

1.  Letta Code starts the appropriate LSP server (auto-installed if missing)
2.  The file is analyzed for type errors, syntax errors, and other diagnostics
3.  Any errors are appended to the file content in a `<file_diagnostics>` block

    This file has errors, please fix<file_diagnostics>ERROR [10:5] Cannot find name 'foo'ERROR [15:3] Type 'string' is not assignable to type 'number'</file_diagnostics>

### Behavior

[Section titled “Behavior”](https://docs.letta.com/letta-code/configuration#behavior)

*   **Auto-included** for files under 500 lines
*   **Manual control** via `include_types` parameter on the Read tool:
    *   `include_types: true` - Force include diagnostics (even for large files)
    *   `include_types: false` - Skip diagnostics (even for small files)

This helps the agent catch type errors before making edits, reducing iteration cycles.

Updates
-------

[Section titled “Updates”](https://docs.letta.com/letta-code/configuration#updates)

Letta Code automatically keeps itself up to date to ensure you have the latest features and fixes.

*   **Update checks**: Performed on startup and periodically while running
*   **Update process**: Downloads and installs automatically in the background
*   **Applying updates**: Updates take effect the next time you start Letta Code

### Disable auto-updates

[Section titled “Disable auto-updates”](https://docs.letta.com/letta-code/configuration#disable-auto-updates)

    export DISABLE_AUTOUPDATER=1

### Manual update

[Section titled “Manual update”](https://docs.letta.com/letta-code/configuration#manual-update)

    letta update

Recommended .gitignore
----------------------

[Section titled “Recommended .gitignore”](https://docs.letta.com/letta-code/configuration#recommended-gitignore)

    # Letta Code personal settings.letta/settings.local.json

Keep `.letta/settings.json` tracked to share project context with your team. You can also track `.letta/.lettaignore` if you want shared file-search exclusions.

---

# Docker | Letta Docs

[Skip to content](https://docs.letta.com/letta-code/docker#_top)

Reference

[Docker](https://docs.letta.com/letta-code/docker)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

* * *

**Copy Markdown**

**View as Markdown**

Docker
======

Use Letta Code with a Letta server running in Docker

Letta Code can connect to a Letta server running in Docker by setting `LETTA_BASE_URL`.

Prerequisites
-------------

[Section titled “Prerequisites”](https://docs.letta.com/letta-code/docker#prerequisites)

Before connecting Letta Code, you need to have a Letta server running in Docker. See the [Docker setup guide](https://docs.letta.com/guides/docker)
 for detailed instructions.

This example command configures a Letta server with an OpenAI API key, an Anthropic API key (for Claude models), and an Ollama URL (assumes that Ollama is running on `localhost:11434`):

    docker run \  -v ~/.letta/.persist/pgdata:/var/lib/postgresql/data \  -p 8283:8283 \  -e OPENAI_API_KEY="your_openai_api_key" \  -e ANTHROPIC_API_KEY="your_anthropic_api_key" \  -e OLLAMA_BASE_URL="http://host.docker.internal:11434/v1" \  letta/letta:latest

Connecting Letta Code
---------------------

[Section titled “Connecting Letta Code”](https://docs.letta.com/letta-code/docker#connecting-letta-code)

Set the `LETTA_BASE_URL` environment variable to point to your server:

    export LETTA_BASE_URL="http://localhost:8283"

Then run Letta Code normally:

    letta

You can also set it inline:

    LETTA_BASE_URL="http://localhost:8283" letta

Models available on the Letta server running in Docker will be shown in `/model`.

---

# Changelog | Letta Docs

[Skip to content](https://docs.letta.com/letta-code/changelog#_top)

Reference

[Changelog](https://docs.letta.com/letta-code/changelog)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

* * *

**Copy Markdown**

**View as Markdown**

Changelog
=========

Release notes and version history for Letta Code

All notable changes to Letta Code are documented here.

0.22.4
------

[Section titled “0.22.4”](https://docs.letta.com/letta-code/changelog#0224)

*   Fixed repeated Linux keychain read warnings during auth setup ([#1663](https://github.com/letta-ai/letta-code/pull/1663)
    )
*   Fixed CLI subcommands so they dispatch before the TUI initializes, and fixed `letta listen` startup ordering so settings load before telemetry ([#1725](https://github.com/letta-ai/letta-code/pull/1725)
    , [#1752](https://github.com/letta-ai/letta-code/pull/1752)
    )
*   Added outbound Telegram markdown formatting and hardened Telegram reminder delivery in channels mode ([#1754](https://github.com/letta-ai/letta-code/pull/1754)
    , [#1756](https://github.com/letta-ai/letta-code/pull/1756)
    , [#1757](https://github.com/letta-ai/letta-code/pull/1757)
    )

0.22.3
------

[Section titled “0.22.3”](https://docs.letta.com/letta-code/changelog#0223)

*   Added OAuth device flow for headless server deployments ([#1731](https://github.com/letta-ai/letta-code/pull/1731)
    )
*   Fixed memory git commits to unstage paths after commit-hook failures ([#1734](https://github.com/letta-ai/letta-code/pull/1734)
    )
*   Fixed bundled CLI packaging to externalize grammY correctly ([#1749](https://github.com/letta-ai/letta-code/pull/1749)
    )

0.22.2
------

[Section titled “0.22.2”](https://docs.letta.com/letta-code/changelog#0222)

*   Fixed the pre-commit frontmatter validator to ignore YAML continuation lines ([#1743](https://github.com/letta-ai/letta-code/pull/1743)
    )
*   Improved inbound channel reply prompting and OAuth setup network error messages ([#1746](https://github.com/letta-ai/letta-code/pull/1746)
    , [#1747](https://github.com/letta-ai/letta-code/pull/1747)
    )

0.22.1
------

[Section titled “0.22.1”](https://docs.letta.com/letta-code/changelog#0221)

*   Added live websocket channel management for channels mode ([#1744](https://github.com/letta-ai/letta-code/pull/1744)
    )

0.22.0
------

[Section titled “0.22.0”](https://docs.letta.com/letta-code/changelog#0220)

*   Added the channels system with a Telegram MVP in listener/WebSocket mode ([#1737](https://github.com/letta-ai/letta-code/pull/1737)
    )
*   Stopped sending self-hosted errors to telemetry ([#1730](https://github.com/letta-ai/letta-code/pull/1730)
    )
*   Fixed `ExitPlanMode` to restore the correct default permission mode and aligned listener task notification queue semantics ([#1738](https://github.com/letta-ai/letta-code/pull/1738)
    , [#1739](https://github.com/letta-ai/letta-code/pull/1739)
    )

0.21.18
-------

[Section titled “0.21.18”](https://docs.letta.com/letta-code/changelog#02118)

*   Added the `scheduling-tasks` built-in skill for cron-style reminders and automations ([#1714](https://github.com/letta-ai/letta-code/pull/1714)
    )
*   Added the `/btw` command for forked conversation side-queries and device-side file watching with `watch_file` / `unwatch_file` ([#1596](https://github.com/letta-ai/letta-code/pull/1596)
    , [#1718](https://github.com/letta-ai/letta-code/pull/1718)
    )
*   Added web history search filters and content-search mode in the history tab ([#1681](https://github.com/letta-ai/letta-code/pull/1681)
    , [#1683](https://github.com/letta-ai/letta-code/pull/1683)
    )
*   Added Opus 1M LC support and improved 1M context window handling ([#1701](https://github.com/letta-ai/letta-code/pull/1701)
    , [#1720](https://github.com/letta-ai/letta-code/pull/1720)
    )
*   Fixed memory sync, permissions, and tool behavior across runtimes, including Windows git credential helpers, memory tool schema alignment, `apply_patch` semantics, and shell truncation behavior ([#1700](https://github.com/letta-ai/letta-code/pull/1700)
    , [#1702](https://github.com/letta-ai/letta-code/pull/1702)
    , [#1704](https://github.com/letta-ai/letta-code/pull/1704)
    , [#1709](https://github.com/letta-ai/letta-code/pull/1709)
    , [#1710](https://github.com/letta-ai/letta-code/pull/1710)
    , [#1711](https://github.com/letta-ai/letta-code/pull/1711)
    , [#1721](https://github.com/letta-ai/letta-code/pull/1721)
    )

0.21.17
-------

[Section titled “0.21.17”](https://docs.letta.com/letta-code/changelog#02117)

*   Added per-personality default models and set the `kawaii` personality to prefer `auto-chat` ([#1687](https://github.com/letta-ai/letta-code/pull/1687)
    )
*   Added the `glm-5.1` model preset ([#1694](https://github.com/letta-ai/letta-code/pull/1694)
    )
*   Enforced git worktree creation under `.letta/worktrees/` ([#1693](https://github.com/letta-ai/letta-code/pull/1693)
    )
*   Fixed first-connection bootstrap of base tools, desktop file indexer visibility, and memory-tool auto-approval behavior in `acceptEdits` mode ([#1684](https://github.com/letta-ai/letta-code/pull/1684)
    , [#1689](https://github.com/letta-ai/letta-code/pull/1689)
    , [#1690](https://github.com/letta-ai/letta-code/pull/1690)
    )
*   Improved memfs push reliability, model-setting context-window updates, and websocket listener hot-path performance ([#1688](https://github.com/letta-ai/letta-code/pull/1688)
    , [#1660](https://github.com/letta-ai/letta-code/pull/1660)
    , [#1695](https://github.com/letta-ai/letta-code/pull/1695)
    )

0.21.16
-------

[Section titled “0.21.16”](https://docs.letta.com/letta-code/changelog#02116)

*   Added `memory_history` and `memory_file_at_ref` device commands for memory inspection ([#1637](https://github.com/letta-ai/letta-code/pull/1637)
    )
*   Fixed memfs clone/pull to retry on transient 52x git errors ([#1675](https://github.com/letta-ai/letta-code/pull/1675)
    )
*   Disabled auto-init for newly created agents ([#1679](https://github.com/letta-ai/letta-code/pull/1679)
    )

0.21.15
-------

[Section titled “0.21.15”](https://docs.letta.com/letta-code/changelog#02115)

*   Improved insufficient-credits error copy for CLI flows ([#1672](https://github.com/letta-ai/letta-code/pull/1672)
    )
*   Retried formatted Cloudflare `521` errors during recovery ([#1674](https://github.com/letta-ai/letta-code/pull/1674)
    )

0.21.14
-------

[Section titled “0.21.14”](https://docs.letta.com/letta-code/changelog#02114)

*   Stopped sync recovery failures from spamming the transcript in listener mode ([#1669](https://github.com/letta-ai/letta-code/pull/1669)
    )
*   Fixed websocket stream retries to relay abort signals correctly ([#1668](https://github.com/letta-ai/letta-code/pull/1668)
    )

0.21.13
-------

[Section titled “0.21.13”](https://docs.letta.com/letta-code/changelog#02113)

*   Fixed memfs skill lookup in the `Skill` tool ([#1649](https://github.com/letta-ai/letta-code/pull/1649)
    )
*   Fixed memory-directory git commits to use the agent git identity ([#1640](https://github.com/letta-ai/letta-code/pull/1640)
    )
*   Refreshed listener loop status when the active plan file path changes ([#1666](https://github.com/letta-ai/letta-code/pull/1666)
    )

0.21.12
-------

[Section titled “0.21.12”](https://docs.letta.com/letta-code/changelog#02112)

*   Added plan file path tracking in listener loop state ([#1662](https://github.com/letta-ai/letta-code/pull/1662)
    )
*   Scoped memory subagents to memory roots for safer permissions ([#1656](https://github.com/letta-ai/letta-code/pull/1656)
    )
*   Updated the `working-in-parallel` skill with pre-commit hook guidance ([#1655](https://github.com/letta-ai/letta-code/pull/1655)
    )

0.21.11
-------

[Section titled “0.21.11”](https://docs.letta.com/letta-code/changelog#02111)

*   Preserved websocket loop error details in listener mode ([#1650](https://github.com/letta-ai/letta-code/pull/1650)
    )
*   Fixed hidden approvals to unwind correctly after interrupts ([#1657](https://github.com/letta-ai/letta-code/pull/1657)
    )

0.21.10
-------

[Section titled “0.21.10”](https://docs.letta.com/letta-code/changelog#02110)

*   Fixed listener approval request projection to be atomic ([#1644](https://github.com/letta-ai/letta-code/pull/1644)
    )
*   Fixed listener transcripts to suppress stale approval recovery notices and show full `update_subagents` status updates ([#1641](https://github.com/letta-ai/letta-code/pull/1641)
    , [#1643](https://github.com/letta-ai/letta-code/pull/1643)
    )
*   Added `[[path]]` indexing guidance to the system prompt and memory tool docs ([#1642](https://github.com/letta-ai/letta-code/pull/1642)
    )

0.21.9
------

[Section titled “0.21.9”](https://docs.letta.com/letta-code/changelog#0219)

*   Added websocket approval suggestion support in listener mode ([#1629](https://github.com/letta-ai/letta-code/pull/1629)
    )

0.21.8
------

[Section titled “0.21.8”](https://docs.letta.com/letta-code/changelog#0218)

*   Improved file indexing correctness, Merkle propagation, and freshness ([#1615](https://github.com/letta-ai/letta-code/pull/1615)
    )
*   Fixed `/fork` for default conversations to pass `agent_id`, and kept auto models on the default toolset ([#1617](https://github.com/letta-ai/letta-code/pull/1617)
    , [#1618](https://github.com/letta-ai/letta-code/pull/1618)
    )
*   Fixed self-hosted model fallback for new agents and improved secret prompting ([#1619](https://github.com/letta-ai/letta-code/pull/1619)
    , [#1623](https://github.com/letta-ai/letta-code/pull/1623)
    )
*   Fixed approval recovery so restored approvals continue through the live pipeline without max-turn exits ([#1622](https://github.com/letta-ai/letta-code/pull/1622)
    , [#1625](https://github.com/letta-ai/letta-code/pull/1625)
    )
*   Fixed websocket listener retention leaks, agent info reminder metadata, and miscellaneous permissions issues ([#1624](https://github.com/letta-ai/letta-code/pull/1624)
    , [#1627](https://github.com/letta-ai/letta-code/pull/1627)
    , [#1628](https://github.com/letta-ai/letta-code/pull/1628)
    )

0.21.7
------

[Section titled “0.21.7”](https://docs.letta.com/letta-code/changelog#0217)

*   Added the `/empanada` slash command for Empanada Empire ordering ([#1612](https://github.com/letta-ai/letta-code/pull/1612)
    )

0.21.6
------

[Section titled “0.21.6”](https://docs.letta.com/letta-code/changelog#0216)

*   Changed `/init` to use the new context constitution workflow for deeper memory initialization ([#1608](https://github.com/letta-ai/letta-code/pull/1608)
    )
*   Changed `history-analyzer` to use the same context constitution principles during history migration ([#1610](https://github.com/letta-ai/letta-code/pull/1610)
    )
*   Added `add-agent` support to server-mode websocket clients ([#1606](https://github.com/letta-ai/letta-code/pull/1606)
    )
*   Fixed duplicate OpenAI GPT-5.4 presets in model selection ([#1607](https://github.com/letta-ai/letta-code/pull/1607)
    )
*   Fixed `AskUserQuestion` and `ExitPlanMode` approvals to preserve the user’s draft input ([#1570](https://github.com/letta-ai/letta-code/pull/1570)
    )

0.21.5
------

[Section titled “0.21.5”](https://docs.letta.com/letta-code/changelog#0215)

*   Added `/personality` to swap between curated agent personality presets ([#1439](https://github.com/letta-ai/letta-code/pull/1439)
    )
*   Added `letta agents create` with `--personality`, `--description`, `--tags`, and `--pinned` options ([#1571](https://github.com/letta-ai/letta-code/pull/1571)
    )
*   Changed session history storage to use `~/.letta/` instead of `~/.letta-code/` ([#1588](https://github.com/letta-ai/letta-code/pull/1588)
    )
*   Added remote `/init`, richer git branch context, and improved client-side file editing in server mode ([#1600](https://github.com/letta-ai/letta-code/pull/1600)
    , [#1556](https://github.com/letta-ai/letta-code/pull/1556)
    , [#1589](https://github.com/letta-ai/letta-code/pull/1589)
    )
*   Added Bedrock fallback when Anthropic is unavailable ([#1569](https://github.com/letta-ai/letta-code/pull/1569)
    )
*   Fixed headless 409 recovery, no-op commit message creation, queued task notifications, and per-conversation subagent state in server mode ([#1591](https://github.com/letta-ai/letta-code/pull/1591)
    , [#1598](https://github.com/letta-ai/letta-code/pull/1598)
    , [#1595](https://github.com/letta-ai/letta-code/pull/1595)
    , [#1602](https://github.com/letta-ai/letta-code/pull/1602)
    )

0.21.4
------

[Section titled “0.21.4”](https://docs.letta.com/letta-code/changelog#0214)

*   No notable user-facing changes in this release

0.21.3
------

[Section titled “0.21.3”](https://docs.letta.com/letta-code/changelog#0213)

*   Added websocket `list_models` and `update_model` support for server-mode clients ([#1579](https://github.com/letta-ai/letta-code/pull/1579)
    )
*   Improved remote reflection progress updates with step counts, and fixed follow-up model update status messages ([#1578](https://github.com/letta-ai/letta-code/pull/1578)
    , [#1582](https://github.com/letta-ai/letta-code/pull/1582)
    )

0.21.2
------

[Section titled “0.21.2”](https://docs.letta.com/letta-code/changelog#0212)

*   Added advertised `supported_commands` in device status and remote `/doctor` command support for server-mode clients ([#1568](https://github.com/letta-ai/letta-code/pull/1568)
    , [#1572](https://github.com/letta-ai/letta-code/pull/1572)
    )
*   Added websocket reflection and sleeptime parity in server mode ([#1567](https://github.com/letta-ai/letta-code/pull/1567)
    )
*   Added remote skill enable/disable controls ([#1573](https://github.com/letta-ai/letta-code/pull/1573)
    )
*   Improved `/resume` to fetch only the messages it needs when resuming conversations ([#1550](https://github.com/letta-ai/letta-code/pull/1550)
    )

0.21.1
------

[Section titled “0.21.1”](https://docs.letta.com/letta-code/changelog#0211)

*   Fixed bundled skills to resolve script paths consistently across installations ([#1563](https://github.com/letta-ai/letta-code/pull/1563)
    )

0.21.0
------

[Section titled “0.21.0”](https://docs.letta.com/letta-code/changelog#0210)

*   Added `CONVERSATION_ID` to shell tool environments and agent info reminders ([#1557](https://github.com/letta-ai/letta-code/pull/1557)
    )
*   Improved message search performance by fetching active results before prefetching ([#1553](https://github.com/letta-ai/letta-code/pull/1553)
    )

0.19.11
-------

[Section titled “0.19.11”](https://docs.letta.com/letta-code/changelog#01911)

*   Added provider status page links on downstream model errors ([#1523](https://github.com/letta-ai/letta-code/pull/1523)
    )
*   Added Baseten Kimi model support and client-side file editing support ([#1529](https://github.com/letta-ai/letta-code/pull/1529)
    , [#1544](https://github.com/letta-ai/letta-code/pull/1544)
    )
*   Added optional `/fork` summaries and a `fork` subagent type that inherits the full parent conversation context ([#1530](https://github.com/letta-ai/letta-code/pull/1530)
    , [#1539](https://github.com/letta-ai/letta-code/pull/1539)
    )
*   Added server-mode `/init`, memfs sync on first message, and session-context reminders in listener mode ([#1534](https://github.com/letta-ai/letta-code/pull/1534)
    , [#1546](https://github.com/letta-ai/letta-code/pull/1546)
    , [#1536](https://github.com/letta-ai/letta-code/pull/1536)
    )
*   Fixed large-workspace file indexing OOMs and improved transient 521 recovery in remote mode ([#1533](https://github.com/letta-ai/letta-code/pull/1533)
    , [#1552](https://github.com/letta-ai/letta-code/pull/1552)
    )

0.19.10
-------

[Section titled “0.19.10”](https://docs.letta.com/letta-code/changelog#01910)

*   Fixed server-mode approval replay after interrupts ([#1521](https://github.com/letta-ai/letta-code/pull/1521)
    )

0.19.9
------

[Section titled “0.19.9”](https://docs.letta.com/letta-code/changelog#0199)

*   Added the `/secret` slash command for managing shell-command secrets ([#1435](https://github.com/letta-ai/letta-code/pull/1435)
    )
*   Added `/fork` to duplicate the current conversation into a new thread ([#1517](https://github.com/letta-ai/letta-code/pull/1517)
    )
*   Added automatic fallback to `letta/auto` when quota limits block the current model ([#1473](https://github.com/letta-ai/letta-code/pull/1473)
    )
*   Fixed conversation restore and persistence when resuming with `--agent` or `--name`, and kept `search_files` scoped to the current conversation cwd ([#1514](https://github.com/letta-ai/letta-code/pull/1514)
    , [#1515](https://github.com/letta-ai/letta-code/pull/1515)
    , [#1512](https://github.com/letta-ai/letta-code/pull/1512)
    )
*   Fixed websocket resume, streaming recovery, and background task notifications in server mode ([#1500](https://github.com/letta-ai/letta-code/pull/1500)
    , [#1505](https://github.com/letta-ai/letta-code/pull/1505)
    , [#1520](https://github.com/letta-ai/letta-code/pull/1520)
    )

0.19.8
------

[Section titled “0.19.8”](https://docs.letta.com/letta-code/changelog#0198)

*   Added the `/doctor` command to audit and refine an agent’s memory structure ([#1488](https://github.com/letta-ai/letta-code/pull/1488)
    )
*   Added client-side `memory_apply_patch` support for Codex toolsets, complementing the existing `memory` tool ([#1485](https://github.com/letta-ai/letta-code/pull/1485)
    )
*   Added memory tool event updates so connected clients can refresh memory state automatically ([#1495](https://github.com/letta-ai/letta-code/pull/1495)
    )
*   Improved `/resume` with progressive loading for large conversation lists ([#1462](https://github.com/letta-ai/letta-code/pull/1462)
    )
*   Fixed listener permission recovery, queued skill replay, retry deduplication, and related websocket resume issues ([#1492](https://github.com/letta-ai/letta-code/pull/1492)
    , [#1499](https://github.com/letta-ai/letta-code/pull/1499)
    , [#1502](https://github.com/letta-ai/letta-code/pull/1502)
    , [#1478](https://github.com/letta-ai/letta-code/pull/1478)
    )

0.19.7
------

[Section titled “0.19.7”](https://docs.letta.com/letta-code/changelog#0197)

*   Changed `/init` guidance to remove hard-coded memory file count and size targets ([#1483](https://github.com/letta-ai/letta-code/pull/1483)
    )
*   Changed memory file frontmatter so `description` is required while legacy `limit` remains optional ([#1484](https://github.com/letta-ai/letta-code/pull/1484)
    )
*   Added pre-commit validation for memory and skill formatting ([#1482](https://github.com/letta-ai/letta-code/pull/1482)
    )
*   Improved reflection snapshots by collapsing very large directories in the memory tree ([#1481](https://github.com/letta-ai/letta-code/pull/1481)
    )

0.19.6
------

[Section titled “0.19.6”](https://docs.letta.com/letta-code/changelog#0196)

*   Added MiniMax 2.7 as a supported model preset ([#1453](https://github.com/letta-ai/letta-code/pull/1453)
    )
*   Added optional conversation naming to `/new` ([#1451](https://github.com/letta-ai/letta-code/pull/1451)
    )
*   Changed `/search` to default to the current agent scope ([#1450](https://github.com/letta-ai/letta-code/pull/1450)
    )
*   Changed Letta Code to remove the `--continue` flag and rely on default resume, `--new`, `--resume`, and `--conversation` instead ([#1458](https://github.com/letta-ai/letta-code/pull/1458)
    )
*   Improved startup resume behavior for project-specific conversations and auto model routing context windows ([#1457](https://github.com/letta-ai/letta-code/pull/1457)
    , [#1463](https://github.com/letta-ai/letta-code/pull/1463)
    )

0.19.5
------

[Section titled “0.19.5”](https://docs.letta.com/letta-code/changelog#0195)

*   Changed `/resume` to sort conversations by most recent activity first ([#1444](https://github.com/letta-ai/letta-code/pull/1444)
    )
*   Fixed `LETTA_DEBUG` environment variable handling so debug logging is respected when set ([#1452](https://github.com/letta-ai/letta-code/pull/1452)
    )

0.19.4
------

[Section titled “0.19.4”](https://docs.letta.com/letta-code/changelog#0194)

*   Added the `memory` tool back to the default Claude, Codex, and Gemini toolsets ([#1447](https://github.com/letta-ai/letta-code/pull/1447)
    )
*   Fixed Electron and Node.js environments to fall back to `node-pty` when Bun is unavailable ([#1446](https://github.com/letta-ai/letta-code/pull/1446)
    )
*   Fixed listener approval reentry so queued turns drain correctly after approval recovery ([#1448](https://github.com/letta-ai/letta-code/pull/1448)
    )

0.19.3
------

[Section titled “0.19.3”](https://docs.letta.com/letta-code/changelog#0193)

*   Added Kitty keyboard protocol support for more reliable key handling in supported terminals ([#1334](https://github.com/letta-ai/letta-code/pull/1334)
    )
*   Added separate BYOK support for zAI Coding Plan accounts via `/connect zai-coding` ([#1434](https://github.com/letta-ai/letta-code/pull/1434)
    )
*   Changed `ExitPlanMode` to always require manual approval, even in `--yolo` mode ([#1440](https://github.com/letta-ai/letta-code/pull/1440)
    )
*   Fixed approval comments being preserved in tool responses for listener and client-tool integrations ([#1441](https://github.com/letta-ai/letta-code/pull/1441)
    , [#1442](https://github.com/letta-ai/letta-code/pull/1442)
    , [#1443](https://github.com/letta-ai/letta-code/pull/1443)
    )
*   Fixed permission mode sync issues in desktop listener sessions ([#1432](https://github.com/letta-ai/letta-code/pull/1432)
    , [#1437](https://github.com/letta-ai/letta-code/pull/1437)
    )

0.19.2
------

[Section titled “0.19.2”](https://docs.letta.com/letta-code/changelog#0192)

*   Fixed TUI live-preview flicker with post-highlight clipping ([#1423](https://github.com/letta-ai/letta-code/pull/1423)
    )
*   Changed default model selection to prefer `auto` instead of Sonnet ([#1429](https://github.com/letta-ai/letta-code/pull/1429)
    )
*   Fixed V2 listener terminal event wiring and required approval for `ExitPlanMode` in bypass mode ([#1430](https://github.com/letta-ai/letta-code/pull/1430)
    , [#1431](https://github.com/letta-ai/letta-code/pull/1431)
    )

0.19.1
------

[Section titled “0.19.1”](https://docs.letta.com/letta-code/changelog#0191)

*   In [Remote environments](https://docs.letta.com/letta-code/remote)
    , `letta server` now keeps [permission modes](https://docs.letta.com/letta-code/permissions)
     separate per conversation, and restores each conversation’s working directory and permission mode after a server restart
*   Added GPT-5.4 Mini and GPT-5.4 Nano model presets for OpenAI and ChatGPT Plus/Pro in [Models](https://docs.letta.com/letta-code/models)
    
*   Fixed [custom subagents](https://docs.letta.com/letta-code/subagents)
     loading when `.md` files use Windows line endings or a UTF-8 BOM in frontmatter
*   Fixed duplicate bypass auto-approvals in plan mode when the same tool call is replayed

0.19.0
------

[Section titled “0.19.0”](https://docs.letta.com/letta-code/changelog#0190)

*   Added a new `/recompile` slash command to recompile the current agent and conversation when you need to refresh prompt state manually
*   Added a client-side `memory` tool with git-backed sync for MemFS workflows, plus startup warnings when context repositories are not enabled
*   Changed built-in default agents and subagents to prefer auto model routing when available, with safer self-hosted fallbacks
*   Improved `/init` so shallow initialization adapts to your existing memory structure instead of assuming a fresh layout
*   Improved server mode listener sessions by scoping runtime state per conversation for more reliable parallel and resumed sessions
*   Fixed startup reconciliation for attached base tools and default summarization model settings on existing agents
*   Fixed status line refresh behavior and several subagent lifecycle and display issues

0.18.3
------

[Section titled “0.18.3”](https://docs.letta.com/letta-code/changelog#0183)

*   Added indexed `@` file search with persistent cache support
*   Added `.letta/.lettaignore` support and `MAX_ENTRIES` tuning in `~/.letta/.lettasettings` for file search indexing
*   Added source-faithful system prompt presets: `source-claude`, `source-codex`, and `source-gemini`
*   Added bundled `dispatching-coding-agents` skill
*   Added PTY terminal session support in `letta server` listener mode
*   Added `recover_pending_approvals` support in headless `--input-format stream-json` control requests
*   Added `gpt-5-mini-high` model preset
*   Changed `/init` to run through the primary agent as an interactive initialization flow
*   Improved shallow auto-init performance
*   Improved reflection subagent context by reading local transcript files
*   Improved `letta server` working-directory and environment cache persistence across restarts
*   Fixed model preset refresh and update-args fallback handling to preserve context window settings and BYOK compatibility
*   Fixed pre-stream `409 CONFLICT` busy handling to resume server-side runs
*   Fixed newly spawned subagents to default `memfs` to off

0.18.2
------

[Section titled “0.18.2”](https://docs.letta.com/letta-code/changelog#0182)

*   Fixed a Bun/Linux crash in vendored Ink input handling when `handleData` receives undefined input

0.18.1
------

[Section titled “0.18.1”](https://docs.letta.com/letta-code/changelog#0181)

*   Added syntax highlighting for Bash command previews in approval and tool-call UI
*   Improved diff rendering with syntax-highlighted output in the TUI
*   Fixed missing backfilled tool calls in streamed history rendering
*   Fixed plan file path race during `ExitPlanMode`
*   Fixed `--yolo` auto-approval while plan mode is active
*   Fixed leading-space artifacts on wrapped continuation lines in TUI text
*   Fixed token counting display in subagent status panels

0.18.0
------

[Section titled “0.18.0”](https://docs.letta.com/letta-code/changelog#0180)

*   Added recipe-based system prompt management
*   Added client-side skills loading and skill reminders
*   Added per-conversation working directories in server mode listener sessions
*   Added minimum Docker server version checks with upgrade guidance
*   Added `conversation_id` propagation on WebSocket listener events
*   Added plan mode system reminders in server mode
*   Added command hints for agents using non-default system prompts
*   Added ChatGPT Plus/Pro `gpt-5.4-fast` model tier support
*   Fixed Gemini 3.1 Pro Preview model handles
*   Fixed custom BYOK models not appearing in `/model` selector
*   Fixed listener queue pump recovery and parity in server mode
*   Fixed `ExitPlanMode` continuation across permission mode cycling

0.17.2
------

[Section titled “0.17.2”](https://docs.letta.com/letta-code/changelog#0172)

*   Added GPT-5.4, GPT-5.4 Fast, and GPT-5.4 Pro model support
*   Added `(Beta)` label to `letta/auto` and `letta/auto-fast` in model selector
*   Added blinking spinner for background subagent indicator in footer
*   Added `run_request_error` event in `letta remote` when initial POST fails
*   Excluded `AskUserQuestion` from headless mode toolset
*   Changed `default` system prompt preset to use the Letta system prompt instead of `letta-claude`
*   Changed free-tier default model from MiniMax M2.5 to GLM-5
*   Fixed `--system` flag to validate against known preset IDs instead of silently falling back
*   Fixed conversation model overrides not persisting across turns
*   Fixed conversation model override cleared on transient retrieve errors
*   Fixed stale `max_tokens` values lingering after model switch
*   Fixed `letta remote` interrupt recovery and reconnect hydration
*   Fixed `letta remote` stale approval conflicts after stop-reason errors
*   Fixed footer subagent link and alignment
*   Removed `--system-append` flag

0.17.0
------

[Section titled “0.17.0”](https://docs.letta.com/letta-code/changelog#0170)

*   Renamed `letta remote` to `letta server` (with `remote` kept as an alias)
*   Added `letta/auto` and `letta/auto-fast` model support in model selection
*   Added max (`xhigh`) reasoning tiers for Sonnet 4.6 and Opus 4.6
*   Added none/low/medium/high reasoning tiers for Opus 4.5
*   Added auto-init memory bootstrap on first message for new MemFS agents
*   Changed `/init` to use shallow and deep initialization tiers
*   Added subagent type tags when creating new subagents
*   Added `agent_id`, `conversation_id`, and `last_run_id` to `/statusline` payloads
*   Added agent-aware `/rename` hints in command-IO reminders
*   Changed app URL generation to use centralized `/chat` links
*   Fixed headless `409 CONFLICT` busy retries to use exponential backoff
*   Fixed startup guard for missing default conversation IDs
*   Fixed default-conversation API routing for SDK 1.7.11 (`conversation_id="default"` with `agent_id`)
*   Improved readability of command-IO and toolset-change reminders

0.16.15
-------

[Section titled “0.16.15”](https://docs.letta.com/letta-code/changelog#01615)

*   Added unified provider normalization for `/connect` and `letta connect`
*   Added `chatgpt` as canonical connect provider token (`codex` remains an alias)
*   Added background agent indicator in the footer
*   Added `background_agents` in `/statusline` payloads
*   Added listener version metadata in `letta remote` registration
*   Changed default model from Sonnet 4.5 to Sonnet 4.6
*   Fixed `Shift+Tab` to enter plan mode before auto-approve
*   Fixed `letta remote` re-registration to recover instead of crash
*   Fixed `/model` selection persistence for default conversations
*   Improved idle-time flushing of background subagent notifications
*   Improved `approve-always` pattern generation for read-only `gh` commands

0.16.14
-------

[Section titled “0.16.14”](https://docs.letta.com/letta-code/changelog#01614)

*   Added `/compaction` command for interactively selecting compaction mode
*   Added `--debug` flag to `letta remote` for plain-text console logging
*   Added always-on session log written to `~/.letta/logs/remote/` for every `letta remote` session
*   Added debug log file written to `~/.letta/logs/debug/` for diagnostics
*   Changed `/init` to run as a background subagent (non-blocking initialization)
*   Changed reflection subagent output to be silenced from the primary agent’s context
*   Fixed model selection not persisting when starting new conversations
*   Fixed Bash tool git commit and PR instructions for Codex and Gemini toolsets

0.16.13
-------

[Section titled “0.16.13”](https://docs.letta.com/letta-code/changelog#01613)

*   Added update availability notifications in TUI and footer when a newer version is released
*   Added `/compact self_compact_all` and `/compact self_compact_sliding_window` modes for agent-driven compaction
*   Added `/reasoning-tab` command to toggle Tab key cycling through reasoning effort levels (opt-in, disabled by default)
*   Added session usage details persistence shown in exit summary
*   Removed `plan` subagent (plan mode no longer delegates to a dedicated subagent)
*   Removed `defragmenting-memory` skill (memory subagent is now self-contained)
*   Fixed `/clear` command to skip server-side message reset for named conversations
*   Fixed `/model` and `/reasoning` commands to stay scoped to the current conversation
*   Fixed plan mode permission level being reliably restored after exiting
*   Fixed plan mode path handling with quote-aware shell parsing for `apply_patch` and scoped paths
*   Fixed Cloudflare HTML 5xx errors handled gracefully with user-friendly messages
*   Fixed ChatGPT `usage_limit_reached` errors to display the reset time
*   Fixed API key caching to survive keychain failures mid-session
*   Fixed clickable ADE and usage links in agent info bar
*   Fixed `/model` selector to deduplicate models by handle
*   Fixed model handle display removing `s:/t:` suffixes from status bar
*   Fixed auto-open file viewers being skipped in SSH sessions
*   Fixed memfs git credential helper value being redacted from debug logs
*   Improved streaming resilience in `letta remote` mode

0.16.12
-------

[Section titled “0.16.12”](https://docs.letta.com/letta-code/changelog#01612)

*   Renamed `letta listen` command to `letta remote` (old name still works as an alias)
*   Added automatic retry on empty LLM responses
*   Fixed `--conv default` working alongside `--new-agent` flag
*   Fixed approval data being preserved across stream resume boundaries
*   Fixed TUI reflow glitches in footer and on terminal resize
*   Fixed ADE link and streaming elapsed timer stability across terminal resizes

0.16.11
-------

[Section titled “0.16.11”](https://docs.letta.com/letta-code/changelog#01611)

*   Added GPT-5.3 Codex model tiers support
*   Fixed WebSocket connectivity issue
*   Fixed cosmetic display issue for newly created agents

0.16.10
-------

[Section titled “0.16.10”](https://docs.letta.com/letta-code/changelog#01610)

*   Simplified `letta listen` command: removed explicit binding flags and added auto-generated session names
*   Fixed API key detection to read from environment variables rather than checking repo secrets
*   Fixed memory defrag flow for git-backed memfs

0.16.9
------

[Section titled “0.16.9”](https://docs.letta.com/letta-code/changelog#0169)

*   Fixed settings collision when running Letta Code from the home directory (project vs. global settings conflict)
*   Updated featured models list to show only the latest frontier model per provider

0.16.8
------

[Section titled “0.16.8”](https://docs.letta.com/letta-code/changelog#0168)

*   Fixed hooks not logging a full error stack trace when project settings are absent

0.16.7
------

[Section titled “0.16.7”](https://docs.letta.com/letta-code/changelog#0167)

*   Added `/install-github-app` setup wizard for GitHub App integration
*   Added `bootstrap_session_state` headless API for pre-configuring session state and memfs startup policy
*   Fixed startup performance by skipping no-op preset refresh when resuming existing agents
*   Fixed duplicate frontmatter blocks appearing in memory subagent prompt
*   Fixed interactive tools from being auto-approved in listen mode
*   Fixed headless `list_messages` to scope correctly to the default conversation
*   Fixed last-character clipping on deferred-wrap terminals

0.16.6
------

[Section titled “0.16.6”](https://docs.letta.com/letta-code/changelog#0166)

*   Fixed user permission settings path to use `~/.letta` instead of `~/.config/letta`

0.16.5
------

[Section titled “0.16.5”](https://docs.letta.com/letta-code/changelog#0165)

*   Fixed default conversation sentinel handling in headless startup

0.16.4
------

[Section titled “0.16.4”](https://docs.letta.com/letta-code/changelog#0164)

*   Added headless `list-messages` protocol command
*   Fixed reasoning tag display when reasoning is set to none
*   Disabled xhigh reasoning tier for Anthropic models

0.16.3
------

[Section titled “0.16.3”](https://docs.letta.com/letta-code/changelog#0163)

*   Added `/palace` command alias for Memory Palace
*   Added plan viewer with browser preview (opens plan markdown in browser)
*   Added symlink support for skills installed in `~/.letta/skills/`
*   Fixed Node 18 compatibility with `node:crypto` import
*   Fixed `bypassPermissions` mode not persisting across transient retries
*   Fixed transcript backfill on conversation resume
*   Fixed assistant anchor recency on resume
*   Fixed default conversation for freshly created subagents
*   Fixed compaction reflection trigger for legacy summary format
*   Fixed model preset settings not refreshing on resume

0.16.2
------

[Section titled “0.16.2”](https://docs.letta.com/letta-code/changelog#0162)

*   Improved startup performance by eliminating redundant API calls
*   Fixed slash commands blocked after interrupt during tool execution
*   Fixed Memory Palace auto-open in tmux on macOS
*   Fixed shared reminders disabled for subagents
*   Fixed env var resolution in reflection/history-analyzer commit trailers
*   Fixed Memory Palace nesting level display
*   Fixed Memory Palace handling of `$` in memory content
*   Fixed retry on quota limit errors

0.16.1
------

[Section titled “0.16.1”](https://docs.letta.com/letta-code/changelog#0161)

*   Added Memory Palace static HTML viewer (opens memory visualization in browser from `/memfs`)
*   Added auto-enable memfs from server-side tag on new machines
*   Fixed error formatting for `/init`
*   Fixed version reporting in feedback and telemetry
*   Fixed headless mode defaulting to new conversation to prevent 409 race
*   Fixed `/memory` command label to say “memory” instead of “memory blocks”
*   Fixed `max_output_tokens` for GPT-5 reasoning variants
*   Fixed LLM streaming error provider mapping

0.16.0
------

[Section titled “0.16.0”](https://docs.letta.com/letta-code/changelog#0160)

*   Added reasoning settings step to `/model` selector for choosing reasoning tier after model selection
*   Added Tab key cycling of reasoning tiers from the input area
*   Added Sonnet 4.6 1M context window model variant
*   Added Gemini 3.1 Pro Preview model support
*   Added `auto` option for toolset mode with persistence across sessions
*   Added `LETTA_MEMFS_LOCAL` env var to enable memfs on self-hosted servers
*   Added Edit tool start line number in code diff display
*   Added elapsed time display for running shell tools
*   Added memory application guidance to system prompts
*   Aligned TaskOutput display format with Bash output
*   Fixed slash commands incorrectly opening state when no arguments are accepted
*   Fixed ADE links for default conversation
*   Fixed user settings being clobbered on save
*   Fixed Gemini/GLM tools not working in plan mode
*   Fixed permission mode desyncs in YOLO approval handling
*   Fixed reasoning effort display in footer and model selector
*   Fixed conversation routing after creating new agent in `/agents`
*   Fixed plan file `apply_patch` paths not allowed in plan mode
*   Fixed auto toolset detection for ChatGPT OAuth as Codex
*   Fixed agents limit exceeded retry behavior
*   Fixed default agent creation when base tools are missing
*   Disabled hidden SDK retries for streaming POSTs
*   Removed Sonnet 4.5 from featured models

0.15.6
------

[Section titled “0.15.6”](https://docs.letta.com/letta-code/changelog#0156)

*   Added `sonnet` shortcut for Sonnet 4.6 model in `-m` flag

0.15.5
------

[Section titled “0.15.5”](https://docs.letta.com/letta-code/changelog#0155)

*   Added Sonnet 4.6 model support (set as new default model)
*   Changed featured model from Sonnet 4.5 to Sonnet 4.6

0.15.4
------

[Section titled “0.15.4”](https://docs.letta.com/letta-code/changelog#0154)

*   Added `--skill-sources` flag to control which skill sources are enabled (comma-separated: `bundled`, `global`, `agent`, `project`, or `all`)
*   Added `--no-bundled-skills` flag to disable only bundled skills while keeping other sources
*   Added headless reflection settings: `--reflection-trigger`, `--reflection-behavior`, `--reflection-step-count`
*   Added `--no-system-info-reminder` flag to suppress first-turn environment context reminder

0.15.3
------

[Section titled “0.15.3”](https://docs.letta.com/letta-code/changelog#0153)

*   Added `MEMORY_DIR` and `AGENT_ID` environment variables exposed in shell tools
*   Fixed ChatGPT connection and OAuth error retry classification
*   Fixed slash command queueing while agent is running
*   Fixed memfs/standard prompt section reconciliation
*   Fixed auto-update execution and release gating
*   Fixed interrupt timer reset on eager cancel
*   Fixed skills reminders appearing in headless sessions
*   Removed `max_turns` option from Task tool

0.15.2
------

[Section titled “0.15.2”](https://docs.letta.com/letta-code/changelog#0152)

*   Added `/skills` command to browse available skills by source (bundled, global, agent, project)
*   Added `memfs_enabled` status in headless init messages
*   Fixed agent not being reused on directory switch (no longer creates unnecessary new agents)
*   Fixed over-escaped strings in Edit tool
*   Fixed memfs git pull authentication and credential URL normalization
*   Fixed shell auto-approval path checks
*   Fixed Windows absolute file-rule matching in permissions
*   Fixed bundled JS subagent launcher on Windows
*   Fixed model tier selection when model ID is selected directly

0.15.1
------

[Section titled “0.15.1”](https://docs.letta.com/letta-code/changelog#0151)

*   Added `--no-skills` flag to disable bundled skills
*   Added `--tags` flag for headless mode agent tagging
*   Added MiniMax M2.5 model support
*   Added specific retry messages for known LLM provider errors
*   Improved reflection subagent to autonomously complete merge and push operations
*   Removed `conversation_search` from default toolset
*   Fixed ghost assistant messages when Anthropic returns `[text, thinking, text]` block order
*   Fixed CONFLICT errors after interrupt during tool execution
*   Fixed interrupt recovery to only trigger on real user interrupts
*   Fixed memfs init steps in headless mode
*   Fixed ADE default conversation link

0.15.0
------

[Section titled “0.15.0”](https://docs.letta.com/letta-code/changelog#0150)

*   Added git-backed memory filesystem sync with automatic commit and push
*   Added `reflection` subagent for background memory analysis and updates
*   Added `history-analyzer` subagent and `migrating-from-codex-and-claude-code` skill for importing history from Claude Code and Codex CLIs
*   Added `/statusline` command for configurable CLI footer status lines
*   Added `/sleeptime` command for client-side reflection trigger settings
*   Added `/compact [all|sliding_window]` mode options
*   Added GLM-5 model support
*   Renamed `/download` to `/export` and `--from-af` to `--import` (old names still work as aliases)
*   Changed compaction to set summary as first message in conversation
*   Fixed `@` file browser deep recursive search when browsing parent directories
*   Fixed `/context` double rendering on short terminals
*   Fixed system-reminder tag rendering in message backfill
*   Fixed stream ID accumulator collisions

0.14.16
-------

[Section titled “0.14.16”](https://docs.letta.com/letta-code/changelog#01416)

*   Added custom tools support for SDK-side tool registration and execution in bidirectional mode
*   Added agent registry import support (`@author/name` format for `--from-af`)
*   Added `PreCompact` hooks now fire during server-side automatic compaction
*   Fixed OpenAI encrypted content organization mismatch error handling
*   Fixed headless pre-stream approval conflict recovery
*   Fixed slash-prefixed messages without trailing space not being sendable
*   Fixed model updates not sending `max_tokens` configuration to cloud
*   Fixed memfs not detaching all memory tool variants when enabled
*   Improved headless mode interactive tool behavior for bidirectional parity

0.14.15
-------

[Section titled “0.14.15”](https://docs.letta.com/letta-code/changelog#01415)

*   Added brand accent color for markdown link text
*   Improved rendering stability and flicker prevention across footer and streaming status
*   Improved always-allow behavior for skill script permissions
*   Improved error guidance for model availability and credit issues
*   Fixed `memory` defrag subagent to run in background
*   Fixed MiniMax errors at higher token counts
*   Fixed duplicate feedback command output on submit
*   Fixed oversized shell tool output clipping in collapsed tool results
*   Fixed task transcript propagation for max-step failures
*   Removed ChatGPT OAuth Pro plan restriction for Codex connect

0.14.14
-------

[Section titled “0.14.14”](https://docs.letta.com/letta-code/changelog#01414)

*   Fixed `--max-turns` flag not accepted at top-level CLI
*   Fixed subagent keychain migration churn

0.14.13
-------

[Section titled “0.14.13”](https://docs.letta.com/letta-code/changelog#01413)

*   Added GPT-5.3 Codex model support (ChatGPT Plus/Pro)
*   Added permission mode restoration when exiting plan mode
*   Fixed headless permission wait deadlock
*   Fixed `/model` selection for shared-handle model tiers with different reasoning efforts
*   Fixed subagent model display consistency

0.14.12
-------

[Section titled “0.14.12”](https://docs.letta.com/letta-code/changelog#01412)

*   Rewrote the Skill tool from load/unload commands to direct invocation (`skill: "name"` with optional `args`)
*   Removed `skills` and `loaded_skills` memory blocks (skills are now listed in system-reminder messages)
*   Added `--embedding` flag to specify embedding model when creating agents in headless mode
*   Added `/context` command token usage breakdown by category (system, core memory, functions, messages)
*   Added `showCompactions` setting to hide compaction messages (defaults to `false`)
*   Added `LETTA_PACKAGE_MANAGER` env var to override detected package manager for auto-updates
*   Changed featured model from Opus 4.5 to Opus 4.6
*   Improved auto-updater to detect package manager (npm/bun/pnpm) instead of hardcoding npm
*   Improved subagent auth to inherit credentials from parent, avoiding keychain contention
*   Improved keychain availability check to use a non-mutating probe instead of set/delete
*   Fixed `UserPromptSubmit` hook firing repeatedly on message dequeue
*   Fixed `Stop` hook using first user message instead of most recent
*   Removed `Setup` hook event type
*   Updated memfs skill and system prompt

0.14.11
-------

[Section titled “0.14.11”](https://docs.letta.com/letta-code/changelog#01411)

*   Added prompt-based hooks that use an LLM to evaluate whether actions should be allowed or blocked
*   Added `/context` command braille area chart showing token usage history across turns
*   Added skills extraction and packaging for `--from-af` agent file imports
*   Added `max_turns` parameter to Task tool for limiting subagent turn count
*   Improved message queue to wait for tool completion instead of using a 15-second timeout
*   Fixed Shift+Enter by normalizing newlines before keypress parsing
*   Fixed keyboard protocol report filtering and scoped Linux Enter key handling
*   Fixed `loaded_skills` block not resetting on new conversation
*   Fixed memFS system prompt not updating based on `--memfs`/`--no-memfs` CLI flags
*   Fixed empty assistant message bullets rendering
*   Fixed skills directory path shown in extraction message
*   Fixed subagent static promotion race during tool result reentry

0.14.10
-------

[Section titled “0.14.10”](https://docs.letta.com/letta-code/changelog#01410)

*   Added `/context` command to show context window usage with visual token bar
*   Added background task support for `Task` and `Bash` tools via `run_in_background` parameter
*   Added `TaskOutput` tool to retrieve output from background tasks
*   Added `TaskStop` tool to stop running background tasks
*   Added background task completion notifications injected into conversation
*   Added `additionalContext` support for `PostToolUse` hooks (JSON output parsed for context injection)
*   Added Claude Opus 4.6 model support
*   Improved subagent status display with aligned dots, headers, and dimming for running agents
*   Improved tool call dot phases and colors for clearer execution feedback
*   Fixed `/download` command to pass `conversation_id` for non-default conversations

0.14.9
------

[Section titled “0.14.9”](https://docs.letta.com/letta-code/changelog#0149)

*   Added number key support (1-9) to approval dialogs for quick selection
*   Enabled memfs in headless mode when using `--agent` flag
*   Fixed Enter key handling on Linux terminals that emit `\n` instead of `\r`
*   Fixed error handling in headless bidirectional mode
*   Fixed MCP skill templates with corrected paths
*   Fixed malformed `AskUserQuestion` falling through to generic approval

0.14.8
------

[Section titled “0.14.8”](https://docs.letta.com/letta-code/changelog#0148)

*   Added `converting-mcps-to-skills` bundled skill for connecting to MCP servers
*   Added `PostToolUseFailure` hook that runs after tool failures (feeds stderr back to agent)
*   Added `SessionEnd` hooks now run on Ctrl+C (SIGINT)
*   Added conversation renaming when renaming agents via `/rename`
*   Improved `SessionStart` hooks with feedback injection
*   Improved post tool use feedback injection
*   Fixed compaction display to show simple “Conversation compacted” message
*   Fixed context windows fetched from server instead of hardcoded
*   Fixed Windows PATH handling and PowerShell quoting
*   Fixed thinking/assistant block spacing preservation during streaming
*   Fixed logo resetting to flat frame when loading completes
*   Fixed duplicate rendering of auto-approved file tools
*   Fixed 409 “conversation busy” errors with exponential backoff
*   Fixed flicker on tall approval dialogs

0.14.7
------

[Section titled “0.14.7”](https://docs.letta.com/letta-code/changelog#0147)

*   Added trajectory stats tracking and completion summary on exit
*   Improved `/memory` viewer to prioritize `system/` directory at top
*   Fixed input area collapsing during approvals and selector overlays
*   Fixed slash command menu render flicker
*   Fixed rendering instability that caused line flicker

0.14.6
------

[Section titled “0.14.6”](https://docs.letta.com/letta-code/changelog#0146)

*   Added alien art to command preview and exit message
*   Added BYOK-aware model resolution with fallback for subagents
*   Added network phase arrows to streaming status indicator
*   Fixed handling of malformed `AskUserQuestion` data from LLM
*   Fixed `/usage` command formatting
*   Fixed `/memfs` position in command autocomplete order
*   Fixed mojibake detection to preserve valid Unicode characters
*   Fixed loading state layout consistency during startup
*   Fixed autocomplete to show “No matching commands” instead of hiding
*   Fixed `<Text>` encoding non-ASCII characters in Bun

0.14.5
------

[Section titled “0.14.5”](https://docs.letta.com/letta-code/changelog#0145)

*   Added `--from-agent` flag for agent-to-agent communication in headless mode
*   Refactored skill scripts into CLI subcommands (`letta memfs`, `letta blocks`, etc.)

0.14.4
------

[Section titled “0.14.4”](https://docs.letta.com/letta-code/changelog#0144)

*   Added compaction messages display and new summary message type handling
*   Fixed skill diffing code
*   Fixed memfs skill scripts

0.14.3
------

[Section titled “0.14.3”](https://docs.letta.com/letta-code/changelog#0143)

*   Fixed memfs frontmatter round-trip to preserve block metadata

0.14.2
------

[Section titled “0.14.2”](https://docs.letta.com/letta-code/changelog#0142)

*   Fixed extra vertical spacing between memory block tabs
*   Fixed Task tool approval dialogs to show full prompt
*   Improved memfs sync performance

0.14.1
------

[Section titled “0.14.1”](https://docs.letta.com/letta-code/changelog#0141)

*   Enabled Memory Filesystem (memfs) by default for newly created agents
*   Added `--memfs` / `--no-memfs` CLI flags to control memfs on agent creation
*   Fixed Bun string encoding issues

0.14.0
------

[Section titled “0.14.0”](https://docs.letta.com/letta-code/changelog#0140)

This release introduces **Memory Filesystem** (experimental) - your agent’s memory blocks now sync with local files in `.letta/memory/`, enabling direct editing and version control of agent memory.

### Memory Filesystem (experimental)

[Section titled “Memory Filesystem (experimental)”](https://docs.letta.com/letta-code/changelog#memory-filesystem-experimental)

*   Added Memory Filesystem (memfs) that syncs memory blocks with `.letta/memory/` directory
*   Added agent-driven conflict resolution for memfs sync conflicts
*   Added `/memfs` command to view sync status and resolve conflicts
*   Added owner tags for tracking block ownership (system vs agent-created)
*   Added hierarchical memory organization with `system/` prefix for core blocks
*   Added `syncing-memory-filesystem` built-in skill for conflict resolution guidance
*   Updated `/init` to create hierarchically organized memory blocks
*   Updated `defragmenting-memory` skill to use memfs instead of backup/restore scripts

### New Models and Providers

[Section titled “New Models and Providers”](https://docs.letta.com/letta-code/changelog#new-models-and-providers)

*   Added MiniMax M2.1 model support
*   Added MiniMax BYOK support via `/connect`
*   Added Kimi K2.5 model support
*   Added OpenRouter BYOK support via `/connect`
*   Added AWS Bedrock profile authentication method
*   Added Bedrock Opus 4.5 fallback suggestion for Anthropic API errors

### Hooks Enhancements

[Section titled “Hooks Enhancements”](https://docs.letta.com/letta-code/changelog#hooks-enhancements)

*   Added `UserPromptSubmit` hook that fires when user submits a prompt
*   Added `reasoning` and `assistant_message` capture in `PostToolUse` and `Stop` hooks
*   Added `LETTA_AGENT_ID` environment variable injection into hooks
*   Added “Disable all hooks” toggle in `/hooks` command
*   Added memory log hook example script

### Other Features

[Section titled “Other Features”](https://docs.letta.com/letta-code/changelog#other-features)

*   Added agent-scoped skills directory (`~/.letta/agents/{id}/skills/`)
*   Added user prompt message highlighting
*   Added permissions status script
*   Changed `conversation_search` to no longer be a default tool (use `recall` subagent instead)

### Fixes

[Section titled “Fixes”](https://docs.letta.com/letta-code/changelog#fixes)

*   Fixed up/down arrow navigation with newlines in multi-line input
*   Fixed cursor visibility on newline characters in multi-line input
*   Fixed `@file` search to exclude `venv` and dependency directories
*   Fixed `/feedback` command formatting and context
*   Fixed approval dialog horizontal lines to extend full terminal width
*   Fixed default agent creation on first bootup
*   Fixed paste support in hooks TUI inputs
*   Fixed hooks TUI with Enter to delete and better spacing
*   Fixed help text for `letta --new` flag
*   Fixed `UserPromptSubmit` hooks to not fire for slash commands
*   Fixed subagents to be marked as hidden on creation
*   Fixed LLM error retry to not retry 4xx client errors
*   Fixed model selector display on self-hosted when default model unavailable

0.13.11
-------

[Section titled “0.13.11”](https://docs.letta.com/letta-code/changelog#01311)

*   Fixed agents limit exceeded error and added deletion support in `/agents`
*   Fixed `-m` flag to correctly apply model variants with same handle

0.13.10
-------

[Section titled “0.13.10”](https://docs.letta.com/letta-code/changelog#01310)

*   Added AWS Bedrock support to `/connect` command
*   Added multi-server support with settings indexed by server URL
*   Added regex tool name matching for hooks (e.g., `"Edit|Write"`)
*   Added message retry on premature interrupt
*   Added desktop notification hook script
*   Added `rm -rf` block hook script example
*   Improved `/connect` command and model selector UX
*   Disabled Incognito agent creation by default
*   Fixed default model selection to use billing tier (free tier uses glm-4.7)
*   Fixed self-hosted and localhost model selection during agent creation
*   Fixed login screen styling to match other menus
*   Fixed error message formatting

0.13.9
------

[Section titled “0.13.9”](https://docs.letta.com/letta-code/changelog#0139)

*   Added Stop hook continuation on blocking (hook can keep agent working)
*   Added example hook scripts for common patterns
*   Improved `memory` subagent to produce hierarchical memory block structures
*   Improved message queueing for smoother UX
*   Fixed backfill failures to be handled gracefully instead of crashing

0.13.8
------

[Section titled “0.13.8”](https://docs.letta.com/letta-code/changelog#0138)

*   Added search field to model selector (both Supported and All Available tabs)
*   Fixed `/compact` to use correct conversations endpoint
*   Fixed agent info bar layout to prevent overflow

0.13.7
------

[Section titled “0.13.7”](https://docs.letta.com/letta-code/changelog#0137)

*   Added Claude Code-compatible hooks system with `/hooks` command for automating workflows
*   Added cross-platform support for hooks executor (Windows, macOS, Linux)
*   Added ViewImage tool for attaching local images to conversation context
*   Added search field to model selector on both tabs
*   Added Bedrock Opus 4.5 model
*   Added conversation ID display in agent info bar
*   Added immediate mode for interactive commands
*   Improved cancellation with graceful 30s timeout before force-abort
*   Fixed bash mode input locking, ESC cancellation, and removed timeout
*   Fixed bash mode process group spawn/kill for proper cleanup
*   Fixed bash mode Ctrl+C interrupt handling
*   Fixed toolset switching to be atomic (prevents tool desync race)
*   Fixed hooks config state to use settings as source of truth
*   Fixed @ file selection during search debounce
*   Fixed 5MB image size limit with progressive compression
*   Fixed invalid tool call ID recovery
*   Fixed stale queued approvals after successful approval flow
*   Fixed Skill tool isolated blocks in conversation context
*   Fixed messages starting with `/` to be sent to agent when unknown command
*   Fixed auto-update ENOTEMPTY errors with cleanup and retry

0.13.6
------

[Section titled “0.13.6”](https://docs.letta.com/letta-code/changelog#0136)

*   Added image reading support to Read tool (PNG, JPG, GIF, WEBP, BMP files are visually displayed)
*   Added shell alias expansion in bash mode (sources from `.zshrc`, `.bashrc`, etc.)
*   Added query prefill support for `/search` command (`/search [query]`)
*   Added arrow key navigation for tab switching in `/models`
*   Improved Skill tool output with more explicit success messages
*   Added automatic retry for 409 “conversation busy” errors
*   Added message restoration to input field after queue errors
*   Fixed agent name consistency using single source of truth
*   Fixed `/clear` command output message to clarify messages are moved to history
*   Fixed streaming flicker with aggressive static content promotion
*   Fixed cursor position placed at end when navigating command history
*   Fixed ADE links to work in tmux
*   Reduced image resize limit to 2000px for multi-image requests
*   Fixed queue-cancel hang and stuck queue issues
*   Fixed premature cancellation of server-side tools in mixed execution

0.13.5
------

[Section titled “0.13.5”](https://docs.letta.com/letta-code/changelog#0135)

*   Added automatic image resizing for clipboard paste (images larger than 2048x2048 are resized to fit API limits)
*   Improved error feedback when image paste fails
*   Fixed conversation ID being passed correctly to resume data retrieval

0.13.4
------

[Section titled “0.13.4”](https://docs.letta.com/letta-code/changelog#0134)

**Default startup behavior reverted to single-threaded experience.** Based on user feedback, `letta` (with no flags) now resumes the agent’s “default” conversation instead of creating a new conversation each time.

| Command | 0.13.0 - 0.13.3 | 0.13.4+ |
| --- | --- | --- |
| `letta` | Creates new conversation each time | Uses “default” conversation |
| `letta --new` | Error (was deprecated) | Creates a new conversation |
| `letta --continue` (no session) | Silently creates new | Errors with helpful message |

*   Changed `letta` (no flags) to resume the “default” conversation with message history
*   Repurposed `--new` flag to create a new conversation (for users who want concurrent sessions)
*   Changed `--continue` fallback to error with helpful suggestions instead of silently creating new

0.13.3
------

[Section titled “0.13.3”](https://docs.letta.com/letta-code/changelog#0133)

*   Added `messaging-agents` bundled skill for sending messages to other agents
*   Added ability to deploy existing agents as subagents via the Task tool
*   Fixed interrupt handling race condition when tool approvals are in flight

0.13.2
------

[Section titled “0.13.2”](https://docs.letta.com/letta-code/changelog#0132)

*   Added skills frontmatter pre-loading for subagents (skills defined in subagent configs are auto-loaded)
*   Added output truncation for Task tool to prevent context overflow
*   Added auto-cleanup for overflow files
*   Fixed auto-allowed tool execution tracking for proper interrupt handling
*   Fixed hardcoded embedding model (now uses server default)

0.13.1
------

[Section titled “0.13.1”](https://docs.letta.com/letta-code/changelog#0131)

*   Added `--default` flag to access agent’s default conversation (alias for `--conv default`)
*   Added `--conv <agent-id>` shorthand (e.g., `letta --conv agent-xyz` → uses that agent’s default conversation)
*   Added default conversation to `/resume` selector (appears at top of list)
*   Added `working-in-parallel` bundled skill for coordinating parallel subagent tasks
*   Added conversation resume hint in exit stats
*   Improved startup performance with reduced time-to-boot
*   Fixed stale approvals being auto-cancelled on session resume
*   Fixed auth type display on startup
*   Fixed memory block retrieval for `/memory` command

0.13.0
------

[Section titled “0.13.0”](https://docs.letta.com/letta-code/changelog#0130)

This release introduces **Conversations** - a major change to how Letta Code manages chat sessions. Your agent can now have many parallel conversations, each contributing to its learning, memory, and shared history.

### What Changed

[Section titled “What Changed”](https://docs.letta.com/letta-code/changelog#what-changed)

**Before 0.13.0:**

*   Each agent had a single conversation
*   Starting Letta Code resumed the same conversation
*   `/clear` reset the agent’s context window

**After 0.13.0 (updated in 0.13.4):**

*   Each startup resumes the **default conversation** (reverted from 0.13.0-0.13.3 behavior)
*   Your agent’s **memory is shared** across all conversations
*   `/new` creates a new conversation (for parallel sessions)
*   `/clear` clears in-context messages
*   Use `/resume` to browse and switch between past conversations
*   Use `letta --new` to create a new conversation for concurrent sessions

### Migration Guide

[Section titled “Migration Guide”](https://docs.letta.com/letta-code/changelog#migration-guide)

If you’re upgrading from an earlier version, you may notice that starting Letta Code puts you in a **new conversation** instead of continuing where you left off. Here’s what happened:

**Your old messages still exist!** They’re in your agent’s **default conversation** - the original message history before conversations were introduced. You can find it at the top of the `/resume` selector, or access it directly with the commands below.

**Easiest way to access them (0.13.1+):**

    # Use the --default flag with your agent nameletta -n "Your Agent Name" --default
    # Or with agent IDletta --agent <your-agent-id> --default
    # Or use the shorthand (agent ID only)letta --conv <your-agent-id>

The default conversation also appears at the top of the `/resume` selector.

**Alternative methods:**

1.  **View them on the web** at `https://app.letta.com/agents/<your-agent-id>`
    
2.  **Have your agent recall them** using one of these prompts:
    
    **Using the `recall` subagent:**
    
        Can you use the recall subagent to find our most recent messages? I'd like to continue where we left off.
    
    **Using the `conversation_search` tool:**
    
        Can you use conversation_search to find our most recent messages so we can continue where we left off?
    
    **Using the `searching-messages` skill:**
    
        Can you load the searching-messages skill and use it to find our most recent messages?
    
3.  **Export and reference your agent file** by running `/export` (saves to `<agent-id>.af`), then ask your agent:
    
        I downloaded my agent file to ./agent-xxxx.af - can you read it and look through the "messages" array to find our most recent conversation?
    

Going forward, all new conversations will be accessible via `/resume`, and the default conversation is always available via `--default`.

### Full Changelog

[Section titled “Full Changelog”](https://docs.letta.com/letta-code/changelog#full-changelog)

*   Added Conversations support - each session creates an isolated conversation while sharing agent memory
*   Added `/resume` command to browse and switch between past conversations
*   Added `--resume` (`-r`) and `--continue` (`-c`) flags to resume last session
*   Added `--conversation` (`-C`, `--conv`) flag to resume a specific conversation by ID
*   Added default agents (Memo and Incognito) auto-created for new users
*   Changed `/clear` to start a new conversation (non-destructive) instead of deleting messages (reverted in 0.13.4)
*   Fixed Task tool rendering issues with parallel subagents
*   Fixed ADE links to include conversation context

0.12.7
------

[Section titled “0.12.7”](https://docs.letta.com/letta-code/changelog#0127)

*   Fixed text wrapping in collapsed bash output display
*   Renamed `memory-defrag` skill to `defragmenting-memory` to follow naming conventions
*   Added automatic retry for transient network errors during LLM streaming
*   Improved plan mode flexibility for writing plan files

0.12.6
------

[Section titled “0.12.6”](https://docs.letta.com/letta-code/changelog#0126)

*   Added `memory` subagent for cleaning up and reorganizing memory blocks
*   Added `defragmenting-memory` built-in skill with backup/restore workflow
*   Added streaming output display for long-running bash commands
*   Added line count summary for Read tool results
*   Added network retry for transient LLM streaming errors
*   Added Skill tool support in plan mode (load/unload/refresh are read-only)
*   Fixed tool approval flow that was broken by ESC handling changes
*   Improved Task tool and subagent display rendering
*   Fixed UI flickering in Ghostty terminal

0.12.5
------

[Section titled “0.12.5”](https://docs.letta.com/letta-code/changelog#0125)

*   Added terminal title and progress indicator for approval screens
*   Added `LETTA_DEBUG_TIMINGS` environment variable for request timing diagnostics
*   Fixed “Create new agent” from selector being stuck in a loop

0.12.4
------

[Section titled “0.12.4”](https://docs.letta.com/letta-code/changelog#0124)

*   Fixed subagent display spacing and extra newlines
*   Fixed subagent live streaming not updating during execution

0.12.3
------

[Section titled “0.12.3”](https://docs.letta.com/letta-code/changelog#0123)

*   Added LSP diagnostics to Read tool for TypeScript and Python files
*   Added `refresh` command to Task tool for rescanning custom subagents
*   Added file-based overflow for long tool outputs
*   Fixed left/right arrow key cursor navigation in approval text inputs
*   Fixed pre-stream approval desync errors with keep-alive recovery
*   Fixed subagents not inheriting parent’s tool permission rules

0.12.2
------

[Section titled “0.12.2”](https://docs.letta.com/letta-code/changelog#0122)

*   Added `/ralph` and `/yolo-ralph` commands for autonomous agentic loop mode
*   Fixed read-only subagents (explore, plan, recall) to work in plan mode
*   Fixed Windows PowerShell ENOENT errors with shell fallback

0.12.1
------

[Section titled “0.12.1”](https://docs.letta.com/letta-code/changelog#0121)

*   Added `recall` subagent for searching parent agent’s conversation history
*   Fixed agent selector not showing when LRU agent retrieval fails
*   Fixed approval desync issues for slash commands and queued messages
*   Fixed SDK retry race conditions on streaming requests
*   Fixed pending approval denials not being cached on ESC interrupt
*   Fixed stale processConversation calls affecting UI state after interrupts

0.12.0
------

[Section titled “0.12.0”](https://docs.letta.com/letta-code/changelog#0120)

*   Refactored to use new client-side tool calling via the messages endpoint
*   Added `acquiring-skills` skill for discovering and installing skills from external repositories
*   Added `migrating-memory` skill for copying memory blocks between agents
*   Updated skills system (migrating-memory, finding-agents, searching-messages)
*   Improved interrupt handling with better messaging
*   Fixed ESC interrupt to properly stop streams
*   Fixed skill scripts to work when installed via npm
*   Fixed Task tool (subagent) rendering issues
*   Fixed bash mode exit behavior after submitting commands
*   Fixed binary file detection being overly aggressive
*   Fixed approval results handling when auto-handling remaining approvals
*   Fixed stream retry behavior after interrupts

0.11.1
------

[Section titled “0.11.1”](https://docs.letta.com/letta-code/changelog#0111)

*   Added system prompt and memory block configuration for headless mode
*   Added `--input-format stream-json` flag for programmatic input handling
*   Improved parallel tool call approval UI

0.11.0
------

[Section titled “0.11.0”](https://docs.letta.com/letta-code/changelog#0110)

*   Added inline dialogs for improved user experience
*   Improved token counter display
*   Fixed server-side tools incorrectly showing as interrupted

0.10.5
------

[Section titled “0.10.5”](https://docs.letta.com/letta-code/changelog#0105)

*   Fixed Windows installation issues
*   Fixed keyboard shortcuts for Ctrl+C, Ctrl+V, and Shift+Enter

0.10.4
------

[Section titled “0.10.4”](https://docs.letta.com/letta-code/changelog#0104)

*   Fixed iTerm2 keybindings
*   Fixed ESC and CTRL-C handling across all dialogs

0.10.3
------

[Section titled “0.10.3”](https://docs.letta.com/letta-code/changelog#0103)

*   Added desktop notifications when UI needs user attention
*   Added read-only shell commands support in plan mode

0.10.2
------

[Section titled “0.10.2”](https://docs.letta.com/letta-code/changelog#0102)

*   Added Ctrl+V support for clipboard image paste in all terminals
*   Fixed keybindings
*   Fixed model name display in welcome screen

0.10.1
------

[Section titled “0.10.1”](https://docs.letta.com/letta-code/changelog#0101)

*   Added Shift+Enter multi-line input support

0.10.0
------

[Section titled “0.10.0”](https://docs.letta.com/letta-code/changelog#0100)

*   Added visual diffs for Edit/Write tool returns
*   Added automatic retry for transient LLM API errors
*   Added custom slash commands support (`/commands`)
*   Added scrolling and manual ordering to command autocomplete
*   Added toggle to show all agents in `/agents` view
*   Added per-resource queues for parallel tool execution
*   Fixed plan mode on non-default toolsets
*   Fixed CLI crash when browser auto-open fails in WSL

0.8.0
-----

[Section titled “0.8.0”](https://docs.letta.com/letta-code/changelog#080)

*   Added GLM-4.7 model support
*   Added `/new` command for creating new agents
*   Added `/feedback` command improvements
*   Added memory reminders to improve memory usage
*   Renamed `/resume` to `/agents` (with backwards-compatible alias)
*   Fixed plan mode path resolution on Windows

0.7.4
-----

[Section titled “0.7.4”](https://docs.letta.com/letta-code/changelog#074)

*   Added support for bundled skills and multi-source skill discovery
*   Increased loaded\_skills block limit to 100k characters

0.7.3
-----

[Section titled “0.7.3”](https://docs.letta.com/letta-code/changelog#073)

*   Added support for Claude Pro and Max plans
*   Added optional telemetry
*   Added `--system` flag for existing agents
*   Fixed Windows-specific issues

0.7.2
-----

[Section titled “0.7.2”](https://docs.letta.com/letta-code/changelog#072)

*   Added `/help` command with interactive dialog
*   Added `/mcp` command for MCP server management
*   Added `/compact` command for message compaction
*   Added text search for all models
*   Improved memory tool visibility with colored name and diff output

0.7.1
-----

[Section titled “0.7.1”](https://docs.letta.com/letta-code/changelog#071)

*   Added BYOK (Bring Your Own Key) support - use your own API keys
*   Added `/usage` command to check usage and credits
*   Added `--info` flag to show project and agent info
*   Added naming dialog when pinning agents

0.7.0
-----

[Section titled “0.7.0”](https://docs.letta.com/letta-code/changelog#070)

*   Added `/memory` command to view agent memory blocks
*   Added ‘add-model’ skill for adding new LLM models
*   Added Gemini 3 Flash model support
*   Added feedback UI

0.6.3
-----

[Section titled “0.6.3”](https://docs.letta.com/letta-code/changelog#063)

*   Added support for relative paths in all tools
*   Added tab completion for slash commands
*   Added Kimi K2 Thinking model
*   Added personalized thinking prompts with agent name
*   Added goodbye message on exit
*   Renamed `/bashes` to `/bg`

0.6.2
-----

[Section titled “0.6.2”](https://docs.letta.com/letta-code/changelog#062)

*   Added stateless subagents via Task tool
*   Added Kimi K2 Thinking model support
*   Improved subagents UI

0.6.1
-----

[Section titled “0.6.1”](https://docs.letta.com/letta-code/changelog#061)

*   Added autocomplete for slash commands
*   Faster startup with cached tool initialization
*   Added `exit` and `quit` as aliases for `/exit`

0.6.0
-----

[Section titled “0.6.0”](https://docs.letta.com/letta-code/changelog#060)

*   Added profile-based persistence with startup selector
*   Added `/profile` command for managing profiles
*   Added simplified welcome screen design
*   Added double Ctrl+C to exit from approval screen
*   Added paginated agent list in `/resume`
*   Added `/description` command to update agent description
*   Added message search

0.5.2
-----

[Section titled “0.5.2”](https://docs.letta.com/letta-code/changelog#052)

*   Added `/resume` command with improved agent selector UI
*   Added `LETTA_DEBUG` environment variable for debug logging
*   Added agent description support
*   Added GPT-5.2 support
*   Added Gemini 3 (Vertex) support

0.5.1
-----

[Section titled “0.5.1”](https://docs.letta.com/letta-code/changelog#051)

*   Added startup status messages showing agent info

0.5.0
-----

[Section titled “0.5.0”](https://docs.letta.com/letta-code/changelog#050)

*   Added `/init` command for initializing memory blocks
*   Added system prompt swapping
*   Changed default naming to PascalCase

0.4.1
-----

[Section titled “0.4.1”](https://docs.letta.com/letta-code/changelog#041)

*   Added `/download` command to export agent file locally
*   Added Skills omni-tool

0.4.0
-----

[Section titled “0.4.0”](https://docs.letta.com/letta-code/changelog#040)

*   Added Claude Opus 4.5 support
*   Added toolset switching UI
*   Added `--toolset` flag
*   Added Gemini tools support
*   Added model-based toolset switching
*   Added eager cancel functionality

0.3.0
-----

[Section titled “0.3.0”](https://docs.letta.com/letta-code/changelog#030)

*   Added sleeptime memory management
*   Added `--sleeptime` CLI flag
*   Added GPT-5.1 models support
*   Added Gemini-3 models support
*   Added `--fresh-blocks` flag for isolation
*   Added `/swap` command for model switching

0.2.0
-----

[Section titled “0.2.0”](https://docs.letta.com/letta-code/changelog#020)

*   Added `/link` and `/unlink` commands for managing agent tools
*   Added Skills support
*   Added parallel tool calling
*   Added multi-device sign in support
*   Added agent renaming capability

0.1.16
------

[Section titled “0.1.16”](https://docs.letta.com/letta-code/changelog#0116)

*   Added Sonnet 4.5 with 180k context window

0.1.15
------

[Section titled “0.1.15”](https://docs.letta.com/letta-code/changelog#0115)

*   Added multiline input support
*   Added `--new` flag for creating new memory blocks
*   Added agent URL display in commands

0.1.11
------

[Section titled “0.1.11”](https://docs.letta.com/letta-code/changelog#0111-1)

*   Added Claude Haiku 4.5 to model selector
*   Added project-level agent persistence with auto-resume
*   Added API key caching
*   Added `--model` flag
*   Added GLM-4.6 support
*   Added autocomplete for commands
*   Added up/down for history navigation
*   Added `fetch_web` to default tool list

0.1.10
------

[Section titled “0.1.10”](https://docs.letta.com/letta-code/changelog#0110-1)

*   Added `stream-json` output format

0.1.9
-----

[Section titled “0.1.9”](https://docs.letta.com/letta-code/changelog#019)

*   Added pretty preview for file listings in approval dialog
*   Added `LETTA_BASE_URL` environment variable support

0.1.8
-----

[Section titled “0.1.8”](https://docs.letta.com/letta-code/changelog#018)

*   Added usage tracking
*   Added ESC to cancel operations
*   Added Ctrl-C exit with agent state dump

0.1.3
-----

[Section titled “0.1.3”](https://docs.letta.com/letta-code/changelog#013)

*   Initial release of Letta Code, the memory-first coding agent

---

# How it works | Letta Docs

[Skip to content](https://docs.letta.com/letta-code/how-it-works#_top)

Reference

[How it works](https://docs.letta.com/letta-code/how-it-works)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

* * *

**Copy Markdown**

**View as Markdown**

How it works
============

Understand how Letta Code is built and how to customize it

Letta Code is a **lightweight CLI harness** built around the [Letta TypeScript SDK](https://github.com/letta-ai/letta-node)
. It gives Letta agents (running on a server, local or remote) the ability to interact with your local development environment.

Architecture overview
---------------------

[Section titled “Architecture overview”](https://docs.letta.com/letta-code/how-it-works#architecture-overview)

flowchart TB
    subgraph Terminal\["Your terminal"\]
        subgraph LettaCode\["Letta Code"\]
            UI\["CLI UI / Headless"\]
            Executor\["Tool Executor"\]
            Permissions\["Permission Manager"\]
            SDK\["Letta TS SDK"\]
        end
    end

    Server\["Letta server"\]

    UI --> SDK
    Executor --> SDK
    Permissions --> SDK
    SDK <-->|Letta API| Server

Letta Code’s main job is to:

1.  **Manage the messaging lifecycle** - Send message between the user and agent
2.  **Execute tools locally** - Run Bash, Read, Write, Edit, etc. on your machine
3.  **Handle permissions** - Prompt the user for approval before tool execution
4.  **Provide a terminal UI** - Render agent state, streaming responses and tool calls

Client-side tool execution
--------------------------

[Section titled “Client-side tool execution”](https://docs.letta.com/letta-code/how-it-works#client-side-tool-execution)

The core mechanism that makes Letta Code work is **client-side tool execution**. Your Letta agent runs on an external server, but the tools it calls - like `Bash`, `Read`, and `Write` - execute locally on your machine.

This is done using the [client-side tools](https://docs.letta.com/guides/core-concepts/tools/client-tools)
 feature of the Letta API:

1.  **Agent requests a tool** - The agent decides to call `Bash(ls -la)`
2.  **Server pauses agent execution for approval** - The request is sent to your terminal
3.  **Letta Code executes locally** - The command runs on your machine
4.  **Result sent back** - Output is returned to the agent to continue

    // Simplified: How Letta Code handles tool executionconst response = await client.agents.messages.create(agentId, {  messages: [{ role: "user", content: userInput }],});
    for (const msg of response.messages) {  if (msg.message_type === "approval_request_message") {    // Execute the tool locally    const result = await executeToolLocally(msg.tool_call);
        // Send the result back to the agent    await client.agents.messages.create(agentId, {      messages: [{        type: "approval",        approvals: [{          type: "tool",          tool_call_id: msg.tool_call.tool_call_id,          tool_return: result,          status: "success",        }],      }],    });  }}

Streaming
---------

[Section titled “Streaming”](https://docs.letta.com/letta-code/how-it-works#streaming)

Letta Code uses the SDK’s [streaming API](https://docs.letta.com/guides/core-concepts/messages/streaming)
 to display reasoning, messages, and tool calls in real-time.

    const stream = await client.agents.messages.stream(agentId, {  messages: [{ role: "user", content: userInput }],  stream_tokens: true,});
    for await (const chunk of stream) {  if (chunk.message_type === "reasoning_message") {    process.stdout.write(chunk.reasoning);  } else if (chunk.message_type === "assistant_message") {    process.stdout.write(chunk.content);  }}

Background mode streaming
-------------------------

[Section titled “Background mode streaming”](https://docs.letta.com/letta-code/how-it-works#background-mode-streaming)

Because coding agents are often long-running, Letta Code uses [background mode streaming](https://docs.letta.com/guides/core-concepts/messages/long-running-executions)
. This decouples agent execution from the client connection, allowing:

*   **Resumable streams** - If your connection drops, you can reconnect and resume from where you left off
*   **Crash recovery** - The agent continues processing on the server even if your terminal closes
*   **Long operations** - Tasks that take 10+ minutes won’t timeout

    // Background mode persists the stream server-sideconst stream = await client.agents.messages.stream(agentId, {  messages: [{ role: "user", content: userInput }],  stream_tokens: true,  background: true, // Enable background mode});
    // Each chunk includes run_id and seq_id for resumptionlet runId, lastSeqId;for await (const chunk of stream) {  if (chunk.run_id && chunk.seq_id) {    runId = chunk.run_id;    lastSeqId = chunk.seq_id;  }  // Process chunk...}
    // If disconnected, resume from last positionfor await (const chunk of client.runs.stream(runId, {  starting_after: lastSeqId,})) {  // Continue processing...}

Conversations
-------------

[Section titled “Conversations”](https://docs.letta.com/letta-code/how-it-works#conversations)

Letta Code organizes message threads into **conversations**. A single agent can have multiple conversations running in parallel—all sharing the same memory blocks and searchable message history.

This lets you run several coding sessions simultaneously (one refactoring your API, another writing tests) with separate context windows but shared knowledge. Messages from all conversations are pooled together and searchable, so your agent can recall context from any past session.

By default, starting `letta` resumes the default conversation with your last-used agent in the current project. Use `--new` to start a fresh conversation for parallel sessions, `--resume` to browse past conversations interactively, `--conversation <id>` to reopen a specific thread, or `/resume` during a session to switch conversations.

Your Letta Code agents are general Letta agents
-----------------------------------------------

[Section titled “Your Letta Code agents are general Letta agents”](https://docs.letta.com/letta-code/how-it-works#your-letta-code-agents-are-general-letta-agents)

An important point: **agents created by Letta Code are general-purpose Letta agents**. This means they’re fully accessible through:

*   **The Letta API** - Use the [Python](https://github.com/letta-ai/letta-python)
     and [TypeScript](https://github.com/letta-ai/letta-node)
     SDKs or any REST endpoint to modify/access/message them
*   **The ADE** - View and interact at [app.letta.com](https://app.letta.com/)
    
*   **Other clients** - Build your own interfaces on top of the Letta API (e.g. using [Vercel AI SDK](https://ai-sdk.dev/providers/community-providers/letta)
    )

Letta Code simply attaches a set of coding-focused tools and prompts to your agents, and provides a terminal interface for interacting with them. The agents themselves, including their memory and conversation history, live on the Letta server.

This means you can:

*   Start a session in Letta Code, then continue in the ADE
*   Use the API to programmatically interact with your coding agent
*   Build custom UIs (e.g. dashboards) to view your Letta Code agent, even when you’re not at your terminal

---

# Attaching and detaching memory blocks | Letta Docs

[Skip to content](https://docs.letta.com/tutorials/attaching-detaching-blocks#_top)

Attaching and detaching memory blocks
=====================================

Dynamically attach and detach memory blocks to control what information agents can access during runtime.

Overview
--------

[Section titled “Overview”](https://docs.letta.com/tutorials/attaching-detaching-blocks#overview)

Memory blocks are structured sections of an agent’s context window that persist across all interactions. They’re always visible to the agent while they are attached. This makes them perfect for storing information that agents need constant access to, like organizational policies, user preferences, or working memory.

One of the most powerful features of memory blocks is that they can be created independently and attached to or detached from agents at any time.

This allows you to:

*   **Dynamically control** what information an agent has access to
*   **Share memory** across multiple agents by attaching the same block to different agents
*   **Temporarily grant access** to sensitive information, then revoke it when no longer needed
*   **Switch contexts** by swapping out blocks as an agent moves between different tasks

By the end of this guide, you’ll understand how to create standalone memory blocks, attach them to agents, detach them to remove access, and re-attach them when needed.

What You’ll Learn
-----------------

[Section titled “What You’ll Learn”](https://docs.letta.com/tutorials/attaching-detaching-blocks#what-youll-learn)

*   Creating standalone memory blocks
*   Attaching blocks to agents
*   Testing agent access to attached blocks
*   Detaching blocks to revoke access
*   Re-attaching blocks to restore access

Prerequisites
-------------

[Section titled “Prerequisites”](https://docs.letta.com/tutorials/attaching-detaching-blocks#prerequisites)

You will need to install `letta-client` to interface with a Letta server:

*   [TypeScript](https://docs.letta.com/tutorials/attaching-detaching-blocks#tab-panel-260)
    
*   [Python](https://docs.letta.com/tutorials/attaching-detaching-blocks#tab-panel-261)
    

    npm install @letta-ai/letta-client

    pip install letta-client

Steps
-----

[Section titled “Steps”](https://docs.letta.com/tutorials/attaching-detaching-blocks#steps)

### Step 1: Initialize Client and Create Agent

[Section titled “Step 1: Initialize Client and Create Agent”](https://docs.letta.com/tutorials/attaching-detaching-blocks#step-1-initialize-client-and-create-agent)

*   [TypeScript](https://docs.letta.com/tutorials/attaching-detaching-blocks#tab-panel-266)
    
*   [Python](https://docs.letta.com/tutorials/attaching-detaching-blocks#tab-panel-267)
    

    import Letta from "@letta-ai/letta-client";
    // Initialize the Letta client using LETTA_API_KEY environment variableconst client = new Letta({ apiKey: process.env.LETTA_API_KEY });
    // If self-hosting, specify the base URL:// const client = new Letta({ baseURL: "http://localhost:8283" });
    // Create agent// API Reference: https://docs.letta.com/api-reference/agents/createconst agent = await client.agents.create({  name: "hello_world_assistant",  model: "openai/gpt-4o-mini",  // embedding: "openai/text-embedding-3-small", // Only set this if self-hosting});
    console.log(`Created agent: ${agent.id}\n`);

    from letta_client import Lettaimport os
    # Initialize the Letta client using LETTA_API_KEY environment variableclient = Letta(api_key=os.getenv("LETTA_API_KEY"))
    # If self-hosting, specify the base URL:# client = Letta(base_url="http://localhost:8283")
    # Create agent# API Reference: https://docs.letta.com/api-reference/agents/createagent = client.agents.create(    name="hello_world_assistant",    model="openai/gpt-4o-mini",    # embedding="openai/text-embedding-3-small", # Only set this if self-hosting)
    print(f"Created agent: {agent.id}\n")

Expected Output

`Created agent: agent-a1b2c3d4-e5f6-7890-abcd-ef1234567890`

### Step 2: Create a Standalone Memory Block

[Section titled “Step 2: Create a Standalone Memory Block”](https://docs.letta.com/tutorials/attaching-detaching-blocks#step-2-create-a-standalone-memory-block)

Memory blocks can be created independently of any agent. This allows you to share the same block across multiple agents or attach/detach blocks as needed.

In this example, we’ll create a standalone memory block storing information about Letta. We’ll include a code that you can use to get the agent to respond to indicate that it has access to information in the block.

When the block is attached, writing “The code is TimberTheDog1234!” will cause the agent to respond with “Access granted”. If the block is not attached, the agent will not have access to any content in the block and will likely be confused by the code.

*   [TypeScript](https://docs.letta.com/tutorials/attaching-detaching-blocks#tab-panel-268)
    
*   [Python](https://docs.letta.com/tutorials/attaching-detaching-blocks#tab-panel-269)
    

    // Create memory block storing information about Letta// API Reference: https://docs.letta.com/api-reference/blocks/createconst block = await client.blocks.create({  label: "organization",  value: `Organization: LettaWebsite: https://www.letta.comDescription: Letta is a platform for building and running stateful agents.Code: TimberTheDog1234!
    When users provide a code, you should check if it matches the code you haveavailable. If it matches, you should respond with "Access granted".`,});
    console.log(`Created block: ${block.id}\n`);

    # Create memory block storing information about Letta# API Reference: https://docs.letta.com/api-reference/blocks/createblock = client.blocks.create(    label="organization",    value="""Organization: LettaWebsite: https://www.letta.comDescription: Letta is a platform for building and running stateful agents.Code: TimberTheDog1234!
    When users provide a code, you should check if it matches the code you haveavailable. If it matches, you should respond with "Access granted".""",)
    print(f"Created block: {block.id}\n")

Expected Output

`Created block: block-a1b2c3d4-e5f6-7890-abcd-ef1234567890`

### Step 3: Attach Block to Agent

[Section titled “Step 3: Attach Block to Agent”](https://docs.letta.com/tutorials/attaching-detaching-blocks#step-3-attach-block-to-agent)

Now let’s attach the block to our agent. Attached blocks are injected into the agent’s context window and are available to the agent to use in its responses.

*   [TypeScript](https://docs.letta.com/tutorials/attaching-detaching-blocks#tab-panel-262)
    
*   [Python](https://docs.letta.com/tutorials/attaching-detaching-blocks#tab-panel-263)
    

    // Attach memory block to agent// API Reference: https://docs.letta.com/api-reference/agents/blocks/attachawait client.agents.blocks.attach(agent.id, block.id);
    console.log(`Attached block ${block.id} to agent ${agent.id}\n`);

    # Attach memory block to agent# API Reference: https://docs.letta.com/api-reference/agents/blocks/attachagent = client.agents.blocks.attach(    agent_id=agent.id,    block_id=block.id,)
    print(f"Attached block {block.id} to agent {agent.id}\n")

### Step 4: Test Agent Access to Block

[Section titled “Step 4: Test Agent Access to Block”](https://docs.letta.com/tutorials/attaching-detaching-blocks#step-4-test-agent-access-to-block)

The agent can now see what’s in the block. Let’s ask it about Letta to verify that it can see the general information in the block — the description, website, and organization name.

*   [TypeScript](https://docs.letta.com/tutorials/attaching-detaching-blocks#tab-panel-270)
    
*   [Python](https://docs.letta.com/tutorials/attaching-detaching-blocks#tab-panel-271)
    

    // Send a message to test the agent's knowledge// API Reference: https://docs.letta.com/api-reference/agents/messages/createconst response = await client.agents.messages.create(agent.id, {  messages: [{ role: "user", content: "What is Letta?" }],});
    for (const msg of response.messages) {  if (msg.message_type === "assistant_message") {    console.log(`Agent response: ${msg.content}\n`);  }}

    # Send a message to test the agent's knowledge# API Reference: https://docs.letta.com/api-reference/agents/messages/createresponse = client.agents.messages.create(    agent_id=agent.id,    messages=[{"role": "user", "content": "What is Letta?"}],)
    for msg in response.messages:    if msg.message_type == "assistant_message":        print(f"Agent response: {msg.content}\n")

The agent will respond with general information about Letta:

> **Agent response**: Letta is a platform designed for building and running stateful agents. You can find more information about it on their website: [https://www.letta.com](https://www.letta.com/)

### Step 5: Detach Block from Agent

[Section titled “Step 5: Detach Block from Agent”](https://docs.letta.com/tutorials/attaching-detaching-blocks#step-5-detach-block-from-agent)

Blocks can be detached from an agent, removing them from the agent’s context window. Detached blocks are not deleted and can be re-attached to an agent later.

*   [TypeScript](https://docs.letta.com/tutorials/attaching-detaching-blocks#tab-panel-264)
    
*   [Python](https://docs.letta.com/tutorials/attaching-detaching-blocks#tab-panel-265)
    

    // Detach the block from the agent// API Reference: https://docs.letta.com/api-reference/agents/blocks/detachawait client.agents.blocks.detach(agent.id, block.id);
    console.log(`Detached block ${block.id} from agent ${agent.id}\n`);

    # Detach the block from the agent# API Reference: https://docs.letta.com/api-reference/agents/blocks/detachagent = client.agents.blocks.detach(    agent_id=agent.id,    block_id=block.id,)
    print(f"Detached block {block.id} from agent {agent.id}\n")

### Step 6: Verify Block is Detached

[Section titled “Step 6: Verify Block is Detached”](https://docs.letta.com/tutorials/attaching-detaching-blocks#step-6-verify-block-is-detached)

Let’s test the code that was in the block. The agent should no longer have access to it.

*   [TypeScript](https://docs.letta.com/tutorials/attaching-detaching-blocks#tab-panel-272)
    
*   [Python](https://docs.letta.com/tutorials/attaching-detaching-blocks#tab-panel-273)
    

    // Test that the agent no longer has access to the codeconst response2 = await client.agents.messages.create(agent.id, {  messages: [{ role: "user", content: "The code is TimberTheDog1234!" }],});
    for (const msg of response2.messages) {  if (msg.message_type === "assistant_message") {    console.log(`Agent response: ${msg.content}\n`);  }}

    # Test that the agent no longer has access to the coderesponse = client.agents.messages.create(    agent_id=agent.id,    messages=[{"role": "user", "content": "The code is TimberTheDog1234!"}],)
    for msg in response.messages:    if msg.message_type == "assistant_message":        print(f"Agent response: {msg.content}\n")

Expected Output

    Agent response: It seems like you've provided a code or password. If thisis sensitive information, please ensure you only share it with trusted partiesand in secure environments. Let me know how I can assist you further!

### Step 7: Re-attach Block and Test Again

[Section titled “Step 7: Re-attach Block and Test Again”](https://docs.letta.com/tutorials/attaching-detaching-blocks#step-7-re-attach-block-and-test-again)

Let’s re-attach the block to restore the agent’s access to the information.

*   [TypeScript](https://docs.letta.com/tutorials/attaching-detaching-blocks#tab-panel-274)
    
*   [Python](https://docs.letta.com/tutorials/attaching-detaching-blocks#tab-panel-275)
    

    // Re-attach the block to the agentawait client.agents.blocks.attach(agent.id, block.id);
    console.log(`Re-attached block ${block.id} to agent ${agent.id}\n`);
    // Test the code againconst response3 = await client.agents.messages.create(agent.id, {  messages: [{ role: "user", content: "The code is TimberTheDog1234!" }],});
    for (const msg of response3.messages) {  if (msg.message_type === "assistant_message") {    console.log(`Agent response: ${msg.content}\n`);  }}

    # Re-attach the block to the agentagent = client.agents.blocks.attach(    agent_id=agent.id,    block_id=block.id,)
    print(f"Re-attached block {block.id} to agent {agent.id}\n")
    # Test the code againresponse = client.agents.messages.create(    agent_id=agent.id,    messages=[{"role": "user", "content": "The code is TimberTheDog1234!"}],)
    for msg in response.messages:    if msg.message_type == "assistant_message":        print(f"Agent response: {msg.content}\n")

Expected Output

`Agent response: Access granted. How can I assist you further?`

Complete Example
----------------

[Section titled “Complete Example”](https://docs.letta.com/tutorials/attaching-detaching-blocks#complete-example)

Here’s the full code in one place that you can run:

*   [TypeScript](https://docs.letta.com/tutorials/attaching-detaching-blocks#tab-panel-276)
    
*   [Python](https://docs.letta.com/tutorials/attaching-detaching-blocks#tab-panel-277)
    

    import Letta from "@letta-ai/letta-client";
    async function main() {  // Initialize client  const client = new Letta({ apiKey: process.env.LETTA_API_KEY });
      // Create agent  const agent = await client.agents.create({    name: "hello_world_assistant",    model: "openai/gpt-4o-mini",  });
      console.log(`Created agent: ${agent.id}\n`);
      // Create standalone memory block  const block = await client.blocks.create({    label: "organization",    value: `Organization: Letta
    Website: https://www.letta.comDescription: Letta is a platform for building and running stateful agents.Code: TimberTheDog1234!
    When users provide a code, you should check if it matches the code you haveavailable. If it matches, you should respond with "Access granted".`,  });
      console.log(`Created block: ${block.id}\n`);
      // Attach block to agent  await client.agents.blocks.attach(agent.id, block.id);  console.log(`Attached block to agent\n`);
      // Test agent with block attached  let response = await client.agents.messages.create(agent.id, {    messages: [{ role: "user", content: "What is Letta?" }],  });  console.log(`Agent response: ${response.messages[0].content}\n`);
      // Detach block  await client.agents.blocks.detach(agent.id, block.id);  console.log(`Detached block from agent\n`);
      // Test agent without block  response = await client.agents.messages.create(agent.id, {    messages: [{ role: "user", content: "The code is TimberTheDog1234!" }],  });  console.log(`Agent response: ${response.messages[0].content}\n`);
      // Re-attach block  await client.agents.blocks.attach(agent.id, block.id);  console.log(`Re-attached block to agent\n`);
      // Test agent with block re-attached  response = await client.agents.messages.create(agent.id, {    messages: [{ role: "user", content: "The code is TimberTheDog1234!" }],  });  console.log(`Agent response: ${response.messages[0].content}\n`);}
    main();

    from letta_client import Lettaimport os
    # Initialize clientclient = Letta(api_key=os.getenv("LETTA_API_KEY"))
    # Create agentagent = client.agents.create(    name="hello_world_assistant",    model="openai/gpt-4o-mini",)
    print(f"Created agent: {agent.id}\n")
    # Create standalone memory blockblock = client.blocks.create(    label="organization",    value="""Organization: LettaWebsite: https://www.letta.comDescription: Letta is a platform for building and running stateful agents.Code: TimberTheDog1234!
    When users provide a code, you should check if it matches the code you haveavailable. If it matches, you should respond with "Access granted".""",)
    print(f"Created block: {block.id}\n")
    # Attach block to agentagent = client.agents.blocks.attach(    agent_id=agent.id,    block_id=block.id,)print(f"Attached block to agent\n")
    # Test agent with block attachedresponse = client.agents.messages.create(    agent_id=agent.id,    messages=[{"role": "user", "content": "What is Letta?"}],)print(f"Agent response: {response.messages[0].content}\n")
    # Detach blockagent = client.agents.blocks.detach(    agent_id=agent.id,    block_id=block.id,)print(f"Detached block from agent\n")
    # Test agent without blockresponse = client.agents.messages.create(    agent_id=agent.id,    messages=[{"role": "user", "content": "The code is TimberTheDog1234!"}],)print(f"Agent response: {response.messages[0].content}\n")
    # Re-attach blockagent = client.agents.blocks.attach(    agent_id=agent.id,    block_id=block.id,)print(f"Re-attached block to agent\n")
    # Test agent with block re-attachedresponse = client.agents.messages.create(    agent_id=agent.id,    messages=[{"role": "user", "content": "The code is TimberTheDog1234!"}],)print(f"Agent response: {response.messages[0].content}\n")

Key Concepts
------------

[Section titled “Key Concepts”](https://docs.letta.com/tutorials/attaching-detaching-blocks#key-concepts)

Standalone Blocks

Memory blocks can be created independently and shared across multiple agents

Dynamic Access Control

Attach and detach blocks to control what information an agent can access

Block Persistence

Detached blocks are not deleted and can be re-attached at any time

Shared Memory

The same block can be attached to multiple agents, enabling shared knowledge

Use Cases
---------

[Section titled “Use Cases”](https://docs.letta.com/tutorials/attaching-detaching-blocks#use-cases)

Temporary Access to Sensitive Information

Attach a block with credentials or sensitive data only when needed, then detach it to prevent unauthorized access.

Shared Knowledge Across Agents

Create a single block with organizational knowledge and attach it to multiple agents to ensure consistency.

Context Switching

Detach blocks related to one task and attach blocks for another, allowing an agent to switch contexts efficiently.

Role-Based Access

Give different agents access to different blocks based on their roles or permissions.

Next Steps
----------

[Section titled “Next Steps”](https://docs.letta.com/tutorials/attaching-detaching-blocks#next-steps)

Memory Blocks Guide

Learn more about memory blocks, including how to update them and manage their lifecycle

---

# Building customer-specific relationship agents with Letta | Letta Docs

[Skip to content](https://docs.letta.com/tutorials/customer-specific-agents#_top)

Building customer-specific relationship agents with Letta
=========================================================

Create dedicated agents for each customer using templates, persistent memory, and personalized communication tools.

Companies generally have customer success agents that handle dozens or even hundreds of accounts. This is a natural pattern to follow when building out AI-based agents too.

But what if each of your customers had their own dedicated customer success agent?

This guide shows you how to get started with customer-specific agents in Letta. Instead of generic chatbots, you’ll create persistent agents with dedicated memory for each customer that can research their background and send personalized communications.

As a demo, we’ll build a customer success agent template where each new customer gets their own dedicated agent, created from the template, that researches their background, updates its memory, and sends personalized welcome emails.

Prerequisites
-------------

[Section titled “Prerequisites”](https://docs.letta.com/tutorials/customer-specific-agents#prerequisites)

To follow along, you need free accounts for the following platforms:

*   **[Letta](https://www.letta.com/)
    :** To access the agent development platform
*   **[Gmail](https://gmail.com/)
    :** To configure the agent’s email sending capability
*   **[Zapier MCP](https://mcp.zapier.com/mcp)
    :** To set up the MCP email tool integration
*   **[Exa](https://exa.ai/)
    :** To configure MCP research and LinkedIn lookup tools

Step 1: Create an agent template
--------------------------------

[Section titled “Step 1: Create an agent template”](https://docs.letta.com/tutorials/customer-specific-agents#step-1-create-an-agent-template)

Agent templates serve as blueprints that define your agent’s memory structure, tools, and behavior patterns. From the Letta dashboard, click **Templates** → **\+ New template** → **Start from scratch**.

![Creating a new agent template in the Letta dashboard](https://docs.letta.com/images/add-template.png)

This launches the Agent Development Environment (ADE) with three key areas: a center chat simulator for testing, a left sidebar for configuration (template settings, tools, LLM config), and a right panel showing memory architecture with real-time context utilization.

![Agent Development Environment interface showing chat simulator, configuration sidebar, and memory blocks panel](https://docs.letta.com/images/agent-development-environment.png)

Rename your template `customer-success-agent` by clicking the **pen icon** next to the **Name** field.

![Editing agent template name in the ADE](https://docs.letta.com/images/name-template.png)

Step 2: Set up memory blocks
----------------------------

[Section titled “Step 2: Set up memory blocks”](https://docs.letta.com/tutorials/customer-specific-agents#step-2-set-up-memory-blocks)

Memory blocks create your agent’s persistent knowledge architecture. In the ADE’s right panel, in the **Core Memory** section, click **Advanced** → **\+ New block** to add custom memory blocks.

![Adding custom memory blocks in Core Memory section](https://docs.letta.com/images/add-custom-memory-block.png)

Create four core memory blocks with the following configurations:

Customer block: Customer profile and context

1.  **Label**
    
    `customer`
    
2.  **Description**
    
        Detailed information about the customer contact including professional background, role, and business context
    
3.  **Value**
    
        Customer Profile:Name: {{customer_name}}Email: {{customer_email}}Company: {{company_name}}Title: {{job_title}}Industry: {{industry_sector}}
        Professional Background:{{professional_background}}
        Business Challenges:{{business_challenges}}
        Communication Preferences:{{communication_preferences}}
    

Organization block: Company knowledge base

1.  **Label**
    
    `organization`
    
2.  **Description**
    
        ACME Manufacturing's company information, products, and value propositions for reference
    
3.  **Read-only**
    
    Yes
    
4.  **Value**
    
        ACME Manufacturing - Industrial Automation Solutions
        Key Products:• QualityCheck AI: Real-time quality control system (reduces defects by 30%)• SupplyOptimize: Supply chain optimization platform (20% cost savings)• ProductionFlow: Manufacturing workflow automation
        Target Industries: Automotive, Aerospace, Electronics, Medical DevicesCompany Size Focus: 100-1000 employees
        Value Propositions:- Reduce manufacturing defects by 25-40%- Optimize supply chain costs by 15-25%- Improve production efficiency by 20-35%- Seamless ERP integration
        Competitive Advantages:- Industry-specific AI models trained on manufacturing data- 99.7% uptime SLA with 24/7 support- ROI typically achieved within 6 months
        Contact Information:- Representative: [Your Name]- Title: [Your Title]
    

Tool use guidelines block: Research and communication guidelines

1.  **Label**
    
    `tool_use_guidelines`
    
2.  **Description**
    
        Instructions for effective tool usage and customer research methodology
    
3.  **Read-only**
    
    Yes
    
4.  **Value**
    
        Research Strategy:1. Begin with LinkedIn research to understand the contact's professional background2. Use web search to research the customer's company, recent news, and industry challenges3. Focus on identifying specific use cases for ACME Manufacturing's solutions4. Look for relevant business triggers (growth, challenges, new initiatives)
        Communication Guidelines:- Personalize emails based on research findings- Reference specific company challenges or industry trends- Connect ACME products to customer's likely pain points- Maintain professional but approachable tone- Include relevant case studies or statistics when appropriate
        Tool Usage Best Practices:- Use company_research_exa for comprehensive business intelligence- Use linkedin_search_exa for professional background verification- Draft emails with research context before sending- Update memory blocks with key findings after each research session
    

Tasks block: Action items and objectives

1.  **Label**
    
    `tasks`
    
2.  **Description**
    
        Current objectives, action items, and next steps for this customer relationship
    
3.  **Value**
    
        Current Priorities:1. Complete customer and company research2. Identify specific use cases for ACME products3. Draft personalized welcome email4. Schedule discovery call5. Prepare customized demo materials
        Research Checklist:- [] LinkedIn professional background research- [] Company website and recent news analysis- [] Industry-specific challenge identification- [] Competitive landscape assessment
    

The `customer` memory block stores everything your agent learns about the individual customer contact. Template variables are populated when creating agents from this template, while research findings accumulate in descriptive fields.

The `organization` memory block contains static company information that agents reference but shouldn’t modify. Set as read-only to ensure consistent messaging across all customer interactions.

The `tool_use_guidelines` memory block contains instructions for how your agent should use its research and communication tools effectively.

The `tasks` memory block contains specific customer onboarding tasks like research, email drafting, and discovery call scheduling with a checklist to track completion.

### Troubleshooting tool failures

[Section titled “Troubleshooting tool failures”](https://docs.letta.com/tutorials/customer-specific-agents#troubleshooting-tool-failures)

When testing your agent, you may encounter tool call failures. These issues are common across all MCP tools and can usually be resolved quickly with the right approach.

Rate limiting errors

**Problem**: Tools return “too many requests” or “rate limit exceeded” messages

**Solution**: Wait 1-2 minutes before retrying, or break large queries into smaller requests

Authentication failures

**Problem**: Tools fail with “unauthorized” or “invalid credentials” errors

**Solution**: Check your MCP server connections in **Tool Manager** and reconnect your accounts. For Gmail tools, ensure your Gmail account is properly connected in Zapier

Network timeouts

**Problem**: Tools hang or timeout without returning results

**Solution**: Retry the request or simplify your query parameters

Invalid queries

**Problem**: Tools return no results or “invalid format” errors

**Solution**: Rephrase search terms using simpler, more specific language

Tool unavailable

**Problem**: Agent says it cannot access required tools

**Solution**: Verify tools are properly attached to your agent in the Tool Manager

API key issues

**Problem**: Tools fail immediately with connection errors

**Solution**: Verify your API keys are valid and haven’t expired. For Exa tools, check your API key at [dashboard.exa.ai/api-keys](https://dashboard.exa.ai/api-keys)
. For Zapier tools, verify your server URL in the Zapier dashboard

### Template variables

[Section titled “Template variables”](https://docs.letta.com/tutorials/customer-specific-agents#template-variables)

The `{{variable_name}}` placeholders in `customer` memory blocks are populated with actual customer data when you create agents from the template and they start interacting with your customers.

Step 3: Configure MCP tools for customer research
-------------------------------------------------

[Section titled “Step 3: Configure MCP tools for customer research”](https://docs.letta.com/tutorials/customer-specific-agents#step-3-configure-mcp-tools-for-customer-research)

Tools transform your agent from a static responder into an active researcher. In the ADE’s left sidebar, click **Tools** → **Tool Manager**. This opens a modal where you’ll configure Model Context Protocol (MCP) servers that provide external capabilities.

![Tool manager modal showing MCP server configuration options](https://docs.letta.com/images/mcp-options.png)

Your agent needs research, communication, email drafting, and email sending tools to gather customer intelligence and send personalized emails.

### Adding Exa for research tools

[Section titled “Adding Exa for research tools”](https://docs.letta.com/tutorials/customer-specific-agents#adding-exa-for-research-tools)

Exa provides web search, company research, and LinkedIn lookup capabilities for your agent.

The complete Exa setup process

1.  **Add the Exa MCP server**
    
    In the **Tool manager** sidebar, click **\+ Add MCP server** in the **MCP servers** section. Select **Exa** from the list to open the configuration modal.
    
2.  **Get an Exa API key**
    
    Go to [exa.ai](https://exa.ai/)
     to create an account. Then visit [dashboard.exa.ai/api-keys](https://dashboard.exa.ai/api-keys)
     to copy your default secret key.
    
    ![Exa API key configuration in dashboard](https://docs.letta.com/images/exa-api.png)
3.  **Configure and test the connection**
    
    Paste the [Exa MCP server URL](https://docs.exa.ai/reference/exa-mcp#remote-exa-mcp)
     `https://mcp.exa.ai/mcp?exaApiKey=your-exa-api-key` in the Server URL field on the modal. Replace `your-exa-api-key` with your Exa secret key and click **Test connection**. When connected, the modal displays a list of available tools, including `web_search_exa`, `company_research_exa`, and `linkedin_search_exa`. Click **Confirm** to add the server.
    
    ![Available Exa tools after successful connection](https://docs.letta.com/images/exa-tools.png)

### Adding Zapier for email tools

[Section titled “Adding Zapier for email tools”](https://docs.letta.com/tutorials/customer-specific-agents#adding-zapier-for-email-tools)

Zapier provides Gmail integration for drafting and sending personalized emails.

The complete Zapier setup process

1.  **Add the Zapier MCP server**
    
    Click **\+ Add MCP server** again and select **Zapier**. For the API setup, go to [mcp.zapier.com/mcp](https://mcp.zapier.com/mcp)
    , create an account, then click **\+ New MCP Server** in your Zapier dashboard.
    
    ![Creating new MCP server in Zapier dashboard](https://docs.letta.com/images/zap-new-mcp.png)
2.  **Configure the MCP server**
    
    Choose **Other** from the **MCP Client** options and name it `Email sender`. After creating the server, click **\+ Add tool**, select **Gmail** from the modal, and add the Gmail tools. Connect your Gmail account for sending emails.
    
    ![Adding Gmail tools in Zapier MCP server](https://docs.letta.com/images/gmail-tools.png)
3.  **Get the server URL**
    
    In your Zapier dashboard, click **Connect** in the top toolbar and copy the **Server URL**.
    
    ![Copying server URL from Zapier dashboard](https://docs.letta.com/images/zap-server-url.png)
4.  **Connect to Letta**
    
    Return to the Letta modal, paste the server URL in the Server URL field, and test the connection. When you see the Gmail tools appear, click **Confirm**.
    
    ![Gmail tools successfully connected in Letta](https://docs.letta.com/images/gmail-tools-connected.png)

### Connecting tools to your agent

[Section titled “Connecting tools to your agent”](https://docs.letta.com/tutorials/customer-specific-agents#connecting-tools-to-your-agent)

In the **Tool manager** view, you can now see both MCP servers. Click each server to view the available tools. To attach them, click the **link icon** next to the tools your agent needs:

![Attaching tools to agent in Tool Manager](https://docs.letta.com/images/attach-tool.png)

**From Exa**: Attach `web_search_exa`, `company_research_exa`, and `linkedin_search_exa`.

**From Zapier**: Attach `gmail_create_draft` and `gmail_send_email`.

Step 4: Save your template
--------------------------

[Section titled “Step 4: Save your template”](https://docs.letta.com/tutorials/customer-specific-agents#step-4-save-your-template)

Once you’ve configured all memory blocks and tools, click the **Save** button in the ADE toolbar. This opens a version modal. Click **Save new version** to save your template for agent creation.

Your `customer-success-agent` template is now ready to create customer-specific agents.

Step 5: Create a customer identity
----------------------------------

[Section titled “Step 5: Create a customer identity”](https://docs.letta.com/tutorials/customer-specific-agents#step-5-create-a-customer-identity)

Before creating agents from your template, you need to set up customer identities. An identity is the customer contact record that represents a unique user and can be associated with one or more agents. An agent is the AI system created for that identity.

This identity-agent relationship enables multi-user applications where each customer gets their own dedicated agent while maintaining proper user isolation and tracking. In a real-world scenario, each new customer that signs up has their identity created (either manually or via API integration). For this demo, you’ll create an identity for yourself to test the complete workflow.

Navigate back to the main Letta dashboard and click **Identities** in the left sidebar, then click **\+ Create identity**.

In the modal that opens, configure your customer identity using the three fields:

*   **Name**: Enter your own full name (for example, `[Your Full Name]`).
*   **Identity Type**: Select **User** for individual customer contacts.
*   **Unique Identifier**: Create a unique string to identify this customer in your system (for example, `customer_[your_name]`).

Click **Confirm** when all fields are populated.

![Creating customer identity with name, type, and unique identifier](https://docs.letta.com/images/create-identity.png)

Step 6: Create an agent from the template
-----------------------------------------

[Section titled “Step 6: Create an agent from the template”](https://docs.letta.com/tutorials/customer-specific-agents#step-6-create-an-agent-from-the-template)

With your template and customer identity ready, navigate to **Agents** in the sidebar and click **\+ Create a new agent**.

In the modal, locate the **Create an agent from existing template** section and click on your `customer-success-agent` template.

Fill in your own customer details for testing:

![Modal showing template variables to fill in when creating agent from template](https://docs.letta.com/images/template-variables-modal.png)

Click **\+ Create Agent**. Letta creates the agent and opens the ADE for your new agent instance.

You can see the agent name in the top-left corner of the ADE (for example, **customer-success-agent:1 / random-generated-name**).

![New agent created from template showing inherited memory blocks and tools](https://docs.letta.com/images/agent-from-template.png)

### Assigning the identity

[Section titled “Assigning the identity”](https://docs.letta.com/tutorials/customer-specific-agents#assigning-the-identity)

In the ADE’s left sidebar, click the **profile icon** next to the first field in the **Identities** section. Search for your customer identity by name, select it, then click **Update identities** to assign it to the agent.

![Assigning customer identity to agent in Edit Identities section](https://docs.letta.com/images/assign-identities.png)

Step 7: Test the agent
----------------------

[Section titled “Step 7: Test the agent”](https://docs.letta.com/tutorials/customer-specific-agents#step-7-test-the-agent)

Once you’ve set up your agent, test the complete workflow with a customer research prompt.

In the ADE chat interface, enter the following:

    Hi! Your new customer [Customer Name] ([email@example.com]) just signed up for our trial. They could benefit from our industrial automation solutions, and they're likely evaluating our platform for potential implementation.
    Please research their professional background using LinkedIn and research their company to understand their business and potential needs for ACME Manufacturing's automation solutions. Update your memory blocks with your findings, then draft and send a personalized welcome email that references their background and suggests relevant ACME solutions.
    Complete the full workflow: research, memory updates, email draft, and email sending. Provide a summary of your research findings and confirm when the email has been sent.

The agent will execute the workflow by using its research tools, updating memory blocks with findings, and sending a personalized welcome email. You can observe the process in real time and review the generated email output to ensure quality and personalization. Check your email inbox to see the final personalized message the agent created and sent.

What’s next?
------------

[Section titled “What’s next?”](https://docs.letta.com/tutorials/customer-specific-agents#whats-next)

You’ve built a customer-specific agent system that handles initial onboarding and welcome emails. Here are two key ways to expand this foundation:

Forward customer emails to agents using Zapier integration

Set up automatic email forwarding so your agents can handle ongoing customer communications beyond the initial welcome. When customers reply to emails or send new messages, Zapier can route them to their dedicated agents, allowing the agents to update their memory with new information, draft contextual responses based on conversation history, and maintain personalized interactions across multiple touchpoints. This transforms your agents from one-time onboarding tools into continuous relationship managers.

Scaling with the SDK

To create agents programmatically from your `customer-success-agent` template, use the Letta SDK:

*   [TypeScript](https://docs.letta.com/tutorials/customer-specific-agents#tab-panel-278)
    
*   [Python](https://docs.letta.com/tutorials/customer-specific-agents#tab-panel-279)
    

    import Letta from "@letta-ai/letta-client";
    const client = new Letta({ apiKey: "your-api-token" });
    // Create agent from template for new customerconst agent = await client.templates.agents.create({  project: "your-project",  templateVersion: "customer-success-agent:latest",  memoryVariables: {    customerName: "John Smith",    customerEmail: "john@techparts.com",    companyName: "TechParts Industries",    jobTitle: "Manufacturing Director",    industrySector: "Industrial Equipment",    professionalBackground: "15+ years in manufacturing operations",    businessChallenges: "Looking to reduce defects and optimize supply chain",    communicationPreferences: "Prefers data-driven discussions",  },  identityIds: ["customer_john_smith"],});

    from letta_client import Letta
    client = Letta(api_key="your-api-token")
    # Create agent from template for new customeragent = client.templates.agents.create(    project="your-project",    template_version="customer-success-agent:latest",    memory_variables={        "customer_name": "John Smith",        "customer_email": "john@techparts.com",        "company_name": "TechParts Industries",        "job_title": "Manufacturing Director",        "industry_sector": "Industrial Equipment",        "professional_background": "15+ years in manufacturing operations",        "business_challenges": "Looking to reduce defects and optimize supply chain",        "communication_preferences": "Prefers data-driven discussions"    },    identity_ids=["customer_john_smith"])

This approach integrates with CRM systems, sign-up workflows, and customer onboarding automation. See the [Letta SDK documentation](https://docs.letta.com/api-reference/templates/agents/create)
 for complete API reference.

**Other possibilities to explore:**

*   Agents that schedule meetings and manage follow-ups
*   Integration with support ticket systems for context-aware assistance
*   Advanced analytics that track relationship progression and agent effectiveness

The combination of persistent memory, research tools, and personalized communication provides a foundation for building more sophisticated customer relationship systems over time.

---

# Create | Letta Docs

[Skip to content](https://docs.letta.com/api/resources/templates/subresources/agents/methods/create#_top)

[API Reference](https://docs.letta.com/api)

[Templates](https://docs.letta.com/api/resources/templates)

[Agents](https://docs.letta.com/api/resources/templates/subresources/agents)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

* * *

**Copy Markdown**

**View as Markdown**

Create Agents From Template
===========================

post/v1/templates/{template\_version}/agents

Creates an Agent or multiple Agents from a template

##### Path ParametersExpand Collapse

template\_version: string

##### Body ParametersExpand Collapse

agent\_name: optional string

The name of the agent, optional otherwise a random one will be assigned

identity\_ids: optional array of string

The identity ids to assign to the agent

initial\_message\_sequence: optional array of object { content, role, batch\_item\_id, 4 more }

Set an initial sequence of messages, if not provided, the agent will start with the default message sequence, if an empty array is provided, the agent will start with no messages

content: string

role: "user" or "system" or "assistant"

Accepts one of the following:

"user"

"system"

"assistant"

batch\_item\_id: optional string

group\_id: optional string

name: optional string

otid: optional string

sender\_id: optional string

memory\_variables: optional map\[string\]

The memory variables to assign to the agent

tags: optional array of string

The tags to assign to the agent

tool\_variables: optional map\[string\]

The tool variables to assign to the agent

##### ReturnsExpand Collapse

agent\_ids: array of string

Array of created agent IDs

deployment\_id: string

The deployment ID for the created agents

group\_id: string

Optional group ID if agents were created in a group

##### Create Agents From Template

HTTP

HTTP

TypeScript

Python

    curl https://api.letta.com/v1/templates/$TEMPLATE_VERSION/agents \
        -X POST \
        -H "Authorization: Bearer $LETTA_API_KEY"

200 example

    {
      "agent_ids": [\
        "string"\
      ],
      "deployment_id": "deployment_id",
      "group_id": "group_id"
    }

##### Returns Examples

200 example

    {
      "agent_ids": [\
        "string"\
      ],
      "deployment_id": "deployment_id",
      "group_id": "group_id"
    }

---

# Letta Python SDK | Letta Docs

[Skip to content](https://docs.letta.com/api/python#_top)

API reference

[Overview](https://docs.letta.com/api/python)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

* * *

**Copy Markdown**

**View as Markdown**

Letta Python SDK
================

Letta Python SDK
================

[![pypi](https://img.shields.io/pypi/v/letta-client)](https://pypi.python.org/pypi/letta-client)

Letta is the platform for building stateful agents: open AI with advanced memory that can learn and self-improve over time.

*   [Letta Code](https://docs.letta.com/letta-code)
    : run agents locally in your terminal
*   [Letta API](https://docs.letta.com/quickstart/)
    : build agents into your applications

Get started
-----------

Install the Letta Python SDK:

    pip install letta-client

Simple Hello World example
--------------------------

Below is a quick example of creating a stateful agent and sending it a message (requires a [Letta API key](https://app.letta.com/)
, or setting `base_url=...` to point at a [Docker server](https://docs.letta.com/guides/docker)
). See the full [quickstart guide](https://docs.letta.com/quickstart)
 for complete documentation.

    from letta_client import Letta
    
    client = Letta(api_key="LETTA_API_KEY")
    
    agent_state = client.agents.create(
        model="openai/gpt-4o-mini",
        embedding="openai/text-embedding-3-small",
        memory_blocks=[\
            {\
                "label": "human",\
                "value": "The human's name is Chad. They like vibe coding."\
            },\
            {\
                "label": "persona",\
                "value": "My name is Sam, a helpful assistant."\
            }\
        ],
        tools=["web_search", "run_code"]
    )
    
    print(agent_state.id)
    # agent-d9be...0846
    
    response = client.agents.messages.create(
        agent_id=agent_state.id,
        messages=[\
            {\
                "role": "user",\
                "content": "Hey, nice to meet you, my name is Brad."\
            }\
        ]
    )
    
    # the agent will think, then edit its memory using a tool
    for message in response.messages:
        print(message)
    
    # The content of this memory block will be something like
    # "The human's name is Brad. They like vibe coding."
    # Fetch this block's content with:
    human_block = client.agents.blocks.retrieve(agent_id=agent_state.id, block_label="human")
    print(human_block.value)

Core concepts in Letta:
-----------------------

Letta is built on the [MemGPT](https://arxiv.org/abs/2310.08560)
 research paper, which introduced the concept of the “LLM Operating System” for memory management:

1.  [**Memory Hierarchy**](https://docs.letta.com/guides/agents/memory)
    : Agents have self-editing memory split between in-context and out-of-context memory
2.  [**Memory Blocks**](https://docs.letta.com/guides/agents/memory-blocks)
    : In-context memory is composed of persistent editable blocks
3.  [**Agentic Context Engineering**](https://docs.letta.com/guides/agents/context-engineering)
    : Agents control their context window using tools to edit, delete, or search memory
4.  [**Perpetual Self-Improving Agents**](https://docs.letta.com/guides/agents/overview)
    : Every agent has a perpetual (infinite) message history

Key Features
------------

### Memory Management ([full guide](https://docs.letta.com/guides/agents/memory-blocks)
)

Memory blocks are persistent, editable sections of an agent’s context window:

    # Create agent with memory blocks
    agent = client.agents.create(
        memory_blocks=[\
            {"label": "persona", "value": "I'm a helpful assistant."},\
            {"label": "human", "value": "User preferences and info."}\
        ]
    )
    
    # Update blocks manually
    client.agents.blocks.update(
        agent_id=agent.id,
        block_label="human",
        value="Updated user information"
    )
    
    # Retrieve a block
    block = client.agents.blocks.retrieve(agent_id=agent.id, block_label="human")

### Multi-agent Shared Memory ([full guide](https://docs.letta.com/guides/agents/multi-agent-shared-memory)
)

Memory blocks can be attached to multiple agents. All agents will have an up-to-date view on the contents of the memory block — if one agent modifies it, the other will see it immediately.

Here is how to attach a single memory block to multiple agents:

    # Create shared block
    shared_block = client.blocks.create(
        label="organization",
        value="Shared team context"
    )
    
    # Attach to multiple agents
    agent1 = client.agents.create(
        memory_blocks=[{"label": "persona", "value": "I am a supervisor"}],
        block_ids=[shared_block.id]
    )
    
    agent2 = client.agents.create(
        memory_blocks=[{"label": "persona", "value": "I am a worker"}],
        block_ids=[shared_block.id]
    )

### Sleep-time Agents ([full guide](https://docs.letta.com/guides/agents/architectures/sleeptime)
)

Background agents that share memory with your primary agent:

    agent = client.agents.create(
        model="openai/gpt-4o-mini",
        enable_sleeptime=True  # creates a sleep-time agent
    )

### Agent File Import/Export ([full guide](https://docs.letta.com/guides/agents/agent-file)
)

Save and share agents with the `.af` file format:

    # Import agent
    with open('/path/to/agent.af', 'rb') as f:
        agent = client.agents.import_file(file=f)
    
    # Export agent
    schema = client.agents.export_file(agent_id=agent.id)

### MCP Tools ([full guide](https://docs.letta.com/guides/mcp/overview)
)

Connect to Model Context Protocol servers:

    # First, create an MCP server (example: weather server)
    weather_server = client.mcp_servers.create(
        server_name="weather-server",
        config={
            "mcp_server_type": "streamable_http",
            "server_url": "https://weather-mcp.example.com/mcp",
        }
    )
    
    # List tools available from the MCP server
    tools = client.mcp_servers.tools.list(weather_server.id)
    
    # Create agent with MCP tool
    agent = client.agents.create(
        model="openai/gpt-4o-mini",
        tool_ids=[tool.id]
    )

### Filesystem ([full guide](https://docs.letta.com/guides/agents/filesystem)
)

Give agents access to files:

    # Create folder and upload file
    folder = client.folders.create(
        name="my_folder",
    )
    
    with open("file.txt", "rb") as f:
        client.folders.files.upload(file=f, folder_id=folder.id)
    
    # Attach to agent
    client.agents.folders.attach(agent_id=agent.id, folder_id=folder.id)

### Long-running Agents ([full guide](https://docs.letta.com/guides/agents/long-running)
)

Background execution with resumable streaming:

    stream = client.agents.messages.create(
        agent_id=agent.id,
        messages=[{"role": "user", "content": "Analyze this dataset"}],
        background=True
    )
    
    run_id = None
    last_seq_id = None
    for chunk in stream:
        run_id = chunk.run_id
        last_seq_id = chunk.seq_id
    
    # Resume if disconnected
    for chunk in client.runs.stream(run_id=run_id, starting_after=last_seq_id):
        print(chunk)

### Streaming ([full guide](https://docs.letta.com/guides/agents/streaming)
)

Stream responses in real-time:

    stream = client.agents.messages.stream(
        agent_id=agent.id,
        messages=[{"role": "user", "content": "Hello!"}]
    )
    
    for chunk in stream:
        print(chunk)

These methods return an [`APIResponse`](https://github.com/letta-ai/letta-python/tree/main/src/letta_client/_response.py)
 object.

The async client returns an [`AsyncAPIResponse`](https://github.com/letta-ai/letta-python/tree/main/src/letta_client/_response.py)
 with the same structure, the only difference being `await`able methods for reading the response content.

### Message Types ([full guide](https://docs.letta.com/guides/agents/message-types)
)

Agent responses contain different message types. Handle them with the `message_type` discriminator:

    messages = client.agents.messages.list(agent_id=agent.id) 
    
    for message in messages:
        if message.message_type == "user_message":
            print(f"User: {message.content}")
        elif message.message_type == "assistant_message":
            print(f"Agent: {message.content}")
        elif message.message_type == "reasoning_message":
            print(f"Reasoning: {message.reasoning}")
        elif message.message_type == "tool_call_message":
            print(f"Tool: {message.tool_call.name}")
        elif message.message_type == "tool_return_message":
            print(f"Result: {message.tool_return}")

Python Support
--------------

Full type hints and async support:

    from letta_client import Letta
    from letta_client.types import CreateAgentRequest
    
    # Sync client
    client = Letta(api_key="LETTA_API_KEY")
    
    # Async client
    from letta_client import AsyncLetta
    
    async_client = AsyncLetta(api_key="LETTA_API_KEY")
    agent = await async_client.agents.create(
        model="openai/gpt-4o-mini",
        memory_blocks=[...]
    )

Error Handling
--------------

    from letta_client.core.api_error import ApiError
    
    try:
        client.agents.messages.create(agent_id=agent_id, messages=[...])
    except ApiError as e:
        print(e.status_code)
        print(e.message)
        print(e.body)

Advanced Configuration
----------------------

### Retries

    response = client.agents.create(
        {...},
        request_options={"max_retries": 3}  # Default: 2
    )

### Timeouts

    response = client.agents.create(
        {...},
        request_options={"timeout_in_seconds": 30}  # Default: 60
    )

### Custom Headers

    response = client.agents.create(
        {...},
        request_options={
            "additional_headers": {
                "X-Custom-Header": "value"
            }
        }
    )

### Raw Response Access

    response = client.agents.with_raw_response.create({...})
    
    print(response.headers["X-My-Header"])
    print(response.data)  # access the underlying object

### Custom HTTP Client

    import httpx
    from letta_client import Letta
    
    client = Letta(
        httpx_client=httpx.Client(
            proxies="http://my.test.proxy.example.com",
            transport=httpx.HTTPTransport(local_address="0.0.0.0"),
        )
    )

Runtime Compatibility
---------------------

Works with:

*   Python 3.8+
*   Supports async/await
*   Compatible with type checkers (mypy, pyright)

Contributing
------------

Letta is an open source project built by over a hundred contributors. There are many ways to get involved in the Letta OSS project!

*   [**Join the Discord**](https://discord.gg/letta)
    : Chat with the Letta devs and other AI developers.
*   [**Chat on our forum**](https://forum.letta.com/)
    : If you’re not into Discord, check out our developer forum.
*   **Follow our socials**: [Twitter/X](https://twitter.com/Letta_AI)
    , [LinkedIn](https://www.linkedin.com/company/letta-ai/)
    , [YouTube](https://www.youtube.com/@letta-ai)
    

This SDK is generated programmatically. For SDK changes, please [open an issue](https://github.com/letta-ai/letta-python/issues)
.

README contributions are always welcome!

Resources
---------

*   [Documentation](https://docs.letta.com/)
    
*   [Python API Reference](https://github.com/letta-ai/letta-python/tree/main/reference.md)
    
*   [Example Applications](https://github.com/letta-ai/letta-chatbot-example)
    

License
-------

MIT

* * *

_**Legal notices**: By using Letta and related Letta services (such as the Letta endpoint or hosted service), you are agreeing to our [privacy policy](https://www.letta.com/privacy-policy)
 and [terms of service](https://www.letta.com/terms-of-service)
._

---

# Letta TypeScript SDK | Letta Docs

[Skip to content](https://docs.letta.com/api/typescript#_top)

API reference

[Overview](https://docs.letta.com/api/typescript)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

* * *

**Copy Markdown**

**View as Markdown**

Letta TypeScript SDK
====================

Letta TypeScript SDK
====================

[![npm shield](https://img.shields.io/npm/v/@letta-ai/letta-client)](https://www.npmjs.com/package/@letta-ai/letta-client)

Letta is the platform for building stateful agents: open AI with advanced memory that can learn and self-improve over time.

*   [Letta Code](https://docs.letta.com/letta-code)
    : run agents locally in your terminal
*   [Letta API](https://docs.letta.com/quickstart/)
    : build agents into your applications

Get started
-----------

Install the Letta TypeScript SDK:

    npm install @letta-ai/letta-client

Simple Hello World example
--------------------------

Below is a quick example of creating a stateful agent and sending it a message (requires a [Letta API key](https://app.letta.com/)
, or setting `baseUrl=...` to point at a [Docker server](https://docs.letta.com/guides/docker)
). See the full [quickstart guide](https://docs.letta.com/quickstart)
 for complete documentation.

    import { Letta } from "@letta-ai/letta-client";
    
    const client = new Letta({ apiKey: process.env.LETTA_API_KEY });
    
    const agentState = await client.agents.create({
        model: "openai/gpt-4.1",
        embedding: "openai/text-embedding-3-small",
        memory_blocks: [\
            {\
              label: "human",\
              value: "The human's name is Chad. They like vibe coding."\
            },\
            {\
              label: "persona",\
              value: "My name is Sam, a helpful assistant."\
            }\
        ],
        tools: ["web_search", "run_code"]
    });
    
    console.log("Agent created with ID:", agentState.id);
    
    const response = await client.agents.messages.create(agentState.id, {
        input: "Hey, nice to meet you, my name is Brad."
    });
    
    // the agent will think, then edit its memory using a tool
    for (const message of response.messages) {
        console.log(message);
    }
    
    // The content of this memory block will be something like
    // "The human's name is Brad. They like vibe coding."
    // Fetch this block's content with:
    const human_block = await client.agents.blocks.retrieve("human", { agent_id: agentState.id });
    console.log(human_block.value);

Core concepts in Letta:
-----------------------

Letta is built on the [MemGPT](https://arxiv.org/abs/2310.08560)
 research paper, which introduced the concept of the “LLM Operating System” for memory management:

1.  [**Memory Hierarchy**](https://docs.letta.com/guides/agents/memory)
    : Agents have self-editing memory split between in-context and out-of-context memory
2.  [**Memory Blocks**](https://docs.letta.com/guides/agents/memory-blocks)
    : In-context memory is composed of persistent editable blocks
3.  [**Agentic Context Engineering**](https://docs.letta.com/guides/agents/context-engineering)
    : Agents control their context window using tools to edit, delete, or search memory
4.  [**Perpetual Self-Improving Agents**](https://docs.letta.com/guides/agents/overview)
    : Every agent has a perpetual (infinite) message history

Key Features
------------

### Memory Management ([full guide](https://docs.letta.com/guides/agents/memory-blocks)
)

Memory blocks are persistent, editable sections of an agent’s context window:

    // Create agent with memory blocks
    const agent = await client.agents.create({
      memory_blocks: [\
        { label: "persona", value: "I'm a helpful assistant." },\
        { label: "human", value: "User preferences and info." }\
      ]
    });
    
    // Update blocks manually
    await client.agents.blocks.update("human", {
      agent_id: agent.id,
      value: "Updated user information"
    });
    
    // Retrieve a block
    const block = await client.agents.blocks.retrieve("human", { agent_id: agent.id });

### Multi-agent Shared Memory ([full guide](https://docs.letta.com/guides/agents/multi-agent-shared-memory)
)

Memory blocks can be attached to multiple agents. All agents will have an up-to-date view on the contents of the memory block — if one agent modifies it, the other will see it immediately.

Here is how to attach a single memory block to multiple agents:

    // Create shared block
    const sharedBlock = await client.blocks.create({
      label: "organization",
      value: "Shared team context"
    });
    
    // Attach to multiple agents
    const agent1 = await client.agents.create({
      memory_blocks: [{ label: "persona", value: "I am a supervisor" }],
      block_ids: [sharedBlock.id]
    });
    
    const agent2 = await client.agents.create({
      memory_blocks: [{ label: "persona", value: "I am a worker" }],
      block_ids: [sharedBlock.id]
    });

### Sleep-time Agents ([full guide](https://docs.letta.com/guides/agents/architectures/sleeptime)
)

Background agents that share memory with your primary agent:

    const agent = await client.agents.create({
      model: "openai/gpt-4.1",
      enable_sleeptime: true  // creates a sleep-time agent
    });

### Agent File Import/Export ([full guide](https://docs.letta.com/guides/agents/agent-file)
)

Save and share agents with the `.af` file format:

    import { readFileSync } from 'fs';
    
    // Import agent
    const file = new Blob([readFileSync('/path/to/agent.af')]);
    const agent = await client.agents.importFile(file);
    
    // Export agent
    const schema = await client.agents.exportFile(agent.id);

### MCP Tools ([full guide](https://docs.letta.com/guides/mcp/overview)
)

Connect to Model Context Protocol servers:

    // First, create an MCP server (example: weather server)
    const weatherServer = await client.mcpServers.create({
      server_name: "weather-server",
      config: {
        mcp_server_type: "streamable_http",
        server_url: "https://weather-mcp.example.com/mcp",
      },
    });
    
    // List tools available from the MCP server
    const tools = await client.mcpServers.tools.list(weatherServer.id);
    
    // Create agent with MCP tool
    const agent = await client.agents.create({
      model: "openai/gpt-4.1",
      tool_ids: [tool.id]
    });

### Filesystem ([full guide](https://docs.letta.com/guides/agents/filesystem)
)

Give agents access to files:

    import { createReadStream } from 'fs';
    
    // Create folder and upload file
    const folder = await client.folders.create({
      name: "my_folder",
    });
    
    await client.folders.files.upload(createReadStream("file.txt"), folder.id);
    
    // Attach to agent
    await client.agents.folders.attach(agent.id, folder.id);

### Long-running Agents ([full guide](https://docs.letta.com/guides/agents/long-running)
)

Background execution with resumable streaming:

    const stream = await client.agents.messages.create(agent.id, {
      messages: [\
        { role: "user", content: "Analyze this dataset" }\
      ],
      background: true
    });
    
    let run_id, last_seq_id;
    for await (const chunk of stream) {
      run_id = chunk.run_id;
      last_seq_id = chunk.seq_id;
    }
    
    // Resume if disconnected
    for await (const chunk of client.runs.stream(run_id, { starting_after: last_seq_id })) {
      console.log(chunk);
    }

### Streaming ([full guide](https://docs.letta.com/guides/agents/streaming)
)

Stream responses in real-time:

    const stream = await client.agents.messages.stream(agent.id, {
      messages: [\
        { role: "user", content: "Hello!" }\
      ]
    });
    
    for await (const chunk of stream) {
      console.log(chunk);
    }

### Message Types ([full guide](https://docs.letta.com/guides/agents/message-types)
)

Agent responses contain different message types. Handle them with the `message_type` discriminator:

    const messagesPage = await client.agents.messages.list(agent.id);
    
    for await (const message of messagesPage) {
      switch (message.message_type) {
        case "user_message":
          console.log("User:", message.content);
          break;
        case "assistant_message":
          console.log("Agent:", message.content);
          break;
        case "reasoning_message":
          console.log("Reasoning:", message.reasoning);
          break;
        case "tool_call_message":
          console.log("Tool:", message.tool_call.name);
          break;
        case "tool_return_message":
          console.log("Result:", message.tool_return);
          break;
      }
    }

TypeScript Support
------------------

Full TypeScript support with exported types:

    import { Letta } from "@letta-ai/letta-client";
    
    const request: Letta.CreateAgentRequest = {
      model: "openai/gpt-4.1",
      memory_blocks: [...]
    };

Error Handling
--------------

    import { LettaError } from "@letta-ai/letta-client";
    
    try {
      await client.agents.messages.create(agentId, {...});
    } catch (err) {
      if (err instanceof LettaError) {
        console.log(err.statusCode);
        console.log(err.message);
        console.log(err.body);
      }
    }

Advanced Configuration
----------------------

### Retries

    const response = await client.agents.create({...}, {
      maxRetries: 3 // Default: 2
    });

### Timeouts

    const response = await client.agents.create({...}, {
      timeoutInSeconds: 30 // Default: 60
    });

### Custom Headers

    const response = await client.agents.create({...}, {
      headers: {
        'X-Custom-Header': 'value'
      }
    });

Contributing
------------

Letta is an open source project built by over a hundred contributors. There are many ways to get involved in the Letta OSS project!

*   [**Join the Discord**](https://discord.gg/letta)
    : Chat with the Letta devs and other AI developers.
*   [**Chat on our forum**](https://forum.letta.com/)
    : If you’re not into Discord, check out our developer forum.
*   **Follow our socials**: [Twitter/X](https://twitter.com/Letta_AI)
    , [LinkedIn](https://www.linkedin.com/company/letta-ai/)
    , [YouTube](https://www.youtube.com/@letta-ai)
    

This SDK is generated programmatically. For SDK changes, please [open an issue](https://github.com/letta-ai/letta-node/issues)
.

README contributions are always welcome!

Resources
---------

*   [Documentation](https://docs.letta.com/)
    
*   [TypeScript API Reference](https://github.com/letta-ai/letta-node/tree/main/reference.md)
    
*   [Example Applications](https://github.com/letta-ai/letta-chatbot-example)
    

License
-------

MIT

* * *

_**Legal notices**: By using Letta and related Letta services (such as the Letta endpoint or hosted service), you are agreeing to our [privacy policy](https://www.letta.com/privacy-policy)
 and [terms of service](https://www.letta.com/terms-of-service)
._

---

# List | Letta Docs

[Skip to content](https://docs.letta.com/api/resources/agents/subresources/messages/methods/list#_top)

[API Reference](https://docs.letta.com/api)

[Agents](https://docs.letta.com/api/resources/agents)

[Messages](https://docs.letta.com/api/resources/agents/subresources/messages)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

* * *

**Copy Markdown**

**View as Markdown**

List Messages
=============

get/v1/agents/{agent\_id}/messages

Retrieve message history for an agent.

##### Path ParametersExpand Collapse

agent\_id: string

The ID of the agent in the format 'agent-'

minLength42

maxLength42

##### Query ParametersExpand Collapse

after: optional string

Cursor for pagination (message ID). Returns results relative to this ID in the specified sort order. Expected format: 'message-'

minLength44

maxLength44

Deprecatedassistant\_message\_tool\_kwarg: optional string

The name of the message argument.

Deprecatedassistant\_message\_tool\_name: optional string

The name of the designated message tool.

before: optional string

Cursor for pagination (message ID). Returns results relative to this ID in the specified sort order. Expected format: 'message-'

minLength44

maxLength44

conversation\_id: optional string

Conversation ID to filter messages by.

group\_id: optional string

Group ID to filter messages by.

include\_err: optional boolean

Whether to include error messages and error statuses. For debugging purposes only.

include\_return\_message\_types: optional array of [MessageType](https://docs.letta.com/api/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20message_type%20%3E%20(schema))

Message types to include in response. When null, all message types are returned.

Accepts one of the following:

"system\_message"

"user\_message"

"assistant\_message"

"reasoning\_message"

"hidden\_reasoning\_message"

"tool\_call\_message"

"tool\_return\_message"

"approval\_request\_message"

"approval\_response\_message"

"summary\_message"

"event\_message"

limit: optional number

Maximum number of messages to return

order: optional "asc" or "desc"

Sort order for messages by creation time. 'asc' for oldest first, 'desc' for newest first

Accepts one of the following:

"asc"

"desc"

order\_by: optional "created\_at"

Field to sort by

Deprecateduse\_assistant\_message: optional boolean

Whether to use assistant messages

##### ReturnsExpand Collapse

SystemMessage = object { id, content, date, 8 more }

A message generated by the system. Never streamed back on a response, only used for cursor pagination.

Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional\[str\]): The name of the sender of the message content (str): The message content sent by the system

id: string

content: string

The message content sent by the system

date: string

is\_err: optional boolean

message\_type: optional "system\_message"

The type of the message.

name: optional string

otid: optional string

The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

run\_id: optional string

sender\_id: optional string

seq\_id: optional number

step\_id: optional string

UserMessage = object { id, content, date, 8 more }

A message sent by the user. Never streamed back on a response, only used for cursor pagination.

Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional\[str\]): The name of the sender of the message content (Union\[str, List\[LettaUserMessageContentUnion\]\]): The message content sent by the user (can be a string or an array of multi-modal content parts)

id: string

content: array of [LettaUserMessageContentUnion](https://docs.letta.com/api/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20letta_user_message_content_union%20%3E%20(schema))
 or string

The message content sent by the user (can be a string or an array of multi-modal content parts)

Accepts one of the following:

UnionMember0 = array of [LettaUserMessageContentUnion](https://docs.letta.com/api/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20letta_user_message_content_union%20%3E%20(schema))

Accepts one of the following:

TextContent = object { text, signature, type }

text: string

The text content of the message.

signature: optional string

Stores a unique identifier for any reasoning associated with this text content.

type: optional "text"

The type of the message.

ImageContent = object { source, type }

source: object { url, type } or object { data, media\_type, detail, type } or object { file\_id, data, detail, 2 more }

The source of the image.

Accepts one of the following:

URL = object { url, type }

url: string

The URL of the image.

type: optional "url"

The source type for the image.

Base64 = object { data, media\_type, detail, type }

data: string

The base64 encoded image data.

media\_type: string

The media type for the image.

detail: optional string

What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)

type: optional "base64"

The source type for the image.

Letta = object { file\_id, data, detail, 2 more }

file\_id: string

The unique identifier of the image file persisted in storage.

data: optional string

The base64 encoded image data.

detail: optional string

What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)

media\_type: optional string

The media type for the image.

type: optional "letta"

The source type for the image.

type: optional "image"

The type of the message.

UnionMember1 = string

date: string

is\_err: optional boolean

message\_type: optional "user\_message"

The type of the message.

name: optional string

otid: optional string

The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

run\_id: optional string

sender\_id: optional string

seq\_id: optional number

step\_id: optional string

ReasoningMessage = object { id, date, reasoning, 10 more }

Representation of an agent's internal reasoning.

Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional\[str\]): The name of the sender of the message source (Literal\["reasoner\_model", "non\_reasoner\_model"\]): Whether the reasoning content was generated natively by a reasoner model or derived via prompting reasoning (str): The internal reasoning of the agent signature (Optional\[str\]): The model-generated signature of the reasoning step

id: string

date: string

reasoning: string

is\_err: optional boolean

message\_type: optional "reasoning\_message"

The type of the message.

name: optional string

otid: optional string

The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

run\_id: optional string

sender\_id: optional string

seq\_id: optional number

signature: optional string

source: optional "reasoner\_model" or "non\_reasoner\_model"

Accepts one of the following:

"reasoner\_model"

"non\_reasoner\_model"

step\_id: optional string

HiddenReasoningMessage = object { id, date, state, 9 more }

Representation of an agent's internal reasoning where reasoning content has been hidden from the response.

Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional\[str\]): The name of the sender of the message state (Literal\["redacted", "omitted"\]): Whether the reasoning content was redacted by the provider or simply omitted by the API hidden\_reasoning (Optional\[str\]): The internal reasoning of the agent

id: string

date: string

state: "redacted" or "omitted"

Accepts one of the following:

"redacted"

"omitted"

hidden\_reasoning: optional string

is\_err: optional boolean

message\_type: optional "hidden\_reasoning\_message"

The type of the message.

name: optional string

otid: optional string

The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

run\_id: optional string

sender\_id: optional string

seq\_id: optional number

step\_id: optional string

ToolCallMessage = object { id, date, tool\_call, 9 more }

A message representing a request to call a tool (generated by the LLM to trigger tool execution).

Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional\[str\]): The name of the sender of the message tool\_call (Union\[ToolCall, ToolCallDelta\]): The tool call

id: string

date: string

Deprecatedtool\_call: [ToolCall](https://docs.letta.com/api/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20tool_call%20%3E%20(schema))
 { arguments, name, tool\_call\_id } or [ToolCallDelta](https://docs.letta.com/api/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20tool_call_delta%20%3E%20(schema))
 { arguments, name, tool\_call\_id }

Accepts one of the following:

ToolCall = object { arguments, name, tool\_call\_id }

arguments: string

name: string

tool\_call\_id: string

ToolCallDelta = object { arguments, name, tool\_call\_id }

arguments: optional string

name: optional string

tool\_call\_id: optional string

is\_err: optional boolean

message\_type: optional "tool\_call\_message"

The type of the message.

name: optional string

otid: optional string

The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

run\_id: optional string

sender\_id: optional string

seq\_id: optional number

step\_id: optional string

tool\_calls: optional array of [ToolCall](https://docs.letta.com/api/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20tool_call%20%3E%20(schema))
 { arguments, name, tool\_call\_id } or [ToolCallDelta](https://docs.letta.com/api/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20tool_call_delta%20%3E%20(schema))
 { arguments, name, tool\_call\_id }

Accepts one of the following:

UnionMember0 = array of [ToolCall](https://docs.letta.com/api/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20tool_call%20%3E%20(schema))
 { arguments, name, tool\_call\_id }

arguments: string

name: string

tool\_call\_id: string

ToolCallDelta = object { arguments, name, tool\_call\_id }

arguments: optional string

name: optional string

tool\_call\_id: optional string

ToolReturnMessage = object { id, date, status, 13 more }

A message representing the return value of a tool call (generated by Letta executing the requested tool).

Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional\[str\]): The name of the sender of the message tool\_return (str): The return value of the tool (deprecated, use tool\_returns) status (Literal\["success", "error"\]): The status of the tool call (deprecated, use tool\_returns) tool\_call\_id (str): A unique identifier for the tool call that generated this message (deprecated, use tool\_returns) stdout (Optional\[List(str)\]): Captured stdout (e.g. prints, logs) from the tool invocation (deprecated, use tool\_returns) stderr (Optional\[List(str)\]): Captured stderr from the tool invocation (deprecated, use tool\_returns) tool\_returns (Optional\[List\[ToolReturn\]\]): List of tool returns for multi-tool support

id: string

date: string

Deprecatedstatus: "success" or "error"

Accepts one of the following:

"success"

"error"

Deprecatedtool\_call\_id: string

Deprecatedtool\_return: string

is\_err: optional boolean

message\_type: optional "tool\_return\_message"

The type of the message.

name: optional string

otid: optional string

The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

run\_id: optional string

sender\_id: optional string

seq\_id: optional number

Deprecatedstderr: optional array of string

Deprecatedstdout: optional array of string

step\_id: optional string

tool\_returns: optional array of [ToolReturn](https://docs.letta.com/api/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20tool_return%20%3E%20(schema))
 { status, tool\_call\_id, tool\_return, 3 more }

status: "success" or "error"

Accepts one of the following:

"success"

"error"

tool\_call\_id: string

tool\_return: array of [TextContent](https://docs.letta.com/api/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20text_content%20%3E%20(schema))
 { text, signature, type } or [ImageContent](https://docs.letta.com/api/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20image_content%20%3E%20(schema))
 { source, type } or string

The tool return value - either a string or list of content parts (text/image)

Accepts one of the following:

UnionMember0 = array of [TextContent](https://docs.letta.com/api/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20text_content%20%3E%20(schema))
 { text, signature, type } or [ImageContent](https://docs.letta.com/api/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20image_content%20%3E%20(schema))
 { source, type }

Accepts one of the following:

TextContent = object { text, signature, type }

text: string

The text content of the message.

signature: optional string

Stores a unique identifier for any reasoning associated with this text content.

type: optional "text"

The type of the message.

ImageContent = object { source, type }

source: object { url, type } or object { data, media\_type, detail, type } or object { file\_id, data, detail, 2 more }

The source of the image.

Accepts one of the following:

URL = object { url, type }

url: string

The URL of the image.

type: optional "url"

The source type for the image.

Base64 = object { data, media\_type, detail, type }

data: string

The base64 encoded image data.

media\_type: string

The media type for the image.

detail: optional string

What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)

type: optional "base64"

The source type for the image.

Letta = object { file\_id, data, detail, 2 more }

file\_id: string

The unique identifier of the image file persisted in storage.

data: optional string

The base64 encoded image data.

detail: optional string

What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)

media\_type: optional string

The media type for the image.

type: optional "letta"

The source type for the image.

type: optional "image"

The type of the message.

UnionMember1 = string

stderr: optional array of string

stdout: optional array of string

type: optional "tool"

The message type to be created.

AssistantMessage = object { id, content, date, 8 more }

A message sent by the LLM in response to user input. Used in the LLM context.

Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional\[str\]): The name of the sender of the message content (Union\[str, List\[LettaAssistantMessageContentUnion\]\]): The message content sent by the agent (can be a string or an array of content parts)

id: string

content: array of [LettaAssistantMessageContentUnion](https://docs.letta.com/api/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20letta_assistant_message_content_union%20%3E%20(schema))
 { text, signature, type } or string

The message content sent by the agent (can be a string or an array of content parts)

Accepts one of the following:

UnionMember0 = array of [LettaAssistantMessageContentUnion](https://docs.letta.com/api/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20letta_assistant_message_content_union%20%3E%20(schema))
 { text, signature, type }

text: string

The text content of the message.

signature: optional string

Stores a unique identifier for any reasoning associated with this text content.

type: optional "text"

The type of the message.

UnionMember1 = string

date: string

is\_err: optional boolean

message\_type: optional "assistant\_message"

The type of the message.

name: optional string

otid: optional string

The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

run\_id: optional string

sender\_id: optional string

seq\_id: optional number

step\_id: optional string

ApprovalRequestMessage = object { id, date, tool\_call, 9 more }

A message representing a request for approval to call a tool (generated by the LLM to trigger tool execution).

Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional\[str\]): The name of the sender of the message tool\_call (ToolCall): The tool call

id: string

date: string

Deprecatedtool\_call: [ToolCall](https://docs.letta.com/api/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20tool_call%20%3E%20(schema))
 { arguments, name, tool\_call\_id } or [ToolCallDelta](https://docs.letta.com/api/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20tool_call_delta%20%3E%20(schema))
 { arguments, name, tool\_call\_id }

The tool call that has been requested by the llm to run

Accepts one of the following:

ToolCall = object { arguments, name, tool\_call\_id }

arguments: string

name: string

tool\_call\_id: string

ToolCallDelta = object { arguments, name, tool\_call\_id }

arguments: optional string

name: optional string

tool\_call\_id: optional string

is\_err: optional boolean

message\_type: optional "approval\_request\_message"

The type of the message.

name: optional string

otid: optional string

The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

run\_id: optional string

sender\_id: optional string

seq\_id: optional number

step\_id: optional string

tool\_calls: optional array of [ToolCall](https://docs.letta.com/api/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20tool_call%20%3E%20(schema))
 { arguments, name, tool\_call\_id } or [ToolCallDelta](https://docs.letta.com/api/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20tool_call_delta%20%3E%20(schema))
 { arguments, name, tool\_call\_id }

The tool calls that have been requested by the llm to run, which are pending approval

Accepts one of the following:

UnionMember0 = array of [ToolCall](https://docs.letta.com/api/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20tool_call%20%3E%20(schema))
 { arguments, name, tool\_call\_id }

arguments: string

name: string

tool\_call\_id: string

ToolCallDelta = object { arguments, name, tool\_call\_id }

arguments: optional string

name: optional string

tool\_call\_id: optional string

ApprovalResponseMessage = object { id, date, approval\_request\_id, 11 more }

A message representing a response form the user indicating whether a tool has been approved to run.

Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional\[str\]): The name of the sender of the message approve: (bool) Whether the tool has been approved approval\_request\_id: The ID of the approval request reason: (Optional\[str\]) An optional explanation for the provided approval status

id: string

date: string

Deprecatedapproval\_request\_id: optional string

The message ID of the approval request

approvals: optional array of [ApprovalReturn](https://docs.letta.com/api/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20approval_return%20%3E%20(schema))
 { approve, tool\_call\_id, reason, type } or [ToolReturn](https://docs.letta.com/api/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20tool_return%20%3E%20(schema))
 { status, tool\_call\_id, tool\_return, 3 more }

The list of approval responses

Accepts one of the following:

ApprovalReturn = object { approve, tool\_call\_id, reason, type }

approve: boolean

Whether the tool has been approved

tool\_call\_id: string

The ID of the tool call that corresponds to this approval

reason: optional string

An optional explanation for the provided approval status

type: optional "approval"

The message type to be created.

ToolReturn = object { status, tool\_call\_id, tool\_return, 3 more }

status: "success" or "error"

Accepts one of the following:

"success"

"error"

tool\_call\_id: string

tool\_return: array of [TextContent](https://docs.letta.com/api/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20text_content%20%3E%20(schema))
 { text, signature, type } or [ImageContent](https://docs.letta.com/api/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20image_content%20%3E%20(schema))
 { source, type } or string

The tool return value - either a string or list of content parts (text/image)

Accepts one of the following:

UnionMember0 = array of [TextContent](https://docs.letta.com/api/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20text_content%20%3E%20(schema))
 { text, signature, type } or [ImageContent](https://docs.letta.com/api/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20image_content%20%3E%20(schema))
 { source, type }

Accepts one of the following:

TextContent = object { text, signature, type }

text: string

The text content of the message.

signature: optional string

Stores a unique identifier for any reasoning associated with this text content.

type: optional "text"

The type of the message.

ImageContent = object { source, type }

source: object { url, type } or object { data, media\_type, detail, type } or object { file\_id, data, detail, 2 more }

The source of the image.

Accepts one of the following:

URL = object { url, type }

url: string

The URL of the image.

type: optional "url"

The source type for the image.

Base64 = object { data, media\_type, detail, type }

data: string

The base64 encoded image data.

media\_type: string

The media type for the image.

detail: optional string

What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)

type: optional "base64"

The source type for the image.

Letta = object { file\_id, data, detail, 2 more }

file\_id: string

The unique identifier of the image file persisted in storage.

data: optional string

The base64 encoded image data.

detail: optional string

What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)

media\_type: optional string

The media type for the image.

type: optional "letta"

The source type for the image.

type: optional "image"

The type of the message.

UnionMember1 = string

stderr: optional array of string

stdout: optional array of string

type: optional "tool"

The message type to be created.

Deprecatedapprove: optional boolean

Whether the tool has been approved

is\_err: optional boolean

message\_type: optional "approval\_response\_message"

The type of the message.

name: optional string

otid: optional string

The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

Deprecatedreason: optional string

An optional explanation for the provided approval status

run\_id: optional string

sender\_id: optional string

seq\_id: optional number

step\_id: optional string

SummaryMessage = object { id, date, summary, 9 more }

A message representing a summary of the conversation. Sent to the LLM as a user or system message depending on the provider.

id: string

date: string

summary: string

compaction\_stats: optional object { context\_window, messages\_count\_after, messages\_count\_before, 3 more }

Statistics about a memory compaction operation.

context\_window: number

The model's context window size

messages\_count\_after: number

Number of messages after compaction

messages\_count\_before: number

Number of messages before compaction

trigger: string

What triggered the compaction (e.g., 'context\_window\_exceeded', 'post\_step\_context\_check')

context\_tokens\_after: optional number

Token count after compaction (message tokens only, does not include tool definitions)

context\_tokens\_before: optional number

Token count before compaction (from LLM usage stats, includes full context sent to LLM)

is\_err: optional boolean

message\_type: optional "summary\_message"

name: optional string

otid: optional string

The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

run\_id: optional string

sender\_id: optional string

seq\_id: optional number

step\_id: optional string

EventMessage = object { id, date, event\_data, 9 more }

A message for notifying the developer that an event that has occured (e.g. a compaction). Events are NOT part of the context window.

id: string

date: string

event\_data: map\[unknown\]

event\_type: "compaction"

is\_err: optional boolean

message\_type: optional "event\_message"

name: optional string

otid: optional string

The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

run\_id: optional string

sender\_id: optional string

seq\_id: optional number

step\_id: optional string

##### List Messages

HTTP

HTTP

TypeScript

Python

    curl https://api.letta.com/v1/agents/$AGENT_ID/messages \
        -H "Authorization: Bearer $LETTA_API_KEY"

200 example

    [\
      {\
        "id": "id",\
        "content": "content",\
        "date": "2019-12-27T18:11:19.117Z",\
        "is_err": true,\
        "message_type": "system_message",\
        "name": "name",\
        "otid": "otid",\
        "run_id": "run_id",\
        "sender_id": "sender_id",\
        "seq_id": 0,\
        "step_id": "step_id"\
      }\
    ]

##### Returns Examples

200 example

    [\
      {\
        "id": "id",\
        "content": "content",\
        "date": "2019-12-27T18:11:19.117Z",\
        "is_err": true,\
        "message_type": "system_message",\
        "name": "name",\
        "otid": "otid",\
        "run_id": "run_id",\
        "sender_id": "sender_id",\
        "seq_id": 0,\
        "step_id": "step_id"\
      }\
    ]

---

# Tools | Letta Docs

[Skip to content](https://docs.letta.com/guides/ade/tools#_top)

Tools
=====

Add, remove, and test custom tools for your agent.

The Tools panel in the ADE provides a comprehensive interface for managing the tools available to your agent. These tools define what capabilities your agent has beyond conversation, enabling it to perform actions, access information, and interact with external systems.

![](https://docs.letta.com/images/ade_screenshot_tool_debugger_light.png) ![](https://docs.letta.com/images/ade_screenshot_tool_debugger.png)

Managing Agent Tools
--------------------

[Section titled “Managing Agent Tools”](https://docs.letta.com/guides/ade/tools#managing-agent-tools)

### Viewing Current Tools

[Section titled “Viewing Current Tools”](https://docs.letta.com/guides/ade/tools#viewing-current-tools)

The Tools panel displays all tools currently attached to your agent, showing both built-in Letta tool (which can be detached), as well as custom tools that you have created and attached to the agent.

### Adding Tools

[Section titled “Adding Tools”](https://docs.letta.com/guides/ade/tools#adding-tools)

Adding tools to your agent is a straightforward process:

1.  Click the “Add Tool” button in the Tools panel
2.  Browse the tool library or search for specific tools
3.  Select a tool to view its details
4.  Click “Add to Agent” to attach it

The tool will immediately become available to your agent without requiring a restart or recreation of the agent.

### Removing Tools

[Section titled “Removing Tools”](https://docs.letta.com/guides/ade/tools#removing-tools)

To remove a tool from your agent:

1.  Locate the tool in the Tools panel
2.  Click the three-dot menu next to the tool
3.  Select “Remove Tool”

The tool will be detached from your agent but remains in your tool library for future use.

Creating Custom Tools
---------------------

[Section titled “Creating Custom Tools”](https://docs.letta.com/guides/ade/tools#creating-custom-tools)

For more information on creating custom tools, see our main [tools documentation](https://docs.letta.com/guides/core-concepts/tools/builtin-tools)
.

### Live Tool Testing Environment

[Section titled “Live Tool Testing Environment”](https://docs.letta.com/guides/ade/tools#live-tool-testing-environment)

One of the most powerful features of the ADE is the ability to test tools as you build them:

1.  Write your tool implementation
2.  Enter test arguments in the JSON input field
3.  Click “Run” to execute the tool in a sandboxed environment
4.  View the results or error messages
5.  Refine your implementation and test again

This real-time testing capability dramatically speeds up tool development and debugging.

---

# Anthropic | Letta Docs

[Skip to content](https://docs.letta.com/guides/server/providers/anthropic#_top)

Anthropic
=========

Configure Anthropic's Claude models for Letta agents.

You can use Letta with Anthropic if you have an Anthropic account and API key. Currently, only there are no supported **embedding** models for Anthropic (only LLM models). You will need to use a seperate provider (e.g. OpenAI) or the Letta embeddings endpoint (`letta-free`) for embeddings.

Enabling Anthropic models with Docker
-------------------------------------

[Section titled “Enabling Anthropic models with Docker”](https://docs.letta.com/guides/server/providers/anthropic#enabling-anthropic-models-with-docker)

To enable Anthropic models when running the Letta server with Docker, set your `ANTHROPIC_API_KEY` as an environment variable:

    # replace `~/.letta/.persist/pgdata` with wherever you want to store your agent datadocker run \  -v ~/.letta/.persist/pgdata:/var/lib/postgresql/data \  -p 8283:8283 \  -e ANTHROPIC_API_KEY="your_anthropic_api_key" \  letta/letta:latest

See the [self-hosting guide](https://docs.letta.com/guides/docker)
 for more information on running Letta with Docker.

Specifying agent models
-----------------------

[Section titled “Specifying agent models”](https://docs.letta.com/guides/server/providers/anthropic#specifying-agent-models)

When creating agents on your self-hosted server, you must specify both the LLM and embedding models to use. You can additionally specify a context window limit (which must be less than or equal to the maximum size).

    from letta_client import Lettaimport os
    # Connect to your self-hosted serverclient = Letta(base_url="http://localhost:8283")
    agent = client.agents.create(    model="anthropic/claude-3-5-sonnet-20241022",    embedding="openai/text-embedding-3-small",  # An embedding model is required for self-hosted    # optional configuration    context_window_limit=30000)

Anthropic models have very large context windows, which will be very expensive and high latency. We recommend setting a lower `context_window_limit` when using Anthropic models.

---

# OpenAI | Letta Docs

[Skip to content](https://docs.letta.com/guides/server/providers/openai#_top)

OpenAI
======

Configure OpenAI models including GPT-4 and GPT-3.5 for Letta agents.

You can use Letta with OpenAI if you have an OpenAI account and API key. Once you have set your `OPENAI_API_KEY` in your environment variables, you can select what model and configure the context window size.

Currently, Letta supports the following OpenAI models:

*   `gpt-4` (recommended for advanced reasoning)
*   `gpt-4o-mini` (recommended for low latency and cost)
*   `gpt-4o`
*   `gpt-4-turbo` (_not_ recommended, should use `gpt-4o-mini` instead)
*   `gpt-3.5-turbo` (_not_ recommended, should use `gpt-4o-mini` instead)

Enabling OpenAI models with Docker
----------------------------------

[Section titled “Enabling OpenAI models with Docker”](https://docs.letta.com/guides/server/providers/openai#enabling-openai-models-with-docker)

To enable OpenAI models when running the Letta server with Docker, set your `OPENAI_API_KEY` as an environment variable:

    # replace `~/.letta/.persist/pgdata` with wherever you want to store your agent datadocker run \  -v ~/.letta/.persist/pgdata:/var/lib/postgresql/data \  -p 8283:8283 \  -e OPENAI_API_KEY="your_openai_api_key" \  letta/letta:latest

See the [self-hosting guide](https://docs.letta.com/guides/docker)
 for more information on running Letta with Docker.

Specifying agent models
-----------------------

[Section titled “Specifying agent models”](https://docs.letta.com/guides/server/providers/openai#specifying-agent-models)

When creating agents on your self-hosted server, you must specify both the LLM and embedding models to use via a _handle_. You can additionally specify a context window limit (which must be less than or equal to the maximum size).

    from letta_client import Lettaimport os
    # Connect to your self-hosted serverclient = Letta(base_url="http://localhost:8283")
    openai_agent = client.agents.create(    model="openai/gpt-4o-mini",    embedding="openai/text-embedding-3-small",  # An embedding model is required for self-hosted    # optional configuration    context_window_limit=16000)

---

# Ollama | Letta Docs

[Skip to content](https://docs.letta.com/guides/server/providers/ollama#_top)

Ollama
======

Use Ollama for running local open-source models with Letta agents.

Setup Ollama
------------

[Section titled “Setup Ollama”](https://docs.letta.com/guides/server/providers/ollama#setup-ollama)

1.  Download + install [Ollama](https://github.com/ollama/ollama)
     and the model you want to test with
2.  Download a model to test with by running `ollama pull <MODEL_NAME>` in the terminal (check the [Ollama model library](https://ollama.ai/library)
     for available models)

For example, if we want to use Dolphin 2.2.1 Mistral, we can download it by running:

    # Let's use the q6_K variantollama pull dolphin2.2-mistral:7b-q6_K

    pulling manifestpulling d8a5ee4aba09... 100% |█████████████████████████████████████████████████████████████████████████| (4.1/4.1 GB, 20 MB/s)pulling a47b02e00552... 100% |██████████████████████████████████████████████████████████████████████████████| (106/106 B, 77 B/s)pulling 9640c2212a51... 100% |████████████████████████████████████████████████████████████████████████████████| (41/41 B, 22 B/s)pulling de6bcd73f9b4... 100% |████████████████████████████████████████████████████████████████████████████████| (58/58 B, 28 B/s)pulling 95c3d8d4429f... 100% |█████████████████████████████████████████████████████████████████████████████| (455/455 B, 330 B/s)verifying sha256 digestwriting manifestremoving any unused layerssuccess

Enabling Ollama with Docker
---------------------------

[Section titled “Enabling Ollama with Docker”](https://docs.letta.com/guides/server/providers/ollama#enabling-ollama-with-docker)

To enable Ollama models when running the Letta server with Docker, set the `OLLAMA_BASE_URL` environment variable.

**macOS/Windows:** Since Ollama is running on the host network, you will need to use `host.docker.internal` to connect to the Ollama server instead of `localhost`.

    # replace `~/.letta/.persist/pgdata` with wherever you want to store your agent datadocker run \  -v ~/.letta/.persist/pgdata:/var/lib/postgresql/data \  -p 8283:8283 \  -e OLLAMA_BASE_URL="http://host.docker.internal:11434/v1" \  letta/letta:latest

**Linux:** Use `--network host` and `localhost`:

    docker run \  -v ~/.letta/.persist/pgdata:/var/lib/postgresql/data \  --network host \  -e OLLAMA_BASE_URL="http://localhost:11434/v1" \  letta/letta:latest

See the [self-hosting guide](https://docs.letta.com/guides/docker)
 for more information on running Letta with Docker.

Specifying agent models
-----------------------

[Section titled “Specifying agent models”](https://docs.letta.com/guides/server/providers/ollama#specifying-agent-models)

When creating agents on your self-hosted server, you must specify both the LLM and embedding models to use via a _handle_. You can additionally specify a context window limit (which must be less than or equal to the maximum size).

    from letta_client import Lettaimport os
    # Connect to your self-hosted serverclient = Letta(base_url="http://localhost:8283")
    ollama_agent = client.agents.create(    model="ollama/thewindmom/hermes-3-llama-3.1-8b:latest",    embedding="ollama/mxbai-embed-large",  # An embedding model is required for self-hosted    # optional configuration    context_window_limit=16000)

---

# Client | Letta Docs

[Skip to content](https://docs.letta.com/api/typescript/resources/$client#_top)

[API Reference](https://docs.letta.com/api/typescript)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

* * *

**Copy Markdown**

**View as Markdown**

Client
======

##### [Check Health](https://docs.letta.com/api/typescript/resources/$client/methods/health)

client.health(RequestOptionsoptions?): [HealthResponse](https://docs.letta.com/api/typescript/resources/$client#(resource)%20%24client%20%3E%20(model)%20health_response%20%3E%20(schema))
 { status, version }

get/v1/health/

---

# Client | Letta Docs

[Skip to content](https://docs.letta.com/api/python/resources/$client#_top)

[API Reference](https://docs.letta.com/api/python)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

* * *

**Copy Markdown**

**View as Markdown**

Client
======

##### [Check Health](https://docs.letta.com/api/python/resources/$client/methods/health)

health() \-> [HealthResponse](https://docs.letta.com/api/python/resources/$client#(resource)%20%24client%20%3E%20(model)%20health_response%20%3E%20(schema))

get/v1/health/

---

# Blocks | Letta Docs

[Skip to content](https://docs.letta.com/api/python/resources/blocks#_top)

[API Reference](https://docs.letta.com/api/python)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

* * *

**Copy Markdown**

**View as Markdown**

Blocks
======

##### [List Blocks](https://docs.letta.com/api/python/resources/blocks/methods/list)

blocks.list(BlockListParams\*\*kwargs) \-> SyncArrayPage\[[BlockResponse](https://docs.letta.com/api/python/resources/blocks#(resource)%20blocks%20%3E%20(model)%20block_response%20%3E%20(schema))\
\]

get/v1/blocks/

##### [Create Block](https://docs.letta.com/api/python/resources/blocks/methods/create)

blocks.create(BlockCreateParams\*\*kwargs) \-> [BlockResponse](https://docs.letta.com/api/python/resources/blocks#(resource)%20blocks%20%3E%20(model)%20block_response%20%3E%20(schema))

post/v1/blocks/

##### [Update Block](https://docs.letta.com/api/python/resources/blocks/methods/update)

blocks.update(strblock\_id, BlockUpdateParams\*\*kwargs) \-> [BlockResponse](https://docs.letta.com/api/python/resources/blocks#(resource)%20blocks%20%3E%20(model)%20block_response%20%3E%20(schema))

patch/v1/blocks/{block\_id}

##### [Delete Block](https://docs.letta.com/api/python/resources/blocks/methods/delete)

blocks.delete(strblock\_id) \-> object

delete/v1/blocks/{block\_id}

##### [Retrieve Block](https://docs.letta.com/api/python/resources/blocks/methods/retrieve)

blocks.retrieve(strblock\_id) \-> [BlockResponse](https://docs.letta.com/api/python/resources/blocks#(resource)%20blocks%20%3E%20(model)%20block_response%20%3E%20(schema))

get/v1/blocks/{block\_id}

##### ModelsExpand Collapse

class BlockResponse: …

id: str

The id of the block.

value: str

Value of the block.

Deprecatedbase\_template\_id: Optional\[str\]

(Deprecated) The base template id of the block.

created\_by\_id: Optional\[str\]

The id of the user that made this Block.

Deprecateddeployment\_id: Optional\[str\]

(Deprecated) The id of the deployment.

description: Optional\[str\]

Description of the block.

Deprecatedentity\_id: Optional\[str\]

(Deprecated) The id of the entity within the template.

Deprecatedhidden: Optional\[bool\]

(Deprecated) If set to True, the block will be hidden.

is\_template: Optional\[bool\]

Whether the block is a template (e.g. saved human/persona options).

label: Optional\[str\]

Label of the block (e.g. 'human', 'persona') in the context window.

last\_updated\_by\_id: Optional\[str\]

The id of the user that last updated this Block.

limit: Optional\[int\]

Character limit of the block.

metadata: Optional\[Dict\[str, object\]\]

Metadata of the block.

Deprecatedpreserve\_on\_migration: Optional\[bool\]

(Deprecated) Preserve the block on template migration.

project\_id: Optional\[str\]

The associated project id.

Deprecatedread\_only: Optional\[bool\]

(Deprecated) Whether the agent has read-only access to the block.

tags: Optional\[List\[str\]\]

The tags associated with the block.

Deprecatedtemplate\_id: Optional\[str\]

(Deprecated) The id of the template.

Deprecatedtemplate\_name: Optional\[str\]

(Deprecated) The name of the block template (if it is a template).

class CreateBlock: …

Create a block

label: str

Label of the block.

value: str

Value of the block.

base\_template\_id: Optional\[str\]

The base template id of the block.

deployment\_id: Optional\[str\]

The id of the deployment.

description: Optional\[str\]

Description of the block.

entity\_id: Optional\[str\]

The id of the entity within the template.

hidden: Optional\[bool\]

If set to True, the block will be hidden.

is\_template: Optional\[bool\]

limit: Optional\[int\]

Character limit of the block.

metadata: Optional\[Dict\[str, object\]\]

Metadata of the block.

preserve\_on\_migration: Optional\[bool\]

Preserve the block on template migration.

project\_id: Optional\[str\]

The associated project id.

read\_only: Optional\[bool\]

Whether the agent has read-only access to the block.

tags: Optional\[SequenceNotStr\[str\]\]

The tags to associate with the block.

template\_id: Optional\[str\]

The id of the template.

template\_name: Optional\[str\]

Name of the block if it is a template.

#### BlocksAgents

##### [List Agents For Block](https://docs.letta.com/api/python/resources/blocks/subresources/agents/methods/list)

blocks.agents.list(strblock\_id, AgentListParams\*\*kwargs) \-> SyncArrayPage\[[AgentState](https://docs.letta.com/api/python/resources/agents#(resource)%20agents%20%3E%20(model)%20agent_state%20%3E%20(schema))\
\]

get/v1/blocks/{block\_id}/agents

---

# Archives | Letta Docs

[Skip to content](https://docs.letta.com/api/python/resources/archives#_top)

[API Reference](https://docs.letta.com/api/python)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

* * *

**Copy Markdown**

**View as Markdown**

Archives
========

##### [Create Archive](https://docs.letta.com/api/python/resources/archives/methods/create)

archives.create(ArchiveCreateParams\*\*kwargs) \-> [Archive](https://docs.letta.com/api/python/resources/archives#(resource)%20archives%20%3E%20(model)%20archive%20%3E%20(schema))

post/v1/archives/

##### [List Archives](https://docs.letta.com/api/python/resources/archives/methods/list)

archives.list(ArchiveListParams\*\*kwargs) \-> SyncArrayPage\[[Archive](https://docs.letta.com/api/python/resources/archives#(resource)%20archives%20%3E%20(model)%20archive%20%3E%20(schema))\
\]

get/v1/archives/

##### [Update Archive](https://docs.letta.com/api/python/resources/archives/methods/update)

archives.update(strarchive\_id, ArchiveUpdateParams\*\*kwargs) \-> [Archive](https://docs.letta.com/api/python/resources/archives#(resource)%20archives%20%3E%20(model)%20archive%20%3E%20(schema))

patch/v1/archives/{archive\_id}

##### [Retrieve Archive](https://docs.letta.com/api/python/resources/archives/methods/retrieve)

archives.retrieve(strarchive\_id) \-> [Archive](https://docs.letta.com/api/python/resources/archives#(resource)%20archives%20%3E%20(model)%20archive%20%3E%20(schema))

get/v1/archives/{archive\_id}

##### [Delete Archive](https://docs.letta.com/api/python/resources/archives/methods/delete)

archives.delete(strarchive\_id)

delete/v1/archives/{archive\_id}

##### ModelsExpand Collapse

class Archive: …

Representation of an archive - a collection of archival passages that can be shared between agents.

id: str

The human-friendly ID of the Archive

created\_at: datetime

The creation date of the archive

formatdate-time

name: str

The name of the archive

created\_by\_id: Optional\[str\]

The id of the user that made this object.

description: Optional\[str\]

A description of the archive

embedding\_config: Optional\[EmbeddingConfig\]

Configuration for embedding model connection and processing parameters.

embedding\_dim: int

The dimension of the embedding.

embedding\_endpoint\_type: Literal\["openai", "anthropic", "bedrock", 16 more\]

The endpoint type for the model.

Accepts one of the following:

"openai"

"anthropic"

"bedrock"

"google\_ai"

"google\_vertex"

"azure"

"groq"

"ollama"

"webui"

"webui-legacy"

"lmstudio"

"lmstudio-legacy"

"llamacpp"

"koboldcpp"

"vllm"

"hugging-face"

"mistral"

"together"

"pinecone"

embedding\_model: str

The model for the embedding.

azure\_deployment: Optional\[str\]

The Azure deployment for the model.

azure\_endpoint: Optional\[str\]

The Azure endpoint for the model.

azure\_version: Optional\[str\]

The Azure version for the model.

batch\_size: Optional\[int\]

The maximum batch size for processing embeddings.

embedding\_chunk\_size: Optional\[int\]

The chunk size of the embedding.

embedding\_endpoint: Optional\[str\]

The endpoint for the model (`None` if local).

handle: Optional\[str\]

The handle for this config, in the format provider/model-name.

last\_updated\_by\_id: Optional\[str\]

The id of the user that made this object.

metadata: Optional\[Dict\[str, object\]\]

Additional metadata

updated\_at: Optional\[datetime\]

The timestamp when the object was last updated.

formatdate-time

vector\_db\_provider: Optional\[VectorDBProvider\]

The vector database provider used for this archive's passages

Accepts one of the following:

"native"

"tpuf"

"pinecone"

Literal\["native", "tpuf", "pinecone"\]

Supported vector database providers for archival memory

Accepts one of the following:

"native"

"tpuf"

"pinecone"

#### ArchivesPassages

##### [Create Passage In Archive](https://docs.letta.com/api/python/resources/archives/subresources/passages/methods/create)

archives.passages.create(strarchive\_id, PassageCreateParams\*\*kwargs) \-> [Passage](https://docs.letta.com/api/python/resources/passages#(resource)%20passages%20%3E%20(model)%20passage%20%3E%20(schema))

post/v1/archives/{archive\_id}/passages

##### [Create Passages In Archive](https://docs.letta.com/api/python/resources/archives/subresources/passages/methods/create_many)

archives.passages.create\_many(strarchive\_id, PassageCreateManyParams\*\*kwargs) \-> [PassageCreateManyResponse](https://docs.letta.com/api/python/resources/archives#(resource)%20archives.passages%20%3E%20(model)%20passage_create_many_response%20%3E%20(schema))

post/v1/archives/{archive\_id}/passages/batch

##### [Delete Passage From Archive](https://docs.letta.com/api/python/resources/archives/subresources/passages/methods/delete)

archives.passages.delete(strpassage\_id, PassageDeleteParams\*\*kwargs)

delete/v1/archives/{archive\_id}/passages/{passage\_id}

---

# Blocks | Letta Docs

[Skip to content](https://docs.letta.com/api/typescript/resources/blocks#_top)

[API Reference](https://docs.letta.com/api/typescript)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

* * *

**Copy Markdown**

**View as Markdown**

Blocks
======

##### [List Blocks](https://docs.letta.com/api/typescript/resources/blocks/methods/list)

client.blocks.list(BlockListParams { after, before, connected\_to\_agents\_count\_eq, 16 more } query?, RequestOptionsoptions?): ArrayPage<[BlockResponse](https://docs.letta.com/api/typescript/resources/blocks#(resource)%20blocks%20%3E%20(model)%20block_response%20%3E%20(schema))
 { id, value, base\_template\_id, 16 more } \>

get/v1/blocks/

##### [Create Block](https://docs.letta.com/api/typescript/resources/blocks/methods/create)

client.blocks.create(BlockCreateParams { label, value, base\_template\_id, 13 more } body, RequestOptionsoptions?): [BlockResponse](https://docs.letta.com/api/typescript/resources/blocks#(resource)%20blocks%20%3E%20(model)%20block_response%20%3E%20(schema))
 { id, value, base\_template\_id, 16 more }

post/v1/blocks/

##### [Update Block](https://docs.letta.com/api/typescript/resources/blocks/methods/update)

client.blocks.update(stringblockID, BlockUpdateParams { base\_template\_id, deployment\_id, description, 13 more } body, RequestOptionsoptions?): [BlockResponse](https://docs.letta.com/api/typescript/resources/blocks#(resource)%20blocks%20%3E%20(model)%20block_response%20%3E%20(schema))
 { id, value, base\_template\_id, 16 more }

patch/v1/blocks/{block\_id}

##### [Delete Block](https://docs.letta.com/api/typescript/resources/blocks/methods/delete)

client.blocks.delete(stringblockID, RequestOptionsoptions?): [BlockDeleteResponse](https://docs.letta.com/api/typescript/resources/blocks#(resource)%20blocks%20%3E%20(model)%20block_delete_response%20%3E%20(schema))

delete/v1/blocks/{block\_id}

##### [Retrieve Block](https://docs.letta.com/api/typescript/resources/blocks/methods/retrieve)

client.blocks.retrieve(stringblockID, RequestOptionsoptions?): [BlockResponse](https://docs.letta.com/api/typescript/resources/blocks#(resource)%20blocks%20%3E%20(model)%20block_response%20%3E%20(schema))
 { id, value, base\_template\_id, 16 more }

get/v1/blocks/{block\_id}

##### ModelsExpand Collapse

BlockResponse { id, value, base\_template\_id, 16 more }

id: string

The id of the block.

value: string

Value of the block.

Deprecatedbase\_template\_id?: string | null

(Deprecated) The base template id of the block.

created\_by\_id?: string | null

The id of the user that made this Block.

Deprecateddeployment\_id?: string | null

(Deprecated) The id of the deployment.

description?: string | null

Description of the block.

Deprecatedentity\_id?: string | null

(Deprecated) The id of the entity within the template.

Deprecatedhidden?: boolean | null

(Deprecated) If set to True, the block will be hidden.

is\_template?: boolean

Whether the block is a template (e.g. saved human/persona options).

label?: string | null

Label of the block (e.g. 'human', 'persona') in the context window.

last\_updated\_by\_id?: string | null

The id of the user that last updated this Block.

limit?: number

Character limit of the block.

metadata?: Record<string, unknown\> | null

Metadata of the block.

Deprecatedpreserve\_on\_migration?: boolean | null

(Deprecated) Preserve the block on template migration.

project\_id?: string | null

The associated project id.

Deprecatedread\_only?: boolean

(Deprecated) Whether the agent has read-only access to the block.

tags?: Array<string\> | null

The tags associated with the block.

Deprecatedtemplate\_id?: string | null

(Deprecated) The id of the template.

Deprecatedtemplate\_name?: string | null

(Deprecated) The name of the block template (if it is a template).

CreateBlock { label, value, base\_template\_id, 13 more }

Create a block

label: string

Label of the block.

value: string

Value of the block.

base\_template\_id?: string | null

The base template id of the block.

deployment\_id?: string | null

The id of the deployment.

description?: string | null

Description of the block.

entity\_id?: string | null

The id of the entity within the template.

hidden?: boolean | null

If set to True, the block will be hidden.

is\_template?: boolean

limit?: number

Character limit of the block.

metadata?: Record<string, unknown\> | null

Metadata of the block.

preserve\_on\_migration?: boolean | null

Preserve the block on template migration.

project\_id?: string | null

The associated project id.

read\_only?: boolean

Whether the agent has read-only access to the block.

tags?: Array<string\> | null

The tags to associate with the block.

template\_id?: string | null

The id of the template.

template\_name?: string | null

Name of the block if it is a template.

#### BlocksAgents

##### [List Agents For Block](https://docs.letta.com/api/typescript/resources/blocks/subresources/agents/methods/list)

client.blocks.agents.list(stringblockID, AgentListParams { after, before, include, 4 more } query?, RequestOptionsoptions?): ArrayPage<[AgentState](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20agent_state%20%3E%20(schema))
 { id, agent\_type, blocks, 42 more } \>

get/v1/blocks/{block\_id}/agents

---

# Tools | Letta Docs

[Skip to content](https://docs.letta.com/api/typescript/resources/tools#_top)

[API Reference](https://docs.letta.com/api/typescript)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

* * *

**Copy Markdown**

**View as Markdown**

Tools
=====

##### [Delete Tool](https://docs.letta.com/api/typescript/resources/tools/methods/delete)

client.tools.delete(stringtoolID, RequestOptionsoptions?): [ToolDeleteResponse](https://docs.letta.com/api/typescript/resources/tools#(resource)%20tools%20%3E%20(model)%20tool_delete_response%20%3E%20(schema))

delete/v1/tools/{tool\_id}

##### [Retrieve Tool](https://docs.letta.com/api/typescript/resources/tools/methods/retrieve)

client.tools.retrieve(stringtoolID, RequestOptionsoptions?): [Tool](https://docs.letta.com/api/typescript/resources/tools#(resource)%20tools%20%3E%20(model)%20tool%20%3E%20(schema))
 { id, args\_json\_schema, created\_by\_id, 15 more }

get/v1/tools/{tool\_id}

##### [Update Tool](https://docs.letta.com/api/typescript/resources/tools/methods/update)

client.tools.update(stringtoolID, ToolUpdateParams { args\_json\_schema, default\_requires\_approval, description, 9 more } body, RequestOptionsoptions?): [Tool](https://docs.letta.com/api/typescript/resources/tools#(resource)%20tools%20%3E%20(model)%20tool%20%3E%20(schema))
 { id, args\_json\_schema, created\_by\_id, 15 more }

patch/v1/tools/{tool\_id}

##### [List Tools](https://docs.letta.com/api/typescript/resources/tools/methods/list)

client.tools.list(ToolListParams { after, before, exclude\_tool\_types, 9 more } query?, RequestOptionsoptions?): ArrayPage<[Tool](https://docs.letta.com/api/typescript/resources/tools#(resource)%20tools%20%3E%20(model)%20tool%20%3E%20(schema))
 { id, args\_json\_schema, created\_by\_id, 15 more } \>

get/v1/tools/

##### [Create Tool](https://docs.letta.com/api/typescript/resources/tools/methods/create)

client.tools.create(ToolCreateParams { source\_code, args\_json\_schema, default\_requires\_approval, 8 more } body, RequestOptionsoptions?): [Tool](https://docs.letta.com/api/typescript/resources/tools#(resource)%20tools%20%3E%20(model)%20tool%20%3E%20(schema))
 { id, args\_json\_schema, created\_by\_id, 15 more }

post/v1/tools/

##### [Upsert Tool](https://docs.letta.com/api/typescript/resources/tools/methods/upsert)

client.tools.upsert(ToolUpsertParams { source\_code, args\_json\_schema, default\_requires\_approval, 8 more } body, RequestOptionsoptions?): [Tool](https://docs.letta.com/api/typescript/resources/tools#(resource)%20tools%20%3E%20(model)%20tool%20%3E%20(schema))
 { id, args\_json\_schema, created\_by\_id, 15 more }

put/v1/tools/

##### [Search Tools](https://docs.letta.com/api/typescript/resources/tools/methods/search)

client.tools.search(ToolSearchParams { limit, query, search\_mode, 2 more } body, RequestOptionsoptions?): [ToolSearchResponse](https://docs.letta.com/api/typescript/resources/tools#(resource)%20tools%20%3E%20(model)%20tool_search_response%20%3E%20(schema))
 { combined\_score, tool, embedded\_text, 2 more }

post/v1/tools/search

##### ModelsExpand Collapse

NpmRequirement { name, version }

name: string

Name of the npm package.

minLength1

version?: string | null

Optional version of the package, following semantic versioning.

PipRequirement { name, version }

name: string

Name of the pip package.

minLength1

version?: string | null

Optional version of the package, following semantic versioning.

Tool { id, args\_json\_schema, created\_by\_id, 15 more }

Representation of a tool, which is a function that can be called by the agent.

id: string

The human-friendly ID of the Tool

args\_json\_schema?: Record<string, unknown\> | null

The args JSON schema of the function.

created\_by\_id?: string | null

The id of the user that made this Tool.

default\_requires\_approval?: boolean | null

Default value for whether or not executing this tool requires approval.

description?: string | null

The description of the tool.

enable\_parallel\_execution?: boolean | null

If set to True, then this tool will potentially be executed concurrently with other tools. Default False.

json\_schema?: Record<string, unknown\> | null

The JSON schema of the function.

last\_updated\_by\_id?: string | null

The id of the user that made this Tool.

metadata\_?: Record<string, unknown\> | null

A dictionary of additional metadata for the tool.

name?: string | null

The name of the function.

npm\_requirements?: Array<[NpmRequirement](https://docs.letta.com/api/typescript/resources/tools#(resource)%20tools%20%3E%20(model)%20npm_requirement%20%3E%20(schema))
 { name, version } \> | null

Optional list of npm packages required by this tool.

name: string

Name of the npm package.

minLength1

version?: string | null

Optional version of the package, following semantic versioning.

pip\_requirements?: Array<[PipRequirement](https://docs.letta.com/api/typescript/resources/tools#(resource)%20tools%20%3E%20(model)%20pip_requirement%20%3E%20(schema))
 { name, version } \> | null

Optional list of pip packages required by this tool.

name: string

Name of the pip package.

minLength1

version?: string | null

Optional version of the package, following semantic versioning.

project\_id?: string | null

The project id of the tool.

return\_char\_limit?: number

The maximum number of characters in the response.

maximum1000000

minimum1

source\_code?: string | null

The source code of the function.

source\_type?: string | null

The type of the source code.

tags?: Array<string\>

Metadata tags.

tool\_type?: [ToolType](https://docs.letta.com/api/typescript/resources/tools#(resource)%20tools%20%3E%20(model)%20tool_type%20%3E%20(schema))

The type of the tool.

Accepts one of the following:

"custom"

"letta\_core"

"letta\_memory\_core"

"letta\_multi\_agent\_core"

"letta\_sleeptime\_core"

"letta\_voice\_sleeptime\_core"

"letta\_builtin"

"letta\_files\_core"

"external\_langchain"

"external\_composio"

"external\_mcp"

ToolCreate { source\_code, args\_json\_schema, default\_requires\_approval, 8 more }

source\_code: string

The source code of the function.

args\_json\_schema?: Record<string, unknown\> | null

The args JSON schema of the function.

default\_requires\_approval?: boolean | null

Whether or not to require approval before executing this tool.

description?: string | null

The description of the tool.

enable\_parallel\_execution?: boolean | null

If set to True, then this tool will potentially be executed concurrently with other tools. Default False.

json\_schema?: Record<string, unknown\> | null

The JSON schema of the function (auto-generated from source\_code if not provided)

npm\_requirements?: Array<[NpmRequirement](https://docs.letta.com/api/typescript/resources/tools#(resource)%20tools%20%3E%20(model)%20npm_requirement%20%3E%20(schema))
 { name, version } \> | null

Optional list of npm packages required by this tool.

name: string

Name of the npm package.

minLength1

version?: string | null

Optional version of the package, following semantic versioning.

pip\_requirements?: Array<[PipRequirement](https://docs.letta.com/api/typescript/resources/tools#(resource)%20tools%20%3E%20(model)%20pip_requirement%20%3E%20(schema))
 { name, version } \> | null

Optional list of pip packages required by this tool.

name: string

Name of the pip package.

minLength1

version?: string | null

Optional version of the package, following semantic versioning.

return\_char\_limit?: number

The maximum number of characters in the response.

maximum1000000

minimum1

source\_type?: string

The source type of the function.

tags?: Array<string\> | null

Metadata tags.

ToolReturnMessage { id, date, status, 13 more }

A message representing the return value of a tool call (generated by Letta executing the requested tool).

Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional\[str\]): The name of the sender of the message tool\_return (str): The return value of the tool (deprecated, use tool\_returns) status (Literal\["success", "error"\]): The status of the tool call (deprecated, use tool\_returns) tool\_call\_id (str): A unique identifier for the tool call that generated this message (deprecated, use tool\_returns) stdout (Optional\[List(str)\]): Captured stdout (e.g. prints, logs) from the tool invocation (deprecated, use tool\_returns) stderr (Optional\[List(str)\]): Captured stderr from the tool invocation (deprecated, use tool\_returns) tool\_returns (Optional\[List\[ToolReturn\]\]): List of tool returns for multi-tool support

id: string

date: string

Deprecatedstatus: "success" | "error"

Accepts one of the following:

"success"

"error"

Deprecatedtool\_call\_id: string

Deprecatedtool\_return: string

is\_err?: boolean | null

message\_type?: "tool\_return\_message"

The type of the message.

name?: string | null

otid?: string | null

The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

run\_id?: string | null

sender\_id?: string | null

seq\_id?: number | null

Deprecatedstderr?: Array<string\> | null

Deprecatedstdout?: Array<string\> | null

step\_id?: string | null

tool\_returns?: Array<[ToolReturn](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20tool_return%20%3E%20(schema))
 { status, tool\_call\_id, tool\_return, 3 more } \> | null

status: "success" | "error"

Accepts one of the following:

"success"

"error"

tool\_call\_id: string

tool\_return: Array<[TextContent](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20text_content%20%3E%20(schema))
 { text, signature, type } | [ImageContent](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20image_content%20%3E%20(schema))
 { source, type } \> | string

The tool return value - either a string or list of content parts (text/image)

Accepts one of the following:

Array<[TextContent](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20text_content%20%3E%20(schema))
 { text, signature, type } | [ImageContent](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20image_content%20%3E%20(schema))
 { source, type } \>

TextContent { text, signature, type }

text: string

The text content of the message.

signature?: string | null

Stores a unique identifier for any reasoning associated with this text content.

type?: "text"

The type of the message.

ImageContent { source, type }

source: URLImage { url, type } | Base64Image { data, media\_type, detail, type } | LettaImage { file\_id, data, detail, 2 more }

The source of the image.

Accepts one of the following:

URLImage { url, type }

url: string

The URL of the image.

type?: "url"

The source type for the image.

Base64Image { data, media\_type, detail, type }

data: string

The base64 encoded image data.

media\_type: string

The media type for the image.

detail?: string | null

What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)

type?: "base64"

The source type for the image.

LettaImage { file\_id, data, detail, 2 more }

file\_id: string

The unique identifier of the image file persisted in storage.

data?: string | null

The base64 encoded image data.

detail?: string | null

What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)

media\_type?: string | null

The media type for the image.

type?: "letta"

The source type for the image.

type?: "image"

The type of the message.

string

stderr?: Array<string\> | null

stdout?: Array<string\> | null

type?: "tool"

The message type to be created.

ToolSearchRequest { limit, query, search\_mode, 2 more }

Request model for searching tools using semantic search.

limit?: number

Maximum number of results to return.

maximum100

minimum1

query?: string | null

Text query for semantic search.

search\_mode?: "vector" | "fts" | "hybrid"

Search mode: vector, fts, or hybrid.

Accepts one of the following:

"vector"

"fts"

"hybrid"

tags?: Array<string\> | null

Filter by tags (match any).

tool\_types?: Array<string\> | null

Filter by tool types (e.g., 'custom', 'letta\_core').

ToolSearchResult { combined\_score, tool, embedded\_text, 2 more }

Result from a tool search operation.

combined\_score: number

Combined relevance score (RRF for hybrid mode).

tool: [Tool](https://docs.letta.com/api/typescript/resources/tools#(resource)%20tools%20%3E%20(model)%20tool%20%3E%20(schema))
 { id, args\_json\_schema, created\_by\_id, 15 more }

The matched tool.

id: string

The human-friendly ID of the Tool

args\_json\_schema?: Record<string, unknown\> | null

The args JSON schema of the function.

created\_by\_id?: string | null

The id of the user that made this Tool.

default\_requires\_approval?: boolean | null

Default value for whether or not executing this tool requires approval.

description?: string | null

The description of the tool.

enable\_parallel\_execution?: boolean | null

If set to True, then this tool will potentially be executed concurrently with other tools. Default False.

json\_schema?: Record<string, unknown\> | null

The JSON schema of the function.

last\_updated\_by\_id?: string | null

The id of the user that made this Tool.

metadata\_?: Record<string, unknown\> | null

A dictionary of additional metadata for the tool.

name?: string | null

The name of the function.

npm\_requirements?: Array<[NpmRequirement](https://docs.letta.com/api/typescript/resources/tools#(resource)%20tools%20%3E%20(model)%20npm_requirement%20%3E%20(schema))
 { name, version } \> | null

Optional list of npm packages required by this tool.

name: string

Name of the npm package.

minLength1

version?: string | null

Optional version of the package, following semantic versioning.

pip\_requirements?: Array<[PipRequirement](https://docs.letta.com/api/typescript/resources/tools#(resource)%20tools%20%3E%20(model)%20pip_requirement%20%3E%20(schema))
 { name, version } \> | null

Optional list of pip packages required by this tool.

name: string

Name of the pip package.

minLength1

version?: string | null

Optional version of the package, following semantic versioning.

project\_id?: string | null

The project id of the tool.

return\_char\_limit?: number

The maximum number of characters in the response.

maximum1000000

minimum1

source\_code?: string | null

The source code of the function.

source\_type?: string | null

The type of the source code.

tags?: Array<string\>

Metadata tags.

tool\_type?: [ToolType](https://docs.letta.com/api/typescript/resources/tools#(resource)%20tools%20%3E%20(model)%20tool_type%20%3E%20(schema))

The type of the tool.

Accepts one of the following:

"custom"

"letta\_core"

"letta\_memory\_core"

"letta\_multi\_agent\_core"

"letta\_sleeptime\_core"

"letta\_voice\_sleeptime\_core"

"letta\_builtin"

"letta\_files\_core"

"external\_langchain"

"external\_composio"

"external\_mcp"

embedded\_text?: string | null

The embedded text content used for matching.

fts\_rank?: number | null

Full-text search rank position.

vector\_rank?: number | null

Vector search rank position.

ToolType = "custom" | "letta\_core" | "letta\_memory\_core" | 8 more

Accepts one of the following:

"custom"

"letta\_core"

"letta\_memory\_core"

"letta\_multi\_agent\_core"

"letta\_sleeptime\_core"

"letta\_voice\_sleeptime\_core"

"letta\_builtin"

"letta\_files\_core"

"external\_langchain"

"external\_composio"

"external\_mcp"

---

# Folders | Letta Docs

[Skip to content](https://docs.letta.com/api/python/resources/folders#_top)

[API Reference](https://docs.letta.com/api/python)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

* * *

**Copy Markdown**

**View as Markdown**

Folders
=======

##### [Retrieve Folder](https://docs.letta.com/api/python/resources/folders/methods/retrieve)

folders.retrieve(strfolder\_id) \-> [Folder](https://docs.letta.com/api/python/resources/folders#(resource)%20folders%20%3E%20(model)%20folder%20%3E%20(schema))

get/v1/folders/{folder\_id}

##### [Update Folder](https://docs.letta.com/api/python/resources/folders/methods/update)

folders.update(strfolder\_id, FolderUpdateParams\*\*kwargs) \-> [Folder](https://docs.letta.com/api/python/resources/folders#(resource)%20folders%20%3E%20(model)%20folder%20%3E%20(schema))

patch/v1/folders/{folder\_id}

##### [Delete Folder](https://docs.letta.com/api/python/resources/folders/methods/delete)

folders.delete(strfolder\_id) \-> object

delete/v1/folders/{folder\_id}

##### [List Folders](https://docs.letta.com/api/python/resources/folders/methods/list)

folders.list(FolderListParams\*\*kwargs) \-> SyncArrayPage\[[Folder](https://docs.letta.com/api/python/resources/folders#(resource)%20folders%20%3E%20(model)%20folder%20%3E%20(schema))\
\]

get/v1/folders/

##### [Create Folder](https://docs.letta.com/api/python/resources/folders/methods/create)

folders.create(FolderCreateParams\*\*kwargs) \-> [Folder](https://docs.letta.com/api/python/resources/folders#(resource)%20folders%20%3E%20(model)%20folder%20%3E%20(schema))

post/v1/folders/

##### ModelsExpand Collapse

class Folder: …

Representation of a folder, which is a collection of files and passages.

id: str

The human-friendly ID of the Source

embedding\_config: [EmbeddingConfig](https://docs.letta.com/api/python/resources/models#(resource)%20models%20%3E%20(model)%20embedding_config%20%3E%20(schema))

The embedding configuration used by the folder.

embedding\_dim: int

The dimension of the embedding.

embedding\_endpoint\_type: Literal\["openai", "anthropic", "bedrock", 16 more\]

The endpoint type for the model.

Accepts one of the following:

"openai"

"anthropic"

"bedrock"

"google\_ai"

"google\_vertex"

"azure"

"groq"

"ollama"

"webui"

"webui-legacy"

"lmstudio"

"lmstudio-legacy"

"llamacpp"

"koboldcpp"

"vllm"

"hugging-face"

"mistral"

"together"

"pinecone"

embedding\_model: str

The model for the embedding.

azure\_deployment: Optional\[str\]

The Azure deployment for the model.

azure\_endpoint: Optional\[str\]

The Azure endpoint for the model.

azure\_version: Optional\[str\]

The Azure version for the model.

batch\_size: Optional\[int\]

The maximum batch size for processing embeddings.

embedding\_chunk\_size: Optional\[int\]

The chunk size of the embedding.

embedding\_endpoint: Optional\[str\]

The endpoint for the model (`None` if local).

handle: Optional\[str\]

The handle for this config, in the format provider/model-name.

name: str

The name of the folder.

created\_at: Optional\[datetime\]

The timestamp when the folder was created.

formatdate-time

created\_by\_id: Optional\[str\]

The id of the user that made this Tool.

description: Optional\[str\]

The description of the folder.

instructions: Optional\[str\]

Instructions for how to use the folder.

last\_updated\_by\_id: Optional\[str\]

The id of the user that made this Tool.

metadata: Optional\[Dict\[str, object\]\]

Metadata associated with the folder.

updated\_at: Optional\[datetime\]

The timestamp when the folder was last updated.

formatdate-time

#### FoldersFiles

##### [Upload File To Folder](https://docs.letta.com/api/python/resources/folders/subresources/files/methods/upload)

folders.files.upload(strfolder\_id, FileUploadParams\*\*kwargs) \-> [FileUploadResponse](https://docs.letta.com/api/python/resources/folders#(resource)%20folders.files%20%3E%20(model)%20file_upload_response%20%3E%20(schema))

post/v1/folders/{folder\_id}/upload

##### [List Files For Folder](https://docs.letta.com/api/python/resources/folders/subresources/files/methods/list)

folders.files.list(strfolder\_id, FileListParams\*\*kwargs) \-> SyncArrayPage\[[FileListResponse](https://docs.letta.com/api/python/resources/folders#(resource)%20folders.files%20%3E%20(model)%20file_list_response%20%3E%20(schema))\
\]

get/v1/folders/{folder\_id}/files

##### [Retrieve File](https://docs.letta.com/api/python/resources/folders/subresources/files/methods/retrieve)

folders.files.retrieve(strfile\_id, FileRetrieveParams\*\*kwargs) \-> [FileRetrieveResponse](https://docs.letta.com/api/python/resources/folders#(resource)%20folders.files%20%3E%20(model)%20file_retrieve_response%20%3E%20(schema))

get/v1/folders/{folder\_id}/files/{file\_id}

##### [Delete File From Folder](https://docs.letta.com/api/python/resources/folders/subresources/files/methods/delete)

folders.files.delete(strfile\_id, FileDeleteParams\*\*kwargs)

delete/v1/folders/{folder\_id}/{file\_id}

#### FoldersAgents

##### [List Agents For Folder](https://docs.letta.com/api/python/resources/folders/subresources/agents/methods/list)

folders.agents.list(strfolder\_id, AgentListParams\*\*kwargs) \-> [AgentListResponse](https://docs.letta.com/api/python/resources/folders#(resource)%20folders.agents%20%3E%20(model)%20agent_list_response%20%3E%20(schema))

get/v1/folders/{folder\_id}/agents

---

# Folders | Letta Docs

[Skip to content](https://docs.letta.com/api/typescript/resources/folders#_top)

[API Reference](https://docs.letta.com/api/typescript)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

* * *

**Copy Markdown**

**View as Markdown**

Folders
=======

##### [Retrieve Folder](https://docs.letta.com/api/typescript/resources/folders/methods/retrieve)

client.folders.retrieve(stringfolderID, RequestOptionsoptions?): [Folder](https://docs.letta.com/api/typescript/resources/folders#(resource)%20folders%20%3E%20(model)%20folder%20%3E%20(schema))
 { id, embedding\_config, name, 7 more }

get/v1/folders/{folder\_id}

##### [Update Folder](https://docs.letta.com/api/typescript/resources/folders/methods/update)

client.folders.update(stringfolderID, FolderUpdateParams { description, embedding\_config, instructions, 2 more } body, RequestOptionsoptions?): [Folder](https://docs.letta.com/api/typescript/resources/folders#(resource)%20folders%20%3E%20(model)%20folder%20%3E%20(schema))
 { id, embedding\_config, name, 7 more }

patch/v1/folders/{folder\_id}

##### [Delete Folder](https://docs.letta.com/api/typescript/resources/folders/methods/delete)

client.folders.delete(stringfolderID, RequestOptionsoptions?): [FolderDeleteResponse](https://docs.letta.com/api/typescript/resources/folders#(resource)%20folders%20%3E%20(model)%20folder_delete_response%20%3E%20(schema))

delete/v1/folders/{folder\_id}

##### [List Folders](https://docs.letta.com/api/typescript/resources/folders/methods/list)

client.folders.list(FolderListParams { after, before, limit, 3 more } query?, RequestOptionsoptions?): ArrayPage<[Folder](https://docs.letta.com/api/typescript/resources/folders#(resource)%20folders%20%3E%20(model)%20folder%20%3E%20(schema))
 { id, embedding\_config, name, 7 more } \>

get/v1/folders/

##### [Create Folder](https://docs.letta.com/api/typescript/resources/folders/methods/create)

client.folders.create(FolderCreateParams { name, description, embedding, 4 more } body, RequestOptionsoptions?): [Folder](https://docs.letta.com/api/typescript/resources/folders#(resource)%20folders%20%3E%20(model)%20folder%20%3E%20(schema))
 { id, embedding\_config, name, 7 more }

post/v1/folders/

##### ModelsExpand Collapse

Folder { id, embedding\_config, name, 7 more }

Representation of a folder, which is a collection of files and passages.

id: string

The human-friendly ID of the Source

embedding\_config: [EmbeddingConfig](https://docs.letta.com/api/typescript/resources/models#(resource)%20models%20%3E%20(model)%20embedding_config%20%3E%20(schema))
 { embedding\_dim, embedding\_endpoint\_type, embedding\_model, 7 more }

The embedding configuration used by the folder.

embedding\_dim: number

The dimension of the embedding.

embedding\_endpoint\_type: "openai" | "anthropic" | "bedrock" | 16 more

The endpoint type for the model.

Accepts one of the following:

"openai"

"anthropic"

"bedrock"

"google\_ai"

"google\_vertex"

"azure"

"groq"

"ollama"

"webui"

"webui-legacy"

"lmstudio"

"lmstudio-legacy"

"llamacpp"

"koboldcpp"

"vllm"

"hugging-face"

"mistral"

"together"

"pinecone"

embedding\_model: string

The model for the embedding.

azure\_deployment?: string | null

The Azure deployment for the model.

azure\_endpoint?: string | null

The Azure endpoint for the model.

azure\_version?: string | null

The Azure version for the model.

batch\_size?: number

The maximum batch size for processing embeddings.

embedding\_chunk\_size?: number | null

The chunk size of the embedding.

embedding\_endpoint?: string | null

The endpoint for the model (`None` if local).

handle?: string | null

The handle for this config, in the format provider/model-name.

name: string

The name of the folder.

created\_at?: string | null

The timestamp when the folder was created.

formatdate-time

created\_by\_id?: string | null

The id of the user that made this Tool.

description?: string | null

The description of the folder.

instructions?: string | null

Instructions for how to use the folder.

last\_updated\_by\_id?: string | null

The id of the user that made this Tool.

metadata?: Record<string, unknown\> | null

Metadata associated with the folder.

updated\_at?: string | null

The timestamp when the folder was last updated.

formatdate-time

#### FoldersFiles

##### [Upload File To Folder](https://docs.letta.com/api/typescript/resources/folders/subresources/files/methods/upload)

client.folders.files.upload(stringfolderID, FileUploadParams { file, duplicate\_handling, name } params, RequestOptionsoptions?): [FileUploadResponse](https://docs.letta.com/api/typescript/resources/folders#(resource)%20folders.files%20%3E%20(model)%20file_upload_response%20%3E%20(schema))
 { id, source\_id, chunks\_embedded, 13 more }

post/v1/folders/{folder\_id}/upload

##### [List Files For Folder](https://docs.letta.com/api/typescript/resources/folders/subresources/files/methods/list)

client.folders.files.list(stringfolderID, FileListParams { after, before, include\_content, 3 more } query?, RequestOptionsoptions?): ArrayPage<[FileListResponse](https://docs.letta.com/api/typescript/resources/folders#(resource)%20folders.files%20%3E%20(model)%20file_list_response%20%3E%20(schema))
 { id, source\_id, chunks\_embedded, 13 more } \>

get/v1/folders/{folder\_id}/files

##### [Retrieve File](https://docs.letta.com/api/typescript/resources/folders/subresources/files/methods/retrieve)

client.folders.files.retrieve(stringfileID, FileRetrieveParams { folder\_id, include\_content } params, RequestOptionsoptions?): [FileRetrieveResponse](https://docs.letta.com/api/typescript/resources/folders#(resource)%20folders.files%20%3E%20(model)%20file_retrieve_response%20%3E%20(schema))
 { id, source\_id, chunks\_embedded, 13 more }

get/v1/folders/{folder\_id}/files/{file\_id}

##### [Delete File From Folder](https://docs.letta.com/api/typescript/resources/folders/subresources/files/methods/delete)

client.folders.files.delete(stringfileID, FileDeleteParams { folder\_id } params, RequestOptionsoptions?): void

delete/v1/folders/{folder\_id}/{file\_id}

#### FoldersAgents

##### [List Agents For Folder](https://docs.letta.com/api/typescript/resources/folders/subresources/agents/methods/list)

client.folders.agents.list(stringfolderID, AgentListParams { after, before, limit, 2 more } query?, RequestOptionsoptions?): [AgentListResponse](https://docs.letta.com/api/typescript/resources/folders#(resource)%20folders.agents%20%3E%20(model)%20agent_list_response%20%3E%20(schema))

get/v1/folders/{folder\_id}/agents

---

# Archives | Letta Docs

[Skip to content](https://docs.letta.com/api/typescript/resources/archives#_top)

[API Reference](https://docs.letta.com/api/typescript)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

* * *

**Copy Markdown**

**View as Markdown**

Archives
========

##### [Create Archive](https://docs.letta.com/api/typescript/resources/archives/methods/create)

client.archives.create(ArchiveCreateParams { name, description, embedding, embedding\_config } body, RequestOptionsoptions?): [Archive](https://docs.letta.com/api/typescript/resources/archives#(resource)%20archives%20%3E%20(model)%20archive%20%3E%20(schema))
 { id, created\_at, name, 7 more }

post/v1/archives/

##### [List Archives](https://docs.letta.com/api/typescript/resources/archives/methods/list)

client.archives.list(ArchiveListParams { after, agent\_id, before, 4 more } query?, RequestOptionsoptions?): ArrayPage<[Archive](https://docs.letta.com/api/typescript/resources/archives#(resource)%20archives%20%3E%20(model)%20archive%20%3E%20(schema))
 { id, created\_at, name, 7 more } \>

get/v1/archives/

##### [Update Archive](https://docs.letta.com/api/typescript/resources/archives/methods/update)

client.archives.update(stringarchiveID, ArchiveUpdateParams { description, name } body, RequestOptionsoptions?): [Archive](https://docs.letta.com/api/typescript/resources/archives#(resource)%20archives%20%3E%20(model)%20archive%20%3E%20(schema))
 { id, created\_at, name, 7 more }

patch/v1/archives/{archive\_id}

##### [Retrieve Archive](https://docs.letta.com/api/typescript/resources/archives/methods/retrieve)

client.archives.retrieve(stringarchiveID, RequestOptionsoptions?): [Archive](https://docs.letta.com/api/typescript/resources/archives#(resource)%20archives%20%3E%20(model)%20archive%20%3E%20(schema))
 { id, created\_at, name, 7 more }

get/v1/archives/{archive\_id}

##### [Delete Archive](https://docs.letta.com/api/typescript/resources/archives/methods/delete)

client.archives.delete(stringarchiveID, RequestOptionsoptions?): void

delete/v1/archives/{archive\_id}

##### ModelsExpand Collapse

Archive { id, created\_at, name, 7 more }

Representation of an archive - a collection of archival passages that can be shared between agents.

id: string

The human-friendly ID of the Archive

created\_at: string

The creation date of the archive

formatdate-time

name: string

The name of the archive

created\_by\_id?: string | null

The id of the user that made this object.

description?: string | null

A description of the archive

embedding\_config?: [EmbeddingConfig](https://docs.letta.com/api/typescript/resources/models#(resource)%20models%20%3E%20(model)%20embedding_config%20%3E%20(schema))
 { embedding\_dim, embedding\_endpoint\_type, embedding\_model, 7 more } | null

Configuration for embedding model connection and processing parameters.

embedding\_dim: number

The dimension of the embedding.

embedding\_endpoint\_type: "openai" | "anthropic" | "bedrock" | 16 more

The endpoint type for the model.

Accepts one of the following:

"openai"

"anthropic"

"bedrock"

"google\_ai"

"google\_vertex"

"azure"

"groq"

"ollama"

"webui"

"webui-legacy"

"lmstudio"

"lmstudio-legacy"

"llamacpp"

"koboldcpp"

"vllm"

"hugging-face"

"mistral"

"together"

"pinecone"

embedding\_model: string

The model for the embedding.

azure\_deployment?: string | null

The Azure deployment for the model.

azure\_endpoint?: string | null

The Azure endpoint for the model.

azure\_version?: string | null

The Azure version for the model.

batch\_size?: number

The maximum batch size for processing embeddings.

embedding\_chunk\_size?: number | null

The chunk size of the embedding.

embedding\_endpoint?: string | null

The endpoint for the model (`None` if local).

handle?: string | null

The handle for this config, in the format provider/model-name.

last\_updated\_by\_id?: string | null

The id of the user that made this object.

metadata?: Record<string, unknown\> | null

Additional metadata

updated\_at?: string | null

The timestamp when the object was last updated.

formatdate-time

vector\_db\_provider?: [VectorDBProvider](https://docs.letta.com/api/typescript/resources/archives#(resource)%20archives%20%3E%20(model)%20vector_db_provider%20%3E%20(schema))

The vector database provider used for this archive's passages

Accepts one of the following:

"native"

"tpuf"

"pinecone"

VectorDBProvider = "native" | "tpuf" | "pinecone"

Supported vector database providers for archival memory

Accepts one of the following:

"native"

"tpuf"

"pinecone"

#### ArchivesPassages

##### [Create Passage In Archive](https://docs.letta.com/api/typescript/resources/archives/subresources/passages/methods/create)

client.archives.passages.create(stringarchiveID, PassageCreateParams { text, created\_at, metadata, tags } body, RequestOptionsoptions?): [Passage](https://docs.letta.com/api/typescript/resources/passages#(resource)%20passages%20%3E%20(model)%20passage%20%3E%20(schema))
 { embedding, embedding\_config, text, 12 more }

post/v1/archives/{archive\_id}/passages

##### [Create Passages In Archive](https://docs.letta.com/api/typescript/resources/archives/subresources/passages/methods/create_many)

client.archives.passages.createMany(stringarchiveID, PassageCreateManyParams { passages } body, RequestOptionsoptions?): [PassageCreateManyResponse](https://docs.letta.com/api/typescript/resources/archives#(resource)%20archives.passages%20%3E%20(model)%20passage_create_many_response%20%3E%20(schema))
 { embedding, embedding\_config, text, 12 more }

post/v1/archives/{archive\_id}/passages/batch

##### [Delete Passage From Archive](https://docs.letta.com/api/typescript/resources/archives/subresources/passages/methods/delete)

client.archives.passages.delete(stringpassageID, PassageDeleteParams { archive\_id } params, RequestOptionsoptions?): void

delete/v1/archives/{archive\_id}/passages/{passage\_id}

---

# Tools | Letta Docs

[Skip to content](https://docs.letta.com/api/python/resources/tools#_top)

[API Reference](https://docs.letta.com/api/python)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

* * *

**Copy Markdown**

**View as Markdown**

Tools
=====

##### [Delete Tool](https://docs.letta.com/api/python/resources/tools/methods/delete)

tools.delete(strtool\_id) \-> object

delete/v1/tools/{tool\_id}

##### [Retrieve Tool](https://docs.letta.com/api/python/resources/tools/methods/retrieve)

tools.retrieve(strtool\_id) \-> [Tool](https://docs.letta.com/api/python/resources/tools#(resource)%20tools%20%3E%20(model)%20tool%20%3E%20(schema))

get/v1/tools/{tool\_id}

##### [Update Tool](https://docs.letta.com/api/python/resources/tools/methods/update)

tools.update(strtool\_id, ToolUpdateParams\*\*kwargs) \-> [Tool](https://docs.letta.com/api/python/resources/tools#(resource)%20tools%20%3E%20(model)%20tool%20%3E%20(schema))

patch/v1/tools/{tool\_id}

##### [List Tools](https://docs.letta.com/api/python/resources/tools/methods/list)

tools.list(ToolListParams\*\*kwargs) \-> SyncArrayPage\[[Tool](https://docs.letta.com/api/python/resources/tools#(resource)%20tools%20%3E%20(model)%20tool%20%3E%20(schema))\
\]

get/v1/tools/

##### [Create Tool](https://docs.letta.com/api/python/resources/tools/methods/create)

tools.create(ToolCreateParams\*\*kwargs) \-> [Tool](https://docs.letta.com/api/python/resources/tools#(resource)%20tools%20%3E%20(model)%20tool%20%3E%20(schema))

post/v1/tools/

##### [Upsert Tool](https://docs.letta.com/api/python/resources/tools/methods/upsert)

tools.upsert(ToolUpsertParams\*\*kwargs) \-> [Tool](https://docs.letta.com/api/python/resources/tools#(resource)%20tools%20%3E%20(model)%20tool%20%3E%20(schema))

put/v1/tools/

##### [Search Tools](https://docs.letta.com/api/python/resources/tools/methods/search)

tools.search(ToolSearchParams\*\*kwargs) \-> [ToolSearchResponse](https://docs.letta.com/api/python/resources/tools#(resource)%20tools%20%3E%20(model)%20tool_search_response%20%3E%20(schema))

post/v1/tools/search

##### ModelsExpand Collapse

class NpmRequirement: …

name: str

Name of the npm package.

minLength1

version: Optional\[str\]

Optional version of the package, following semantic versioning.

class PipRequirement: …

name: str

Name of the pip package.

minLength1

version: Optional\[str\]

Optional version of the package, following semantic versioning.

class Tool: …

Representation of a tool, which is a function that can be called by the agent.

id: str

The human-friendly ID of the Tool

args\_json\_schema: Optional\[Dict\[str, object\]\]

The args JSON schema of the function.

created\_by\_id: Optional\[str\]

The id of the user that made this Tool.

default\_requires\_approval: Optional\[bool\]

Default value for whether or not executing this tool requires approval.

description: Optional\[str\]

The description of the tool.

enable\_parallel\_execution: Optional\[bool\]

If set to True, then this tool will potentially be executed concurrently with other tools. Default False.

json\_schema: Optional\[Dict\[str, object\]\]

The JSON schema of the function.

last\_updated\_by\_id: Optional\[str\]

The id of the user that made this Tool.

metadata: Optional\[Dict\[str, object\]\]

A dictionary of additional metadata for the tool.

name: Optional\[str\]

The name of the function.

npm\_requirements: Optional\[List\[[NpmRequirement](https://docs.letta.com/api/python/resources/tools#(resource)%20tools%20%3E%20(model)%20npm_requirement%20%3E%20(schema))\
\]\]

Optional list of npm packages required by this tool.

name: str

Name of the npm package.

minLength1

version: Optional\[str\]

Optional version of the package, following semantic versioning.

pip\_requirements: Optional\[List\[[PipRequirement](https://docs.letta.com/api/python/resources/tools#(resource)%20tools%20%3E%20(model)%20pip_requirement%20%3E%20(schema))\
\]\]

Optional list of pip packages required by this tool.

name: str

Name of the pip package.

minLength1

version: Optional\[str\]

Optional version of the package, following semantic versioning.

project\_id: Optional\[str\]

The project id of the tool.

return\_char\_limit: Optional\[int\]

The maximum number of characters in the response.

maximum1000000

minimum1

source\_code: Optional\[str\]

The source code of the function.

source\_type: Optional\[str\]

The type of the source code.

tags: Optional\[List\[str\]\]

Metadata tags.

tool\_type: Optional\[ToolType\]

The type of the tool.

Accepts one of the following:

"custom"

"letta\_core"

"letta\_memory\_core"

"letta\_multi\_agent\_core"

"letta\_sleeptime\_core"

"letta\_voice\_sleeptime\_core"

"letta\_builtin"

"letta\_files\_core"

"external\_langchain"

"external\_composio"

"external\_mcp"

class ToolCreate: …

source\_code: str

The source code of the function.

args\_json\_schema: Optional\[Dict\[str, object\]\]

The args JSON schema of the function.

default\_requires\_approval: Optional\[bool\]

Whether or not to require approval before executing this tool.

description: Optional\[str\]

The description of the tool.

enable\_parallel\_execution: Optional\[bool\]

If set to True, then this tool will potentially be executed concurrently with other tools. Default False.

json\_schema: Optional\[Dict\[str, object\]\]

The JSON schema of the function (auto-generated from source\_code if not provided)

npm\_requirements: Optional\[List\[[NpmRequirement](https://docs.letta.com/api/python/resources/tools#(resource)%20tools%20%3E%20(model)%20npm_requirement%20%3E%20(schema))\
\]\]

Optional list of npm packages required by this tool.

name: str

Name of the npm package.

minLength1

version: Optional\[str\]

Optional version of the package, following semantic versioning.

pip\_requirements: Optional\[List\[[PipRequirement](https://docs.letta.com/api/python/resources/tools#(resource)%20tools%20%3E%20(model)%20pip_requirement%20%3E%20(schema))\
\]\]

Optional list of pip packages required by this tool.

name: str

Name of the pip package.

minLength1

version: Optional\[str\]

Optional version of the package, following semantic versioning.

return\_char\_limit: Optional\[int\]

The maximum number of characters in the response.

maximum1000000

minimum1

source\_type: Optional\[str\]

The source type of the function.

tags: Optional\[List\[str\]\]

Metadata tags.

class ToolReturnMessage: …

A message representing the return value of a tool call (generated by Letta executing the requested tool).

Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional\[str\]): The name of the sender of the message tool\_return (str): The return value of the tool (deprecated, use tool\_returns) status (Literal\["success", "error"\]): The status of the tool call (deprecated, use tool\_returns) tool\_call\_id (str): A unique identifier for the tool call that generated this message (deprecated, use tool\_returns) stdout (Optional\[List(str)\]): Captured stdout (e.g. prints, logs) from the tool invocation (deprecated, use tool\_returns) stderr (Optional\[List(str)\]): Captured stderr from the tool invocation (deprecated, use tool\_returns) tool\_returns (Optional\[List\[ToolReturn\]\]): List of tool returns for multi-tool support

id: str

date: datetime

Deprecatedstatus: Literal\["success", "error"\]

Accepts one of the following:

"success"

"error"

Deprecatedtool\_call\_id: str

Deprecatedtool\_return: str

is\_err: Optional\[bool\]

message\_type: Optional\[Literal\["tool\_return\_message"\]\]

The type of the message.

name: Optional\[str\]

otid: Optional\[str\]

The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

run\_id: Optional\[str\]

sender\_id: Optional\[str\]

seq\_id: Optional\[int\]

Deprecatedstderr: Optional\[List\[str\]\]

Deprecatedstdout: Optional\[List\[str\]\]

step\_id: Optional\[str\]

tool\_returns: Optional\[List\[[ToolReturn](https://docs.letta.com/api/python/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20tool_return%20%3E%20(schema))\
\]\]

status: Literal\["success", "error"\]

Accepts one of the following:

"success"

"error"

tool\_call\_id: str

tool\_return: Union\[List\[ToolReturnUnionMember0\], str\]

The tool return value - either a string or list of content parts (text/image)

Accepts one of the following:

List\[ToolReturnUnionMember0\]

Accepts one of the following:

class TextContent: …

text: str

The text content of the message.

signature: Optional\[str\]

Stores a unique identifier for any reasoning associated with this text content.

type: Optional\[Literal\["text"\]\]

The type of the message.

class ImageContent: …

source: Source

The source of the image.

Accepts one of the following:

class SourceURLImage: …

url: str

The URL of the image.

type: Optional\[Literal\["url"\]\]

The source type for the image.

class SourceBase64Image: …

data: str

The base64 encoded image data.

media\_type: str

The media type for the image.

detail: Optional\[str\]

What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)

type: Optional\[Literal\["base64"\]\]

The source type for the image.

class SourceLettaImage: …

file\_id: str

The unique identifier of the image file persisted in storage.

data: Optional\[str\]

The base64 encoded image data.

detail: Optional\[str\]

What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)

media\_type: Optional\[str\]

The media type for the image.

type: Optional\[Literal\["letta"\]\]

The source type for the image.

type: Optional\[Literal\["image"\]\]

The type of the message.

str

stderr: Optional\[List\[str\]\]

stdout: Optional\[List\[str\]\]

type: Optional\[Literal\["tool"\]\]

The message type to be created.

class ToolSearchRequest: …

Request model for searching tools using semantic search.

limit: Optional\[int\]

Maximum number of results to return.

maximum100

minimum1

query: Optional\[str\]

Text query for semantic search.

search\_mode: Optional\[Literal\["vector", "fts", "hybrid"\]\]

Search mode: vector, fts, or hybrid.

Accepts one of the following:

"vector"

"fts"

"hybrid"

tags: Optional\[List\[str\]\]

Filter by tags (match any).

tool\_types: Optional\[List\[str\]\]

Filter by tool types (e.g., 'custom', 'letta\_core').

class ToolSearchResult: …

Result from a tool search operation.

combined\_score: float

Combined relevance score (RRF for hybrid mode).

tool: [Tool](https://docs.letta.com/api/python/resources/tools#(resource)%20tools%20%3E%20(model)%20tool%20%3E%20(schema))

The matched tool.

id: str

The human-friendly ID of the Tool

args\_json\_schema: Optional\[Dict\[str, object\]\]

The args JSON schema of the function.

created\_by\_id: Optional\[str\]

The id of the user that made this Tool.

default\_requires\_approval: Optional\[bool\]

Default value for whether or not executing this tool requires approval.

description: Optional\[str\]

The description of the tool.

enable\_parallel\_execution: Optional\[bool\]

If set to True, then this tool will potentially be executed concurrently with other tools. Default False.

json\_schema: Optional\[Dict\[str, object\]\]

The JSON schema of the function.

last\_updated\_by\_id: Optional\[str\]

The id of the user that made this Tool.

metadata: Optional\[Dict\[str, object\]\]

A dictionary of additional metadata for the tool.

name: Optional\[str\]

The name of the function.

npm\_requirements: Optional\[List\[[NpmRequirement](https://docs.letta.com/api/python/resources/tools#(resource)%20tools%20%3E%20(model)%20npm_requirement%20%3E%20(schema))\
\]\]

Optional list of npm packages required by this tool.

name: str

Name of the npm package.

minLength1

version: Optional\[str\]

Optional version of the package, following semantic versioning.

pip\_requirements: Optional\[List\[[PipRequirement](https://docs.letta.com/api/python/resources/tools#(resource)%20tools%20%3E%20(model)%20pip_requirement%20%3E%20(schema))\
\]\]

Optional list of pip packages required by this tool.

name: str

Name of the pip package.

minLength1

version: Optional\[str\]

Optional version of the package, following semantic versioning.

project\_id: Optional\[str\]

The project id of the tool.

return\_char\_limit: Optional\[int\]

The maximum number of characters in the response.

maximum1000000

minimum1

source\_code: Optional\[str\]

The source code of the function.

source\_type: Optional\[str\]

The type of the source code.

tags: Optional\[List\[str\]\]

Metadata tags.

tool\_type: Optional\[ToolType\]

The type of the tool.

Accepts one of the following:

"custom"

"letta\_core"

"letta\_memory\_core"

"letta\_multi\_agent\_core"

"letta\_sleeptime\_core"

"letta\_voice\_sleeptime\_core"

"letta\_builtin"

"letta\_files\_core"

"external\_langchain"

"external\_composio"

"external\_mcp"

embedded\_text: Optional\[str\]

The embedded text content used for matching.

fts\_rank: Optional\[int\]

Full-text search rank position.

vector\_rank: Optional\[int\]

Vector search rank position.

Literal\["custom", "letta\_core", "letta\_memory\_core", 8 more\]

Accepts one of the following:

"custom"

"letta\_core"

"letta\_memory\_core"

"letta\_multi\_agent\_core"

"letta\_sleeptime\_core"

"letta\_voice\_sleeptime\_core"

"letta\_builtin"

"letta\_files\_core"

"external\_langchain"

"external\_composio"

"external\_mcp"

---

# Models | Letta Docs

[Skip to content](https://docs.letta.com/api/typescript/resources/models#_top)

[API Reference](https://docs.letta.com/api/typescript)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

* * *

**Copy Markdown**

**View as Markdown**

Models
======

##### [List Llm Models](https://docs.letta.com/api/typescript/resources/models/methods/list)

client.models.list(ModelListParams { provider\_category, provider\_name, provider\_type } query?, RequestOptionsoptions?): [ModelListResponse](https://docs.letta.com/api/typescript/resources/models#(resource)%20models%20%3E%20(model)%20model_list_response%20%3E%20(schema))
 { context\_window, max\_context\_window, model, 28 more }

get/v1/models/

##### ModelsExpand Collapse

EmbeddingConfig { embedding\_dim, embedding\_endpoint\_type, embedding\_model, 7 more }

Configuration for embedding model connection and processing parameters.

embedding\_dim: number

The dimension of the embedding.

embedding\_endpoint\_type: "openai" | "anthropic" | "bedrock" | 16 more

The endpoint type for the model.

Accepts one of the following:

"openai"

"anthropic"

"bedrock"

"google\_ai"

"google\_vertex"

"azure"

"groq"

"ollama"

"webui"

"webui-legacy"

"lmstudio"

"lmstudio-legacy"

"llamacpp"

"koboldcpp"

"vllm"

"hugging-face"

"mistral"

"together"

"pinecone"

embedding\_model: string

The model for the embedding.

azure\_deployment?: string | null

The Azure deployment for the model.

azure\_endpoint?: string | null

The Azure endpoint for the model.

azure\_version?: string | null

The Azure version for the model.

batch\_size?: number

The maximum batch size for processing embeddings.

embedding\_chunk\_size?: number | null

The chunk size of the embedding.

embedding\_endpoint?: string | null

The endpoint for the model (`None` if local).

handle?: string | null

The handle for this config, in the format provider/model-name.

EmbeddingModel { display\_name, embedding\_dim, embedding\_endpoint\_type, 12 more }

display\_name: string

Display name for the model shown in UI

embedding\_dim: number

The dimension of the embedding

Deprecatedembedding\_endpoint\_type: "openai" | "anthropic" | "bedrock" | 16 more

Deprecated: Use 'provider\_type' field instead. The endpoint type for the embedding model.

Accepts one of the following:

"openai"

"anthropic"

"bedrock"

"google\_ai"

"google\_vertex"

"azure"

"groq"

"ollama"

"webui"

"webui-legacy"

"lmstudio"

"lmstudio-legacy"

"llamacpp"

"koboldcpp"

"vllm"

"hugging-face"

"mistral"

"together"

"pinecone"

Deprecatedembedding\_model: string

Deprecated: Use 'name' field instead. Embedding model name.

name: string

The actual model name used by the provider

provider\_name: string

The name of the provider

provider\_type: [ProviderType](https://docs.letta.com/api/typescript/resources/models#(resource)%20models%20%3E%20(model)%20provider_type%20%3E%20(schema))

The type of the provider

Accepts one of the following:

"anthropic"

"azure"

"baseten"

"bedrock"

"cerebras"

"chatgpt\_oauth"

"deepseek"

"fireworks"

"google\_ai"

"google\_vertex"

"groq"

"hugging-face"

"letta"

"lmstudio\_openai"

"minimax"

"mistral"

"ollama"

"openai"

"together"

"vllm"

"sglang"

"openrouter"

"xai"

"zai"

"zai\_coding"

Deprecatedazure\_deployment?: string | null

Deprecated: The Azure deployment for the model.

Deprecatedazure\_endpoint?: string | null

Deprecated: The Azure endpoint for the model.

Deprecatedazure\_version?: string | null

Deprecated: The Azure version for the model.

Deprecatedbatch\_size?: number

Deprecated: The maximum batch size for processing embeddings.

Deprecatedembedding\_chunk\_size?: number | null

Deprecated: The chunk size of the embedding.

Deprecatedembedding\_endpoint?: string | null

Deprecated: The endpoint for the model.

handle?: string | null

The handle for this config, in the format provider/model-name.

model\_type?: "embedding"

Type of model (llm or embedding)

LlmConfig { context\_window, model, model\_endpoint\_type, 24 more }

Configuration for Language Model (LLM) connection and generation parameters.

.. deprecated:: LLMConfig is deprecated and should not be used as an input or return type in API calls. Use the schemas in letta.schemas.model (ModelSettings, OpenAIModelSettings, etc.) instead. For conversion, use the \_to\_model() method or Model.\_from\_llm\_config() method.

context\_window: number

The context window size for the model.

model: string

LLM model name.

model\_endpoint\_type: "openai" | "anthropic" | "google\_ai" | 25 more

The endpoint type for the model.

Accepts one of the following:

"openai"

"anthropic"

"google\_ai"

"google\_vertex"

"azure"

"groq"

"ollama"

"webui"

"webui-legacy"

"lmstudio"

"lmstudio-legacy"

"lmstudio-chatcompletions"

"llamacpp"

"koboldcpp"

"vllm"

"hugging-face"

"minimax"

"mistral"

"together"

"bedrock"

"deepseek"

"xai"

"zai"

"zai\_coding"

"baseten"

"fireworks"

"openrouter"

"chatgpt\_oauth"

compatibility\_type?: "gguf" | "mlx" | null

The framework compatibility type for the model.

Accepts one of the following:

"gguf"

"mlx"

display\_name?: string | null

A human-friendly display name for the model.

effort?: "low" | "medium" | "high" | 2 more | null

The effort level for Anthropic models that support it (Opus 4.5+). Controls token spending and thinking behavior. Not setting this gives similar performance to 'high'.

Accepts one of the following:

"low"

"medium"

"high"

"xhigh"

"max"

enable\_reasoner?: boolean

Whether or not the model should use extended thinking if it is a 'reasoning' style model

frequency\_penalty?: number | null

Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim. From OpenAI: Number between -2.0 and 2.0.

handle?: string | null

The handle for this config, in the format provider/model-name.

max\_reasoning\_tokens?: number

Configurable thinking budget for extended thinking. Used for enable\_reasoner and also for Google Vertex models like Gemini 2.5 Flash. Minimum value is 1024 when used with enable\_reasoner.

max\_tokens?: number | null

The maximum number of tokens to generate. If not set, the model will use its default value.

model\_endpoint?: string | null

The endpoint for the model.

model\_wrapper?: string | null

The wrapper for the model.

Deprecatedparallel\_tool\_calls?: boolean | null

Deprecated: Use model\_settings to configure parallel tool calls instead. If set to True, enables parallel tool calling. Defaults to False.

provider\_category?: [ProviderCategory](https://docs.letta.com/api/typescript/resources/models#(resource)%20models%20%3E%20(model)%20provider_category%20%3E%20(schema))
 | null

The provider category for the model.

Accepts one of the following:

"base"

"byok"

provider\_name?: string | null

The provider name for the model.

put\_inner\_thoughts\_in\_kwargs?: boolean | null

Puts 'inner\_thoughts' as a kwarg in the function call if this is set to True. This helps with function calling performance and also the generation of inner thoughts.

reasoning\_effort?: "none" | "minimal" | "low" | 3 more | null

The reasoning effort to use when generating text reasoning models

Accepts one of the following:

"none"

"minimal"

"low"

"medium"

"high"

"xhigh"

response\_format?: [TextResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20text_response_format%20%3E%20(schema))
 { type } | [JsonSchemaResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_schema_response_format%20%3E%20(schema))
 { json\_schema, type } | [JsonObjectResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_object_response_format%20%3E%20(schema))
 { type } | null

The response format for the model's output. Supports text, json\_object, and json\_schema (structured outputs). Can be set via model\_settings.

Accepts one of the following:

TextResponseFormat { type }

Response format for plain text responses.

type?: "text"

The type of the response format.

JsonSchemaResponseFormat { json\_schema, type }

Response format for JSON schema-based responses.

json\_schema: Record<string, unknown\>

The JSON schema of the response.

type?: "json\_schema"

The type of the response format.

JsonObjectResponseFormat { type }

Response format for JSON object responses.

type?: "json\_object"

The type of the response format.

return\_logprobs?: boolean

Whether to return log probabilities of the output tokens. Useful for RL training.

return\_token\_ids?: boolean

Whether to return token IDs for all LLM generations via SGLang native endpoint. Required for multi-turn RL training with loss masking. Only works with SGLang provider.

strict?: boolean

Enable strict mode for tool calling. When true, tool schemas include strict: true and additionalProperties: false, guaranteeing tool outputs match JSON schemas.

temperature?: number

The temperature to use when generating text with the model. A higher temperature will result in more random text.

tier?: string | null

The cost tier for the model (cloud only).

tool\_call\_parser?: string | null

SGLang tool call parser name (e.g. 'glm47', 'qwen25', 'hermes'). Used by the SGLang native adapter to parse tool calls from raw model output.

top\_logprobs?: number | null

Number of most likely tokens to return at each position (0-20). Requires return\_logprobs=True.

verbosity?: "low" | "medium" | "high" | null

Soft control for how verbose model output should be, used for GPT-5 models.

Accepts one of the following:

"low"

"medium"

"high"

Model { context\_window, max\_context\_window, model, 28 more }

Deprecatedcontext\_window: number

Deprecated: Use 'max\_context\_window' field instead. The context window size for the model.

max\_context\_window: number

The maximum context window for the model

Deprecatedmodel: string

Deprecated: Use 'name' field instead. LLM model name.

Deprecatedmodel\_endpoint\_type: "openai" | "anthropic" | "google\_ai" | 24 more

Deprecated: Use 'provider\_type' field instead. The endpoint type for the model.

Accepts one of the following:

"openai"

"anthropic"

"google\_ai"

"google\_vertex"

"azure"

"groq"

"ollama"

"webui"

"webui-legacy"

"lmstudio"

"lmstudio-legacy"

"lmstudio-chatcompletions"

"llamacpp"

"koboldcpp"

"vllm"

"hugging-face"

"baseten"

"minimax"

"mistral"

"together"

"bedrock"

"deepseek"

"xai"

"zai"

"zai\_coding"

"openrouter"

"chatgpt\_oauth"

name: string

The actual model name used by the provider

provider\_type: [ProviderType](https://docs.letta.com/api/typescript/resources/models#(resource)%20models%20%3E%20(model)%20provider_type%20%3E%20(schema))

The type of the provider

Accepts one of the following:

"anthropic"

"azure"

"baseten"

"bedrock"

"cerebras"

"chatgpt\_oauth"

"deepseek"

"fireworks"

"google\_ai"

"google\_vertex"

"groq"

"hugging-face"

"letta"

"lmstudio\_openai"

"minimax"

"mistral"

"ollama"

"openai"

"together"

"vllm"

"sglang"

"openrouter"

"xai"

"zai"

"zai\_coding"

Deprecatedcompatibility\_type?: "gguf" | "mlx" | null

Deprecated: The framework compatibility type for the model.

Accepts one of the following:

"gguf"

"mlx"

display\_name?: string | null

A human-friendly display name for the model.

effort?: "low" | "medium" | "high" | 2 more | null

The effort level for Anthropic models that support it (Opus 4.5+). Controls token spending and thinking behavior. Not setting this gives similar performance to 'high'.

Accepts one of the following:

"low"

"medium"

"high"

"xhigh"

"max"

Deprecatedenable\_reasoner?: boolean

Deprecated: Whether or not the model should use extended thinking if it is a 'reasoning' style model.

Deprecatedfrequency\_penalty?: number | null

Deprecated: Positive values penalize new tokens based on their existing frequency in the text so far.

handle?: string | null

The handle for this config, in the format provider/model-name.

Deprecatedmax\_reasoning\_tokens?: number

Deprecated: Configurable thinking budget for extended thinking.

Deprecatedmax\_tokens?: number | null

Deprecated: The maximum number of tokens to generate.

Deprecatedmodel\_endpoint?: string | null

Deprecated: The endpoint for the model.

model\_type?: "llm"

Type of model (llm or embedding)

Deprecatedmodel\_wrapper?: string | null

Deprecated: The wrapper for the model.

Deprecatedparallel\_tool\_calls?: boolean | null

Deprecated: If set to True, enables parallel tool calling.

Deprecatedprovider\_category?: [ProviderCategory](https://docs.letta.com/api/typescript/resources/models#(resource)%20models%20%3E%20(model)%20provider_category%20%3E%20(schema))
 | null

Deprecated: The provider category for the model.

Accepts one of the following:

"base"

"byok"

provider\_name?: string | null

The provider name for the model.

Deprecatedput\_inner\_thoughts\_in\_kwargs?: boolean | null

Deprecated: Puts 'inner\_thoughts' as a kwarg in the function call.

Deprecatedreasoning\_effort?: "none" | "minimal" | "low" | 3 more | null

Deprecated: The reasoning effort to use when generating text reasoning models.

Accepts one of the following:

"none"

"minimal"

"low"

"medium"

"high"

"xhigh"

response\_format?: [TextResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20text_response_format%20%3E%20(schema))
 { type } | [JsonSchemaResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_schema_response_format%20%3E%20(schema))
 { json\_schema, type } | [JsonObjectResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_object_response_format%20%3E%20(schema))
 { type } | null

The response format for the model's output. Supports text, json\_object, and json\_schema (structured outputs). Can be set via model\_settings.

Accepts one of the following:

TextResponseFormat { type }

Response format for plain text responses.

type?: "text"

The type of the response format.

JsonSchemaResponseFormat { json\_schema, type }

Response format for JSON schema-based responses.

json\_schema: Record<string, unknown\>

The JSON schema of the response.

type?: "json\_schema"

The type of the response format.

JsonObjectResponseFormat { type }

Response format for JSON object responses.

type?: "json\_object"

The type of the response format.

return\_logprobs?: boolean

Whether to return log probabilities of the output tokens. Useful for RL training.

return\_token\_ids?: boolean

Whether to return token IDs for all LLM generations via SGLang native endpoint. Required for multi-turn RL training with loss masking. Only works with SGLang provider.

strict?: boolean

Enable strict mode for tool calling. When true, tool schemas include strict: true and additionalProperties: false, guaranteeing tool outputs match JSON schemas.

Deprecatedtemperature?: number

Deprecated: The temperature to use when generating text with the model.

Deprecatedtier?: string | null

Deprecated: The cost tier for the model (cloud only).

tool\_call\_parser?: string | null

SGLang tool call parser name (e.g. 'glm47', 'qwen25', 'hermes'). Used by the SGLang native adapter to parse tool calls from raw model output.

top\_logprobs?: number | null

Number of most likely tokens to return at each position (0-20). Requires return\_logprobs=True.

Deprecatedverbosity?: "low" | "medium" | "high" | null

Deprecated: Soft control for how verbose model output should be.

Accepts one of the following:

"low"

"medium"

"high"

ProviderCategory = "base" | "byok"

Accepts one of the following:

"base"

"byok"

ProviderType = "anthropic" | "azure" | "baseten" | 22 more

Accepts one of the following:

"anthropic"

"azure"

"baseten"

"bedrock"

"cerebras"

"chatgpt\_oauth"

"deepseek"

"fireworks"

"google\_ai"

"google\_vertex"

"groq"

"hugging-face"

"letta"

"lmstudio\_openai"

"minimax"

"mistral"

"ollama"

"openai"

"together"

"vllm"

"sglang"

"openrouter"

"xai"

"zai"

"zai\_coding"

#### ModelsEmbeddings

##### [List Embedding Models](https://docs.letta.com/api/typescript/resources/models/subresources/embeddings/methods/list)

client.models.embeddings.list(RequestOptionsoptions?): [EmbeddingListResponse](https://docs.letta.com/api/typescript/resources/models#(resource)%20models.embeddings%20%3E%20(model)%20embedding_list_response%20%3E%20(schema))
 { display\_name, embedding\_dim, embedding\_endpoint\_type, 12 more }

get/v1/models/embedding

---

# Tags | Letta Docs

[Skip to content](https://docs.letta.com/api/python/resources/tags#_top)

[API Reference](https://docs.letta.com/api/python)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

* * *

**Copy Markdown**

**View as Markdown**

Tags
====

##### [List Tags](https://docs.letta.com/api/python/resources/tags/methods/list)

tags.list(TagListParams\*\*kwargs) \-> [TagListResponse](https://docs.letta.com/api/python/resources/tags#(resource)%20tags%20%3E%20(model)%20tag_list_response%20%3E%20(schema))

get/v1/tags/

---

# Tags | Letta Docs

[Skip to content](https://docs.letta.com/api/typescript/resources/tags#_top)

[API Reference](https://docs.letta.com/api/typescript)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

* * *

**Copy Markdown**

**View as Markdown**

Tags
====

##### [List Tags](https://docs.letta.com/api/typescript/resources/tags/methods/list)

client.tags.list(TagListParams { after, before, limit, 4 more } query?, RequestOptionsoptions?): [TagListResponse](https://docs.letta.com/api/typescript/resources/tags#(resource)%20tags%20%3E%20(model)%20tag_list_response%20%3E%20(schema))

get/v1/tags/

---

# Templates | Letta Docs

[Skip to content](https://docs.letta.com/api/typescript/resources/templates#_top)

[API Reference](https://docs.letta.com/api/typescript)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

* * *

**Copy Markdown**

**View as Markdown**

Templates
=========

##### [Create template (Cloud-only)](https://docs.letta.com/api/typescript/resources/templates/methods/create)

client.templates.create(TemplateCreateParamsbody, RequestOptionsoptions?): [TemplateCreateResponse](https://docs.letta.com/api/typescript/resources/templates#(resource)%20templates%20%3E%20(model)%20template_create_response%20%3E%20(schema))
 { id, latest\_version, name, 5 more }

post/v1/templates

##### [Save template version (Cloud-only)](https://docs.letta.com/api/typescript/resources/templates/methods/save)

client.templates.save(stringtemplateName, TemplateSaveParams { block\_reconciliation\_strategy, message, migrate\_agents, 3 more } body?, RequestOptionsoptions?): [TemplateSaveResponse](https://docs.letta.com/api/typescript/resources/templates#(resource)%20templates%20%3E%20(model)%20template_save_response%20%3E%20(schema))
 { id, latest\_version, name, 5 more }

post/v1/templates/{template\_name}/save

##### [Delete template (Cloud-only)](https://docs.letta.com/api/typescript/resources/templates/methods/delete)

client.templates.delete(stringtemplateName, TemplateDeleteParamsbody?, RequestOptionsoptions?): [TemplateDeleteResponse](https://docs.letta.com/api/typescript/resources/templates#(resource)%20templates%20%3E%20(model)%20template_delete_response%20%3E%20(schema))
 { success }

delete/v1/templates/{template\_name}

##### [Update current template from agent file (Cloud-only)](https://docs.letta.com/api/typescript/resources/templates/methods/update)

client.templates.update(stringtemplateName, TemplateUpdateParams { agent\_file\_json, save\_existing\_changes, update\_existing\_tools } body, RequestOptionsoptions?): [TemplateUpdateResponse](https://docs.letta.com/api/typescript/resources/templates#(resource)%20templates%20%3E%20(model)%20template_update_response%20%3E%20(schema))
 { success, message }

patch/v1/templates/{template\_name}

##### [Rollback template to previous version (Cloud-only)](https://docs.letta.com/api/typescript/resources/templates/methods/rollback)

client.templates.rollback(stringtemplateName, TemplateRollbackParams { version } body, RequestOptionsoptions?): [TemplateRollbackResponse](https://docs.letta.com/api/typescript/resources/templates#(resource)%20templates%20%3E%20(model)%20template_rollback_response%20%3E%20(schema))
 { success, message }

post/v1/templates/{template\_name}/rollback

#### TemplatesAgents

##### [Create Agents From Template](https://docs.letta.com/api/typescript/resources/templates/subresources/agents/methods/create)

client.templates.agents.create(stringtemplateVersion, AgentCreateParams { agent\_name, identity\_ids, initial\_message\_sequence, 3 more } body?, RequestOptionsoptions?): [AgentCreateResponse](https://docs.letta.com/api/typescript/resources/templates#(resource)%20templates.agents%20%3E%20(model)%20agent_create_response%20%3E%20(schema))
 { agent\_ids, deployment\_id, group\_id }

post/v1/templates/{template\_version}/agents

---

# Templates | Letta Docs

[Skip to content](https://docs.letta.com/api/python/resources/templates#_top)

[API Reference](https://docs.letta.com/api/python)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

* * *

**Copy Markdown**

**View as Markdown**

Templates
=========

##### [Create template (Cloud-only)](https://docs.letta.com/api/python/resources/templates/methods/create)

templates.create(TemplateCreateParams\*\*kwargs) \-> [TemplateCreateResponse](https://docs.letta.com/api/python/resources/templates#(resource)%20templates%20%3E%20(model)%20template_create_response%20%3E%20(schema))

post/v1/templates

##### [Save template version (Cloud-only)](https://docs.letta.com/api/python/resources/templates/methods/save)

templates.save(strtemplate\_name, TemplateSaveParams\*\*kwargs) \-> [TemplateSaveResponse](https://docs.letta.com/api/python/resources/templates#(resource)%20templates%20%3E%20(model)%20template_save_response%20%3E%20(schema))

post/v1/templates/{template\_name}/save

##### [Delete template (Cloud-only)](https://docs.letta.com/api/python/resources/templates/methods/delete)

templates.delete(strtemplate\_name) \-> [TemplateDeleteResponse](https://docs.letta.com/api/python/resources/templates#(resource)%20templates%20%3E%20(model)%20template_delete_response%20%3E%20(schema))

delete/v1/templates/{template\_name}

##### [Update current template from agent file (Cloud-only)](https://docs.letta.com/api/python/resources/templates/methods/update)

templates.update(strtemplate\_name, TemplateUpdateParams\*\*kwargs) \-> [TemplateUpdateResponse](https://docs.letta.com/api/python/resources/templates#(resource)%20templates%20%3E%20(model)%20template_update_response%20%3E%20(schema))

patch/v1/templates/{template\_name}

##### [Rollback template to previous version (Cloud-only)](https://docs.letta.com/api/python/resources/templates/methods/rollback)

templates.rollback(strtemplate\_name, TemplateRollbackParams\*\*kwargs) \-> [TemplateRollbackResponse](https://docs.letta.com/api/python/resources/templates#(resource)%20templates%20%3E%20(model)%20template_rollback_response%20%3E%20(schema))

post/v1/templates/{template\_name}/rollback

#### TemplatesAgents

##### [Create Agents From Template](https://docs.letta.com/api/python/resources/templates/subresources/agents/methods/create)

templates.agents.create(strtemplate\_version, AgentCreateParams\*\*kwargs) \-> [AgentCreateResponse](https://docs.letta.com/api/python/resources/templates#(resource)%20templates.agents%20%3E%20(model)%20agent_create_response%20%3E%20(schema))

post/v1/templates/{template\_version}/agents

---

# Access Tokens | Letta Docs

[Skip to content](https://docs.letta.com/api/typescript/resources/access_tokens#_top)

[API Reference](https://docs.letta.com/api/typescript)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

* * *

**Copy Markdown**

**View as Markdown**

Access Tokens
=============

##### [List tokens (Cloud-only)](https://docs.letta.com/api/typescript/resources/access_tokens/methods/list)

client.accessTokens.list(AccessTokenListParams { agentId, limit, offset } query?, RequestOptionsoptions?): [AccessTokenListResponse](https://docs.letta.com/api/typescript/resources/access_tokens#(resource)%20access_tokens%20%3E%20(model)%20access_token_list_response%20%3E%20(schema))
 { hasNextPage, tokens }

get/v1/client-side-access-tokens

##### [Create token (Cloud-only)](https://docs.letta.com/api/typescript/resources/access_tokens/methods/create)

client.accessTokens.create(AccessTokenCreateParams { hostname, policy, expires\_at } body, RequestOptionsoptions?): [AccessTokenCreateResponse](https://docs.letta.com/api/typescript/resources/access_tokens#(resource)%20access_tokens%20%3E%20(model)%20access_token_create_response%20%3E%20(schema))
 { token, expiresAt, hostname, policy }

post/v1/client-side-access-tokens

##### [Delete token (Cloud-only)](https://docs.letta.com/api/typescript/resources/access_tokens/methods/delete)

client.accessTokens.delete(stringtoken, AccessTokenDeleteParams { body } params?, RequestOptionsoptions?): [AccessTokenDeleteResponse](https://docs.letta.com/api/typescript/resources/access_tokens#(resource)%20access_tokens%20%3E%20(model)%20access_token_delete_response%20%3E%20(schema))

delete/v1/client-side-access-tokens/{token}

---

# Runs | Letta Docs

[Skip to content](https://docs.letta.com/api/python/resources/runs#_top)

[API Reference](https://docs.letta.com/api/python)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

* * *

**Copy Markdown**

**View as Markdown**

Runs
====

##### [List Runs](https://docs.letta.com/api/python/resources/runs/methods/list)

runs.list(RunListParams\*\*kwargs) \-> SyncArrayPage\[[Run](https://docs.letta.com/api/python/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20run%20%3E%20(schema))\
\]

get/v1/runs/

##### [Retrieve Run](https://docs.letta.com/api/python/resources/runs/methods/retrieve)

runs.retrieve(strrun\_id) \-> [Run](https://docs.letta.com/api/python/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20run%20%3E%20(schema))

get/v1/runs/{run\_id}

##### ModelsExpand Collapse

class Job: …

Representation of offline jobs, used for tracking status of data loading tasks (involving parsing and embedding files).

id: Optional\[str\]

The human-friendly ID of the Job

agent\_id: Optional\[str\]

The agent associated with this job/run.

background: Optional\[bool\]

Whether the job was created in background mode.

callback\_error: Optional\[str\]

Optional error message from attempting to POST the callback endpoint.

callback\_sent\_at: Optional\[datetime\]

Timestamp when the callback was last attempted.

formatdate-time

callback\_status\_code: Optional\[int\]

HTTP status code returned by the callback endpoint.

callback\_url: Optional\[str\]

If set, POST to this URL when the job completes.

completed\_at: Optional\[datetime\]

The unix timestamp of when the job was completed.

formatdate-time

created\_at: Optional\[datetime\]

The unix timestamp of when the job was created.

formatdate-time

created\_by\_id: Optional\[str\]

The id of the user that made this object.

job\_type: Optional\[JobType\]

The type of the job.

Accepts one of the following:

"job"

"run"

"batch"

last\_updated\_by\_id: Optional\[str\]

The id of the user that made this object.

metadata: Optional\[Dict\[str, object\]\]

The metadata of the job.

status: Optional\[JobStatus\]

The status of the job.

Accepts one of the following:

"created"

"running"

"completed"

"failed"

"pending"

"cancelled"

"expired"

stop\_reason: Optional\[StopReasonType\]

The reason why the job was stopped.

Accepts one of the following:

"end\_turn"

"error"

"llm\_api\_error"

"invalid\_llm\_response"

"invalid\_tool\_call"

"max\_steps"

"max\_tokens\_exceeded"

"no\_tool\_call"

"tool\_rule"

"cancelled"

"insufficient\_credits"

"requires\_approval"

"context\_window\_overflow\_in\_system\_prompt"

total\_duration\_ns: Optional\[int\]

Total run duration in nanoseconds

ttft\_ns: Optional\[int\]

Time to first token for a run in nanoseconds

updated\_at: Optional\[datetime\]

The timestamp when the object was last updated.

formatdate-time

Literal\["end\_turn", "error", "llm\_api\_error", 10 more\]

Accepts one of the following:

"end\_turn"

"error"

"llm\_api\_error"

"invalid\_llm\_response"

"invalid\_tool\_call"

"max\_steps"

"max\_tokens\_exceeded"

"no\_tool\_call"

"tool\_rule"

"cancelled"

"insufficient\_credits"

"requires\_approval"

"context\_window\_overflow\_in\_system\_prompt"

#### RunsMessages

##### [List Messages For Run](https://docs.letta.com/api/python/resources/runs/subresources/messages/methods/list)

runs.messages.list(strrun\_id, MessageListParams\*\*kwargs) \-> SyncArrayPage\[[Message](https://docs.letta.com/api/python/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20message%20%3E%20(schema))\
\]

get/v1/runs/{run\_id}/messages

##### [Retrieve Stream For Run](https://docs.letta.com/api/python/resources/runs/subresources/messages/methods/stream)

runs.messages.stream(strpath\_run\_id, MessageStreamParams\*\*kwargs) \-> object

post/v1/runs/{run\_id}/stream

#### RunsUsage

##### [Retrieve Usage For Run](https://docs.letta.com/api/python/resources/runs/subresources/usage/methods/retrieve)

runs.usage.retrieve(strrun\_id) \-> [UsageRetrieveResponse](https://docs.letta.com/api/python/resources/runs#(resource)%20runs.usage%20%3E%20(model)%20usage_retrieve_response%20%3E%20(schema))

get/v1/runs/{run\_id}/usage

#### RunsSteps

##### [List Steps For Run](https://docs.letta.com/api/python/resources/runs/subresources/steps/methods/list)

runs.steps.list(strrun\_id, StepListParams\*\*kwargs) \-> SyncArrayPage\[[Step](https://docs.letta.com/api/python/resources/steps#(resource)%20steps%20%3E%20(model)%20step%20%3E%20(schema))\
\]

get/v1/runs/{run\_id}/steps

#### RunsTrace

##### [Retrieve Trace For Run](https://docs.letta.com/api/python/resources/runs/subresources/trace/methods/retrieve)

runs.trace.retrieve(strrun\_id, TraceRetrieveParams\*\*kwargs) \-> [TraceRetrieveResponse](https://docs.letta.com/api/python/resources/runs#(resource)%20runs.trace%20%3E%20(model)%20trace_retrieve_response%20%3E%20(schema))

get/v1/runs/{run\_id}/trace

---

# Passages | Letta Docs

[Skip to content](https://docs.letta.com/api/typescript/resources/passages#_top)

[API Reference](https://docs.letta.com/api/typescript)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

* * *

**Copy Markdown**

**View as Markdown**

Passages
========

##### [Search Passages](https://docs.letta.com/api/typescript/resources/passages/methods/search)

client.passages.search(PassageSearchParams { agent\_id, archive\_id, end\_date, 5 more } body, RequestOptionsoptions?): [PassageSearchResponse](https://docs.letta.com/api/typescript/resources/passages#(resource)%20passages%20%3E%20(model)%20passage_search_response%20%3E%20(schema))
 { passage, score, metadata }

post/v1/passages/search

##### ModelsExpand Collapse

Passage { embedding, embedding\_config, text, 12 more }

Representation of a passage, which is stored in archival memory.

embedding: Array<number\> | null

The embedding of the passage.

embedding\_config: [EmbeddingConfig](https://docs.letta.com/api/typescript/resources/models#(resource)%20models%20%3E%20(model)%20embedding_config%20%3E%20(schema))
 { embedding\_dim, embedding\_endpoint\_type, embedding\_model, 7 more } | null

Configuration for embedding model connection and processing parameters.

embedding\_dim: number

The dimension of the embedding.

embedding\_endpoint\_type: "openai" | "anthropic" | "bedrock" | 16 more

The endpoint type for the model.

Accepts one of the following:

"openai"

"anthropic"

"bedrock"

"google\_ai"

"google\_vertex"

"azure"

"groq"

"ollama"

"webui"

"webui-legacy"

"lmstudio"

"lmstudio-legacy"

"llamacpp"

"koboldcpp"

"vllm"

"hugging-face"

"mistral"

"together"

"pinecone"

embedding\_model: string

The model for the embedding.

azure\_deployment?: string | null

The Azure deployment for the model.

azure\_endpoint?: string | null

The Azure endpoint for the model.

azure\_version?: string | null

The Azure version for the model.

batch\_size?: number

The maximum batch size for processing embeddings.

embedding\_chunk\_size?: number | null

The chunk size of the embedding.

embedding\_endpoint?: string | null

The endpoint for the model (`None` if local).

handle?: string | null

The handle for this config, in the format provider/model-name.

text: string

The text of the passage.

id?: string

The human-friendly ID of the Passage

archive\_id?: string | null

The unique identifier of the archive containing this passage.

created\_at?: string | null

The creation date of the passage.

formatdate-time

created\_by\_id?: string | null

The id of the user that made this object.

file\_id?: string | null

The unique identifier of the file associated with the passage.

file\_name?: string | null

The name of the file (only for source passages).

is\_deleted?: boolean

Whether this passage is deleted or not.

last\_updated\_by\_id?: string | null

The id of the user that made this object.

metadata?: Record<string, unknown\> | null

The metadata of the passage.

Deprecatedsource\_id?: string | null

Deprecated: Use `folder_id` field instead. The data source of the passage.

tags?: Array<string\> | null

Tags associated with this passage.

updated\_at?: string | null

The timestamp when the object was last updated.

formatdate-time

---

# Passages | Letta Docs

[Skip to content](https://docs.letta.com/api/python/resources/passages#_top)

[API Reference](https://docs.letta.com/api/python)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

* * *

**Copy Markdown**

**View as Markdown**

Passages
========

##### [Search Passages](https://docs.letta.com/api/python/resources/passages/methods/search)

passages.search(PassageSearchParams\*\*kwargs) \-> [PassageSearchResponse](https://docs.letta.com/api/python/resources/passages#(resource)%20passages%20%3E%20(model)%20passage_search_response%20%3E%20(schema))

post/v1/passages/search

##### ModelsExpand Collapse

class Passage: …

Representation of a passage, which is stored in archival memory.

embedding: Optional\[List\[float\]\]

The embedding of the passage.

embedding\_config: Optional\[EmbeddingConfig\]

Configuration for embedding model connection and processing parameters.

embedding\_dim: int

The dimension of the embedding.

embedding\_endpoint\_type: Literal\["openai", "anthropic", "bedrock", 16 more\]

The endpoint type for the model.

Accepts one of the following:

"openai"

"anthropic"

"bedrock"

"google\_ai"

"google\_vertex"

"azure"

"groq"

"ollama"

"webui"

"webui-legacy"

"lmstudio"

"lmstudio-legacy"

"llamacpp"

"koboldcpp"

"vllm"

"hugging-face"

"mistral"

"together"

"pinecone"

embedding\_model: str

The model for the embedding.

azure\_deployment: Optional\[str\]

The Azure deployment for the model.

azure\_endpoint: Optional\[str\]

The Azure endpoint for the model.

azure\_version: Optional\[str\]

The Azure version for the model.

batch\_size: Optional\[int\]

The maximum batch size for processing embeddings.

embedding\_chunk\_size: Optional\[int\]

The chunk size of the embedding.

embedding\_endpoint: Optional\[str\]

The endpoint for the model (`None` if local).

handle: Optional\[str\]

The handle for this config, in the format provider/model-name.

text: str

The text of the passage.

id: Optional\[str\]

The human-friendly ID of the Passage

archive\_id: Optional\[str\]

The unique identifier of the archive containing this passage.

created\_at: Optional\[datetime\]

The creation date of the passage.

formatdate-time

created\_by\_id: Optional\[str\]

The id of the user that made this object.

file\_id: Optional\[str\]

The unique identifier of the file associated with the passage.

file\_name: Optional\[str\]

The name of the file (only for source passages).

is\_deleted: Optional\[bool\]

Whether this passage is deleted or not.

last\_updated\_by\_id: Optional\[str\]

The id of the user that made this object.

metadata: Optional\[Dict\[str, object\]\]

The metadata of the passage.

Deprecatedsource\_id: Optional\[str\]

Deprecated: Use `folder_id` field instead. The data source of the passage.

tags: Optional\[List\[str\]\]

Tags associated with this passage.

updated\_at: Optional\[datetime\]

The timestamp when the object was last updated.

formatdate-time

---

# Runs | Letta Docs

[Skip to content](https://docs.letta.com/api/typescript/resources/runs#_top)

[API Reference](https://docs.letta.com/api/typescript)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

* * *

**Copy Markdown**

**View as Markdown**

Runs
====

##### [List Runs](https://docs.letta.com/api/typescript/resources/runs/methods/list)

client.runs.list(RunListParams { active, after, agent\_id, 10 more } query?, RequestOptionsoptions?): ArrayPage<[Run](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20run%20%3E%20(schema))
 { id, agent\_id, background, 14 more } \>

get/v1/runs/

##### [Retrieve Run](https://docs.letta.com/api/typescript/resources/runs/methods/retrieve)

client.runs.retrieve(stringrunID, RequestOptionsoptions?): [Run](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20run%20%3E%20(schema))
 { id, agent\_id, background, 14 more }

get/v1/runs/{run\_id}

##### ModelsExpand Collapse

Job { id, agent\_id, background, 15 more }

Representation of offline jobs, used for tracking status of data loading tasks (involving parsing and embedding files).

id?: string

The human-friendly ID of the Job

agent\_id?: string | null

The agent associated with this job/run.

background?: boolean | null

Whether the job was created in background mode.

callback\_error?: string | null

Optional error message from attempting to POST the callback endpoint.

callback\_sent\_at?: string | null

Timestamp when the callback was last attempted.

formatdate-time

callback\_status\_code?: number | null

HTTP status code returned by the callback endpoint.

callback\_url?: string | null

If set, POST to this URL when the job completes.

completed\_at?: string | null

The unix timestamp of when the job was completed.

formatdate-time

created\_at?: string

The unix timestamp of when the job was created.

formatdate-time

created\_by\_id?: string | null

The id of the user that made this object.

job\_type?: [JobType](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20job_type%20%3E%20(schema))

The type of the job.

Accepts one of the following:

"job"

"run"

"batch"

last\_updated\_by\_id?: string | null

The id of the user that made this object.

metadata?: Record<string, unknown\> | null

The metadata of the job.

status?: [JobStatus](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20job_status%20%3E%20(schema))

The status of the job.

Accepts one of the following:

"created"

"running"

"completed"

"failed"

"pending"

"cancelled"

"expired"

stop\_reason?: [StopReasonType](https://docs.letta.com/api/typescript/resources/runs#(resource)%20runs%20%3E%20(model)%20stop_reason_type%20%3E%20(schema))
 | null

The reason why the job was stopped.

Accepts one of the following:

"end\_turn"

"error"

"llm\_api\_error"

"invalid\_llm\_response"

"invalid\_tool\_call"

"max\_steps"

"max\_tokens\_exceeded"

"no\_tool\_call"

"tool\_rule"

"cancelled"

"insufficient\_credits"

"requires\_approval"

"context\_window\_overflow\_in\_system\_prompt"

total\_duration\_ns?: number | null

Total run duration in nanoseconds

ttft\_ns?: number | null

Time to first token for a run in nanoseconds

updated\_at?: string | null

The timestamp when the object was last updated.

formatdate-time

StopReasonType = "end\_turn" | "error" | "llm\_api\_error" | 10 more

Accepts one of the following:

"end\_turn"

"error"

"llm\_api\_error"

"invalid\_llm\_response"

"invalid\_tool\_call"

"max\_steps"

"max\_tokens\_exceeded"

"no\_tool\_call"

"tool\_rule"

"cancelled"

"insufficient\_credits"

"requires\_approval"

"context\_window\_overflow\_in\_system\_prompt"

#### RunsMessages

##### [List Messages For Run](https://docs.letta.com/api/typescript/resources/runs/subresources/messages/methods/list)

client.runs.messages.list(stringrunID, MessageListParams { after, before, limit, 2 more } query?, RequestOptionsoptions?): ArrayPage<[Message](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20message%20%3E%20(schema))
\>

get/v1/runs/{run\_id}/messages

##### [Retrieve Stream For Run](https://docs.letta.com/api/typescript/resources/runs/subresources/messages/methods/stream)

client.runs.messages.stream(stringrunID, MessageStreamParams { agent\_id, batch\_size, include\_pings, 4 more } body?, RequestOptionsoptions?): [MessageStreamResponse](https://docs.letta.com/api/typescript/resources/runs#(resource)%20runs.messages%20%3E%20(model)%20message_stream_response%20%3E%20(schema))
 | Stream<[LettaStreamingResponse](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20letta_streaming_response%20%3E%20(schema))
\>

post/v1/runs/{run\_id}/stream

#### RunsUsage

##### [Retrieve Usage For Run](https://docs.letta.com/api/typescript/resources/runs/subresources/usage/methods/retrieve)

client.runs.usage.retrieve(stringrunID, RequestOptionsoptions?): [UsageRetrieveResponse](https://docs.letta.com/api/typescript/resources/runs#(resource)%20runs.usage%20%3E%20(model)%20usage_retrieve_response%20%3E%20(schema))
 { completion\_tokens, completion\_tokens\_details, prompt\_tokens, 2 more }

get/v1/runs/{run\_id}/usage

#### RunsSteps

##### [List Steps For Run](https://docs.letta.com/api/typescript/resources/runs/subresources/steps/methods/list)

client.runs.steps.list(stringrunID, StepListParams { after, before, limit, 2 more } query?, RequestOptionsoptions?): ArrayPage<[Step](https://docs.letta.com/api/typescript/resources/steps#(resource)%20steps%20%3E%20(model)%20step%20%3E%20(schema))
 { id, agent\_id, cache\_write\_tokens, 27 more } \>

get/v1/runs/{run\_id}/steps

#### RunsTrace

##### [Retrieve Trace For Run](https://docs.letta.com/api/typescript/resources/runs/subresources/trace/methods/retrieve)

client.runs.trace.retrieve(stringrunID, TraceRetrieveParams { limit } query?, RequestOptionsoptions?): [TraceRetrieveResponse](https://docs.letta.com/api/typescript/resources/runs#(resource)%20runs.trace%20%3E%20(model)%20trace_retrieve_response%20%3E%20(schema))

get/v1/runs/{run\_id}/trace

---

# Mcp Servers | Letta Docs

[Skip to content](https://docs.letta.com/api/python/resources/mcp_servers#_top)

[API Reference](https://docs.letta.com/api/python)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

* * *

**Copy Markdown**

**View as Markdown**

Mcp Servers
===========

##### [Create Mcp Server](https://docs.letta.com/api/python/resources/mcp_servers/methods/create)

mcp\_servers.create(McpServerCreateParams\*\*kwargs) \-> [McpServerCreateResponse](https://docs.letta.com/api/python/resources/mcp_servers#(resource)%20mcp_servers%20%3E%20(model)%20mcp_server_create_response%20%3E%20(schema))

post/v1/mcp-servers/

##### [List Mcp Servers](https://docs.letta.com/api/python/resources/mcp_servers/methods/list)

mcp\_servers.list() \-> [McpServerListResponse](https://docs.letta.com/api/python/resources/mcp_servers#(resource)%20mcp_servers%20%3E%20(model)%20mcp_server_list_response%20%3E%20(schema))

get/v1/mcp-servers/

##### [Retrieve Mcp Server](https://docs.letta.com/api/python/resources/mcp_servers/methods/retrieve)

mcp\_servers.retrieve(strmcp\_server\_id) \-> [McpServerRetrieveResponse](https://docs.letta.com/api/python/resources/mcp_servers#(resource)%20mcp_servers%20%3E%20(model)%20mcp_server_retrieve_response%20%3E%20(schema))

get/v1/mcp-servers/{mcp\_server\_id}

##### [Delete Mcp Server](https://docs.letta.com/api/python/resources/mcp_servers/methods/delete)

mcp\_servers.delete(strmcp\_server\_id)

delete/v1/mcp-servers/{mcp\_server\_id}

##### [Update Mcp Server](https://docs.letta.com/api/python/resources/mcp_servers/methods/update)

mcp\_servers.update(strmcp\_server\_id, McpServerUpdateParams\*\*kwargs) \-> [McpServerUpdateResponse](https://docs.letta.com/api/python/resources/mcp_servers#(resource)%20mcp_servers%20%3E%20(model)%20mcp_server_update_response%20%3E%20(schema))

patch/v1/mcp-servers/{mcp\_server\_id}

##### [Refresh Mcp Server Tools](https://docs.letta.com/api/python/resources/mcp_servers/methods/refresh)

mcp\_servers.refresh(strmcp\_server\_id, McpServerRefreshParams\*\*kwargs) \-> object

patch/v1/mcp-servers/{mcp\_server\_id}/refresh

##### ModelsExpand Collapse

class CreateSseMcpServer: …

Create a new SSE MCP server

server\_url: str

The URL of the server

auth\_header: Optional\[str\]

The name of the authentication header (e.g., 'Authorization')

auth\_token: Optional\[str\]

The authentication token or API key value

custom\_headers: Optional\[Dict\[str, str\]\]

Custom HTTP headers to include with requests

mcp\_server\_type: Optional\[Literal\["sse"\]\]

class CreateStdioMcpServer: …

Create a new Stdio MCP server

args: List\[str\]

The arguments to pass to the command

command: str

The command to run (MCP 'local' client will run this command)

env: Optional\[Dict\[str, str\]\]

Environment variables to set

mcp\_server\_type: Optional\[Literal\["stdio"\]\]

class CreateStreamableHTTPMcpServer: …

Create a new Streamable HTTP MCP server

server\_url: str

The URL of the server

auth\_header: Optional\[str\]

The name of the authentication header (e.g., 'Authorization')

auth\_token: Optional\[str\]

The authentication token or API key value

custom\_headers: Optional\[Dict\[str, str\]\]

Custom HTTP headers to include with requests

mcp\_server\_type: Optional\[Literal\["streamable\_http"\]\]

class SseMcpServer: …

An SSE MCP server

server\_name: str

The name of the MCP server

server\_url: str

The URL of the server

id: Optional\[str\]

The human-friendly ID of the Mcp\_server

auth\_header: Optional\[str\]

The name of the authentication header (e.g., 'Authorization')

auth\_token: Optional\[str\]

The authentication token or API key value

custom\_headers: Optional\[Dict\[str, str\]\]

Custom HTTP headers to include with requests

mcp\_server\_type: Optional\[Literal\["sse"\]\]

class StdioMcpServer: …

A Stdio MCP server

args: List\[str\]

The arguments to pass to the command

command: str

The command to run (MCP 'local' client will run this command)

server\_name: str

The name of the MCP server

id: Optional\[str\]

The human-friendly ID of the Mcp\_server

env: Optional\[Dict\[str, str\]\]

Environment variables to set

mcp\_server\_type: Optional\[Literal\["stdio"\]\]

class StreamableHTTPMcpServer: …

A Streamable HTTP MCP server

server\_name: str

The name of the MCP server

server\_url: str

The URL of the server

id: Optional\[str\]

The human-friendly ID of the Mcp\_server

auth\_header: Optional\[str\]

The name of the authentication header (e.g., 'Authorization')

auth\_token: Optional\[str\]

The authentication token or API key value

custom\_headers: Optional\[Dict\[str, str\]\]

Custom HTTP headers to include with requests

mcp\_server\_type: Optional\[Literal\["streamable\_http"\]\]

class UpdateSseMcpServer: …

Update schema for SSE MCP server - all fields optional

server\_url: Optional\[str\]

The URL of the server

auth\_header: Optional\[str\]

The name of the authentication header (e.g., 'Authorization')

auth\_token: Optional\[str\]

The authentication token or API key value

custom\_headers: Optional\[Dict\[str, str\]\]

Custom HTTP headers to include with requests

mcp\_server\_type: Optional\[Literal\["sse"\]\]

class UpdateStdioMcpServer: …

Update schema for Stdio MCP server - all fields optional

args: Optional\[List\[str\]\]

The arguments to pass to the command

command: Optional\[str\]

The command to run (MCP 'local' client will run this command)

env: Optional\[Dict\[str, str\]\]

Environment variables to set

mcp\_server\_type: Optional\[Literal\["stdio"\]\]

class UpdateStreamableHTTPMcpServer: …

Update schema for Streamable HTTP MCP server - all fields optional

server\_url: Optional\[str\]

The URL of the server

auth\_header: Optional\[str\]

The name of the authentication header (e.g., 'Authorization')

auth\_token: Optional\[str\]

The authentication token or API key value

custom\_headers: Optional\[Dict\[str, str\]\]

Custom HTTP headers to include with requests

mcp\_server\_type: Optional\[Literal\["streamable\_http"\]\]

#### Mcp ServersTools

##### [List Tools For Mcp Server](https://docs.letta.com/api/python/resources/mcp_servers/subresources/tools/methods/list)

mcp\_servers.tools.list(strmcp\_server\_id) \-> [ToolListResponse](https://docs.letta.com/api/python/resources/mcp_servers#(resource)%20mcp_servers.tools%20%3E%20(model)%20tool_list_response%20%3E%20(schema))

get/v1/mcp-servers/{mcp\_server\_id}/tools

##### [Retrieve Mcp Tool](https://docs.letta.com/api/python/resources/mcp_servers/subresources/tools/methods/retrieve)

mcp\_servers.tools.retrieve(strtool\_id, ToolRetrieveParams\*\*kwargs) \-> [Tool](https://docs.letta.com/api/python/resources/tools#(resource)%20tools%20%3E%20(model)%20tool%20%3E%20(schema))

get/v1/mcp-servers/{mcp\_server\_id}/tools/{tool\_id}

##### [Run Mcp Tool](https://docs.letta.com/api/python/resources/mcp_servers/subresources/tools/methods/run)

mcp\_servers.tools.run(strtool\_id, ToolRunParams\*\*kwargs) \-> [ToolExecutionResult](https://docs.letta.com/api/python/resources/agents#(resource)%20agents.tools%20%3E%20(model)%20tool_execution_result%20%3E%20(schema))

post/v1/mcp-servers/{mcp\_server\_id}/tools/{tool\_id}/run

---

# Mcp Servers | Letta Docs

[Skip to content](https://docs.letta.com/api/typescript/resources/mcp_servers#_top)

[API Reference](https://docs.letta.com/api/typescript)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

* * *

**Copy Markdown**

**View as Markdown**

Mcp Servers
===========

##### [Create Mcp Server](https://docs.letta.com/api/typescript/resources/mcp_servers/methods/create)

client.mcpServers.create(McpServerCreateParams { config, server\_name } body, RequestOptionsoptions?): [McpServerCreateResponse](https://docs.letta.com/api/typescript/resources/mcp_servers#(resource)%20mcp_servers%20%3E%20(model)%20mcp_server_create_response%20%3E%20(schema))

post/v1/mcp-servers/

##### [List Mcp Servers](https://docs.letta.com/api/typescript/resources/mcp_servers/methods/list)

client.mcpServers.list(RequestOptionsoptions?): [McpServerListResponse](https://docs.letta.com/api/typescript/resources/mcp_servers#(resource)%20mcp_servers%20%3E%20(model)%20mcp_server_list_response%20%3E%20(schema))
 { , , }

get/v1/mcp-servers/

##### [Retrieve Mcp Server](https://docs.letta.com/api/typescript/resources/mcp_servers/methods/retrieve)

client.mcpServers.retrieve(stringmcpServerID, RequestOptionsoptions?): [McpServerRetrieveResponse](https://docs.letta.com/api/typescript/resources/mcp_servers#(resource)%20mcp_servers%20%3E%20(model)%20mcp_server_retrieve_response%20%3E%20(schema))

get/v1/mcp-servers/{mcp\_server\_id}

##### [Delete Mcp Server](https://docs.letta.com/api/typescript/resources/mcp_servers/methods/delete)

client.mcpServers.delete(stringmcpServerID, RequestOptionsoptions?): void

delete/v1/mcp-servers/{mcp\_server\_id}

##### [Update Mcp Server](https://docs.letta.com/api/typescript/resources/mcp_servers/methods/update)

client.mcpServers.update(stringmcpServerID, McpServerUpdateParams { config, server\_name } body, RequestOptionsoptions?): [McpServerUpdateResponse](https://docs.letta.com/api/typescript/resources/mcp_servers#(resource)%20mcp_servers%20%3E%20(model)%20mcp_server_update_response%20%3E%20(schema))

patch/v1/mcp-servers/{mcp\_server\_id}

##### [Refresh Mcp Server Tools](https://docs.letta.com/api/typescript/resources/mcp_servers/methods/refresh)

client.mcpServers.refresh(stringmcpServerID, McpServerRefreshParams { agent\_id } params?, RequestOptionsoptions?): [McpServerRefreshResponse](https://docs.letta.com/api/typescript/resources/mcp_servers#(resource)%20mcp_servers%20%3E%20(model)%20mcp_server_refresh_response%20%3E%20(schema))

patch/v1/mcp-servers/{mcp\_server\_id}/refresh

##### ModelsExpand Collapse

CreateSseMcpServer { server\_url, auth\_header, auth\_token, 2 more }

Create a new SSE MCP server

server\_url: string

The URL of the server

auth\_header?: string | null

The name of the authentication header (e.g., 'Authorization')

auth\_token?: string | null

The authentication token or API key value

custom\_headers?: Record<string, string\> | null

Custom HTTP headers to include with requests

mcp\_server\_type?: "sse"

CreateStdioMcpServer { args, command, env, mcp\_server\_type }

Create a new Stdio MCP server

args: Array<string\>

The arguments to pass to the command

command: string

The command to run (MCP 'local' client will run this command)

env?: Record<string, string\> | null

Environment variables to set

mcp\_server\_type?: "stdio"

CreateStreamableHTTPMcpServer { server\_url, auth\_header, auth\_token, 2 more }

Create a new Streamable HTTP MCP server

server\_url: string

The URL of the server

auth\_header?: string | null

The name of the authentication header (e.g., 'Authorization')

auth\_token?: string | null

The authentication token or API key value

custom\_headers?: Record<string, string\> | null

Custom HTTP headers to include with requests

mcp\_server\_type?: "streamable\_http"

SseMcpServer { server\_name, server\_url, id, 4 more }

An SSE MCP server

server\_name: string

The name of the MCP server

server\_url: string

The URL of the server

id?: string

The human-friendly ID of the Mcp\_server

auth\_header?: string | null

The name of the authentication header (e.g., 'Authorization')

auth\_token?: string | null

The authentication token or API key value

custom\_headers?: Record<string, string\> | null

Custom HTTP headers to include with requests

mcp\_server\_type?: "sse"

StdioMcpServer { args, command, server\_name, 3 more }

A Stdio MCP server

args: Array<string\>

The arguments to pass to the command

command: string

The command to run (MCP 'local' client will run this command)

server\_name: string

The name of the MCP server

id?: string

The human-friendly ID of the Mcp\_server

env?: Record<string, string\> | null

Environment variables to set

mcp\_server\_type?: "stdio"

StreamableHTTPMcpServer { server\_name, server\_url, id, 4 more }

A Streamable HTTP MCP server

server\_name: string

The name of the MCP server

server\_url: string

The URL of the server

id?: string

The human-friendly ID of the Mcp\_server

auth\_header?: string | null

The name of the authentication header (e.g., 'Authorization')

auth\_token?: string | null

The authentication token or API key value

custom\_headers?: Record<string, string\> | null

Custom HTTP headers to include with requests

mcp\_server\_type?: "streamable\_http"

UpdateSseMcpServer { server\_url, auth\_header, auth\_token, 2 more }

Update schema for SSE MCP server - all fields optional

server\_url: string | null

The URL of the server

auth\_header?: string | null

The name of the authentication header (e.g., 'Authorization')

auth\_token?: string | null

The authentication token or API key value

custom\_headers?: Record<string, string\> | null

Custom HTTP headers to include with requests

mcp\_server\_type?: "sse"

UpdateStdioMcpServer { args, command, env, mcp\_server\_type }

Update schema for Stdio MCP server - all fields optional

args: Array<string\> | null

The arguments to pass to the command

command: string | null

The command to run (MCP 'local' client will run this command)

env?: Record<string, string\> | null

Environment variables to set

mcp\_server\_type?: "stdio"

UpdateStreamableHTTPMcpServer { server\_url, auth\_header, auth\_token, 2 more }

Update schema for Streamable HTTP MCP server - all fields optional

server\_url: string | null

The URL of the server

auth\_header?: string | null

The name of the authentication header (e.g., 'Authorization')

auth\_token?: string | null

The authentication token or API key value

custom\_headers?: Record<string, string\> | null

Custom HTTP headers to include with requests

mcp\_server\_type?: "streamable\_http"

#### Mcp ServersTools

##### [List Tools For Mcp Server](https://docs.letta.com/api/typescript/resources/mcp_servers/subresources/tools/methods/list)

client.mcpServers.tools.list(stringmcpServerID, RequestOptionsoptions?): [ToolListResponse](https://docs.letta.com/api/typescript/resources/mcp_servers#(resource)%20mcp_servers.tools%20%3E%20(model)%20tool_list_response%20%3E%20(schema))
 { id, args\_json\_schema, created\_by\_id, 15 more }

get/v1/mcp-servers/{mcp\_server\_id}/tools

##### [Retrieve Mcp Tool](https://docs.letta.com/api/typescript/resources/mcp_servers/subresources/tools/methods/retrieve)

client.mcpServers.tools.retrieve(stringtoolID, ToolRetrieveParams { mcp\_server\_id } params, RequestOptionsoptions?): [Tool](https://docs.letta.com/api/typescript/resources/tools#(resource)%20tools%20%3E%20(model)%20tool%20%3E%20(schema))
 { id, args\_json\_schema, created\_by\_id, 15 more }

get/v1/mcp-servers/{mcp\_server\_id}/tools/{tool\_id}

##### [Run Mcp Tool](https://docs.letta.com/api/typescript/resources/mcp_servers/subresources/tools/methods/run)

client.mcpServers.tools.run(stringtoolID, ToolRunParams { mcp\_server\_id, args } params, RequestOptionsoptions?): [ToolExecutionResult](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents.tools%20%3E%20(model)%20tool_execution_result%20%3E%20(schema))
 { status, agent\_state, func\_return, 3 more }

post/v1/mcp-servers/{mcp\_server\_id}/tools/{tool\_id}/run

---

# Access Tokens | Letta Docs

[Skip to content](https://docs.letta.com/api/python/resources/access_tokens#_top)

[API Reference](https://docs.letta.com/api/python)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

* * *

**Copy Markdown**

**View as Markdown**

Access Tokens
=============

##### [List tokens (Cloud-only)](https://docs.letta.com/api/python/resources/access_tokens/methods/list)

access\_tokens.list(AccessTokenListParams\*\*kwargs) \-> [AccessTokenListResponse](https://docs.letta.com/api/python/resources/access_tokens#(resource)%20access_tokens%20%3E%20(model)%20access_token_list_response%20%3E%20(schema))

get/v1/client-side-access-tokens

##### [Create token (Cloud-only)](https://docs.letta.com/api/python/resources/access_tokens/methods/create)

access\_tokens.create(AccessTokenCreateParams\*\*kwargs) \-> [AccessTokenCreateResponse](https://docs.letta.com/api/python/resources/access_tokens#(resource)%20access_tokens%20%3E%20(model)%20access_token_create_response%20%3E%20(schema))

post/v1/client-side-access-tokens

##### [Delete token (Cloud-only)](https://docs.letta.com/api/python/resources/access_tokens/methods/delete)

access\_tokens.delete(strtoken, AccessTokenDeleteParams\*\*kwargs) \-> object

delete/v1/client-side-access-tokens/{token}

---

# Models | Letta Docs

[Skip to content](https://docs.letta.com/api/python/resources/models#_top)

[API Reference](https://docs.letta.com/api/python)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

* * *

**Copy Markdown**

**View as Markdown**

Models
======

##### [List Llm Models](https://docs.letta.com/api/python/resources/models/methods/list)

models.list(ModelListParams\*\*kwargs) \-> [ModelListResponse](https://docs.letta.com/api/python/resources/models#(resource)%20models%20%3E%20(model)%20model_list_response%20%3E%20(schema))

get/v1/models/

##### ModelsExpand Collapse

class EmbeddingConfig: …

Configuration for embedding model connection and processing parameters.

embedding\_dim: int

The dimension of the embedding.

embedding\_endpoint\_type: Literal\["openai", "anthropic", "bedrock", 16 more\]

The endpoint type for the model.

Accepts one of the following:

"openai"

"anthropic"

"bedrock"

"google\_ai"

"google\_vertex"

"azure"

"groq"

"ollama"

"webui"

"webui-legacy"

"lmstudio"

"lmstudio-legacy"

"llamacpp"

"koboldcpp"

"vllm"

"hugging-face"

"mistral"

"together"

"pinecone"

embedding\_model: str

The model for the embedding.

azure\_deployment: Optional\[str\]

The Azure deployment for the model.

azure\_endpoint: Optional\[str\]

The Azure endpoint for the model.

azure\_version: Optional\[str\]

The Azure version for the model.

batch\_size: Optional\[int\]

The maximum batch size for processing embeddings.

embedding\_chunk\_size: Optional\[int\]

The chunk size of the embedding.

embedding\_endpoint: Optional\[str\]

The endpoint for the model (`None` if local).

handle: Optional\[str\]

The handle for this config, in the format provider/model-name.

class EmbeddingModel: …

display\_name: str

Display name for the model shown in UI

embedding\_dim: int

The dimension of the embedding

Deprecatedembedding\_endpoint\_type: Literal\["openai", "anthropic", "bedrock", 16 more\]

Deprecated: Use 'provider\_type' field instead. The endpoint type for the embedding model.

Accepts one of the following:

"openai"

"anthropic"

"bedrock"

"google\_ai"

"google\_vertex"

"azure"

"groq"

"ollama"

"webui"

"webui-legacy"

"lmstudio"

"lmstudio-legacy"

"llamacpp"

"koboldcpp"

"vllm"

"hugging-face"

"mistral"

"together"

"pinecone"

Deprecatedembedding\_model: str

Deprecated: Use 'name' field instead. Embedding model name.

name: str

The actual model name used by the provider

provider\_name: str

The name of the provider

provider\_type: [ProviderType](https://docs.letta.com/api/python/resources/models#(resource)%20models%20%3E%20(model)%20provider_type%20%3E%20(schema))

The type of the provider

Accepts one of the following:

"anthropic"

"azure"

"baseten"

"bedrock"

"cerebras"

"chatgpt\_oauth"

"deepseek"

"fireworks"

"google\_ai"

"google\_vertex"

"groq"

"hugging-face"

"letta"

"lmstudio\_openai"

"minimax"

"mistral"

"ollama"

"openai"

"together"

"vllm"

"sglang"

"openrouter"

"xai"

"zai"

"zai\_coding"

Deprecatedazure\_deployment: Optional\[str\]

Deprecated: The Azure deployment for the model.

Deprecatedazure\_endpoint: Optional\[str\]

Deprecated: The Azure endpoint for the model.

Deprecatedazure\_version: Optional\[str\]

Deprecated: The Azure version for the model.

Deprecatedbatch\_size: Optional\[int\]

Deprecated: The maximum batch size for processing embeddings.

Deprecatedembedding\_chunk\_size: Optional\[int\]

Deprecated: The chunk size of the embedding.

Deprecatedembedding\_endpoint: Optional\[str\]

Deprecated: The endpoint for the model.

handle: Optional\[str\]

The handle for this config, in the format provider/model-name.

model\_type: Optional\[Literal\["embedding"\]\]

Type of model (llm or embedding)

class LlmConfig: …

Configuration for Language Model (LLM) connection and generation parameters.

.. deprecated:: LLMConfig is deprecated and should not be used as an input or return type in API calls. Use the schemas in letta.schemas.model (ModelSettings, OpenAIModelSettings, etc.) instead. For conversion, use the \_to\_model() method or Model.\_from\_llm\_config() method.

context\_window: int

The context window size for the model.

model: str

LLM model name.

model\_endpoint\_type: Literal\["openai", "anthropic", "google\_ai", 25 more\]

The endpoint type for the model.

Accepts one of the following:

"openai"

"anthropic"

"google\_ai"

"google\_vertex"

"azure"

"groq"

"ollama"

"webui"

"webui-legacy"

"lmstudio"

"lmstudio-legacy"

"lmstudio-chatcompletions"

"llamacpp"

"koboldcpp"

"vllm"

"hugging-face"

"minimax"

"mistral"

"together"

"bedrock"

"deepseek"

"xai"

"zai"

"zai\_coding"

"baseten"

"fireworks"

"openrouter"

"chatgpt\_oauth"

compatibility\_type: Optional\[Literal\["gguf", "mlx"\]\]

The framework compatibility type for the model.

Accepts one of the following:

"gguf"

"mlx"

display\_name: Optional\[str\]

A human-friendly display name for the model.

effort: Optional\[Literal\["low", "medium", "high", 2 more\]\]

The effort level for Anthropic models that support it (Opus 4.5+). Controls token spending and thinking behavior. Not setting this gives similar performance to 'high'.

Accepts one of the following:

"low"

"medium"

"high"

"xhigh"

"max"

enable\_reasoner: Optional\[bool\]

Whether or not the model should use extended thinking if it is a 'reasoning' style model

frequency\_penalty: Optional\[float\]

Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim. From OpenAI: Number between -2.0 and 2.0.

handle: Optional\[str\]

The handle for this config, in the format provider/model-name.

max\_reasoning\_tokens: Optional\[int\]

Configurable thinking budget for extended thinking. Used for enable\_reasoner and also for Google Vertex models like Gemini 2.5 Flash. Minimum value is 1024 when used with enable\_reasoner.

max\_tokens: Optional\[int\]

The maximum number of tokens to generate. If not set, the model will use its default value.

model\_endpoint: Optional\[str\]

The endpoint for the model.

model\_wrapper: Optional\[str\]

The wrapper for the model.

Deprecatedparallel\_tool\_calls: Optional\[bool\]

Deprecated: Use model\_settings to configure parallel tool calls instead. If set to True, enables parallel tool calling. Defaults to False.

provider\_category: Optional\[ProviderCategory\]

The provider category for the model.

Accepts one of the following:

"base"

"byok"

provider\_name: Optional\[str\]

The provider name for the model.

put\_inner\_thoughts\_in\_kwargs: Optional\[bool\]

Puts 'inner\_thoughts' as a kwarg in the function call if this is set to True. This helps with function calling performance and also the generation of inner thoughts.

reasoning\_effort: Optional\[Literal\["none", "minimal", "low", 3 more\]\]

The reasoning effort to use when generating text reasoning models

Accepts one of the following:

"none"

"minimal"

"low"

"medium"

"high"

"xhigh"

response\_format: Optional\[ResponseFormat\]

The response format for the model's output. Supports text, json\_object, and json\_schema (structured outputs). Can be set via model\_settings.

Accepts one of the following:

class TextResponseFormat: …

Response format for plain text responses.

type: Optional\[Literal\["text"\]\]

The type of the response format.

class JsonSchemaResponseFormat: …

Response format for JSON schema-based responses.

json\_schema: Dict\[str, object\]

The JSON schema of the response.

type: Optional\[Literal\["json\_schema"\]\]

The type of the response format.

class JsonObjectResponseFormat: …

Response format for JSON object responses.

type: Optional\[Literal\["json\_object"\]\]

The type of the response format.

return\_logprobs: Optional\[bool\]

Whether to return log probabilities of the output tokens. Useful for RL training.

return\_token\_ids: Optional\[bool\]

Whether to return token IDs for all LLM generations via SGLang native endpoint. Required for multi-turn RL training with loss masking. Only works with SGLang provider.

strict: Optional\[bool\]

Enable strict mode for tool calling. When true, tool schemas include strict: true and additionalProperties: false, guaranteeing tool outputs match JSON schemas.

temperature: Optional\[float\]

The temperature to use when generating text with the model. A higher temperature will result in more random text.

tier: Optional\[str\]

The cost tier for the model (cloud only).

tool\_call\_parser: Optional\[str\]

SGLang tool call parser name (e.g. 'glm47', 'qwen25', 'hermes'). Used by the SGLang native adapter to parse tool calls from raw model output.

top\_logprobs: Optional\[int\]

Number of most likely tokens to return at each position (0-20). Requires return\_logprobs=True.

verbosity: Optional\[Literal\["low", "medium", "high"\]\]

Soft control for how verbose model output should be, used for GPT-5 models.

Accepts one of the following:

"low"

"medium"

"high"

class Model: …

Deprecatedcontext\_window: int

Deprecated: Use 'max\_context\_window' field instead. The context window size for the model.

max\_context\_window: int

The maximum context window for the model

Deprecatedmodel: str

Deprecated: Use 'name' field instead. LLM model name.

Deprecatedmodel\_endpoint\_type: Literal\["openai", "anthropic", "google\_ai", 24 more\]

Deprecated: Use 'provider\_type' field instead. The endpoint type for the model.

Accepts one of the following:

"openai"

"anthropic"

"google\_ai"

"google\_vertex"

"azure"

"groq"

"ollama"

"webui"

"webui-legacy"

"lmstudio"

"lmstudio-legacy"

"lmstudio-chatcompletions"

"llamacpp"

"koboldcpp"

"vllm"

"hugging-face"

"baseten"

"minimax"

"mistral"

"together"

"bedrock"

"deepseek"

"xai"

"zai"

"zai\_coding"

"openrouter"

"chatgpt\_oauth"

name: str

The actual model name used by the provider

provider\_type: [ProviderType](https://docs.letta.com/api/python/resources/models#(resource)%20models%20%3E%20(model)%20provider_type%20%3E%20(schema))

The type of the provider

Accepts one of the following:

"anthropic"

"azure"

"baseten"

"bedrock"

"cerebras"

"chatgpt\_oauth"

"deepseek"

"fireworks"

"google\_ai"

"google\_vertex"

"groq"

"hugging-face"

"letta"

"lmstudio\_openai"

"minimax"

"mistral"

"ollama"

"openai"

"together"

"vllm"

"sglang"

"openrouter"

"xai"

"zai"

"zai\_coding"

Deprecatedcompatibility\_type: Optional\[Literal\["gguf", "mlx"\]\]

Deprecated: The framework compatibility type for the model.

Accepts one of the following:

"gguf"

"mlx"

display\_name: Optional\[str\]

A human-friendly display name for the model.

effort: Optional\[Literal\["low", "medium", "high", 2 more\]\]

The effort level for Anthropic models that support it (Opus 4.5+). Controls token spending and thinking behavior. Not setting this gives similar performance to 'high'.

Accepts one of the following:

"low"

"medium"

"high"

"xhigh"

"max"

Deprecatedenable\_reasoner: Optional\[bool\]

Deprecated: Whether or not the model should use extended thinking if it is a 'reasoning' style model.

Deprecatedfrequency\_penalty: Optional\[float\]

Deprecated: Positive values penalize new tokens based on their existing frequency in the text so far.

handle: Optional\[str\]

The handle for this config, in the format provider/model-name.

Deprecatedmax\_reasoning\_tokens: Optional\[int\]

Deprecated: Configurable thinking budget for extended thinking.

Deprecatedmax\_tokens: Optional\[int\]

Deprecated: The maximum number of tokens to generate.

Deprecatedmodel\_endpoint: Optional\[str\]

Deprecated: The endpoint for the model.

model\_type: Optional\[Literal\["llm"\]\]

Type of model (llm or embedding)

Deprecatedmodel\_wrapper: Optional\[str\]

Deprecated: The wrapper for the model.

Deprecatedparallel\_tool\_calls: Optional\[bool\]

Deprecated: If set to True, enables parallel tool calling.

Deprecatedprovider\_category: Optional\[ProviderCategory\]

Deprecated: The provider category for the model.

Accepts one of the following:

"base"

"byok"

provider\_name: Optional\[str\]

The provider name for the model.

Deprecatedput\_inner\_thoughts\_in\_kwargs: Optional\[bool\]

Deprecated: Puts 'inner\_thoughts' as a kwarg in the function call.

Deprecatedreasoning\_effort: Optional\[Literal\["none", "minimal", "low", 3 more\]\]

Deprecated: The reasoning effort to use when generating text reasoning models.

Accepts one of the following:

"none"

"minimal"

"low"

"medium"

"high"

"xhigh"

response\_format: Optional\[ResponseFormat\]

The response format for the model's output. Supports text, json\_object, and json\_schema (structured outputs). Can be set via model\_settings.

Accepts one of the following:

class TextResponseFormat: …

Response format for plain text responses.

type: Optional\[Literal\["text"\]\]

The type of the response format.

class JsonSchemaResponseFormat: …

Response format for JSON schema-based responses.

json\_schema: Dict\[str, object\]

The JSON schema of the response.

type: Optional\[Literal\["json\_schema"\]\]

The type of the response format.

class JsonObjectResponseFormat: …

Response format for JSON object responses.

type: Optional\[Literal\["json\_object"\]\]

The type of the response format.

return\_logprobs: Optional\[bool\]

Whether to return log probabilities of the output tokens. Useful for RL training.

return\_token\_ids: Optional\[bool\]

Whether to return token IDs for all LLM generations via SGLang native endpoint. Required for multi-turn RL training with loss masking. Only works with SGLang provider.

strict: Optional\[bool\]

Enable strict mode for tool calling. When true, tool schemas include strict: true and additionalProperties: false, guaranteeing tool outputs match JSON schemas.

Deprecatedtemperature: Optional\[float\]

Deprecated: The temperature to use when generating text with the model.

Deprecatedtier: Optional\[str\]

Deprecated: The cost tier for the model (cloud only).

tool\_call\_parser: Optional\[str\]

SGLang tool call parser name (e.g. 'glm47', 'qwen25', 'hermes'). Used by the SGLang native adapter to parse tool calls from raw model output.

top\_logprobs: Optional\[int\]

Number of most likely tokens to return at each position (0-20). Requires return\_logprobs=True.

Deprecatedverbosity: Optional\[Literal\["low", "medium", "high"\]\]

Deprecated: Soft control for how verbose model output should be.

Accepts one of the following:

"low"

"medium"

"high"

Literal\["base", "byok"\]

Accepts one of the following:

"base"

"byok"

Literal\["anthropic", "azure", "baseten", 22 more\]

Accepts one of the following:

"anthropic"

"azure"

"baseten"

"bedrock"

"cerebras"

"chatgpt\_oauth"

"deepseek"

"fireworks"

"google\_ai"

"google\_vertex"

"groq"

"hugging-face"

"letta"

"lmstudio\_openai"

"minimax"

"mistral"

"ollama"

"openai"

"together"

"vllm"

"sglang"

"openrouter"

"xai"

"zai"

"zai\_coding"

#### ModelsEmbeddings

##### [List Embedding Models](https://docs.letta.com/api/python/resources/models/subresources/embeddings/methods/list)

models.embeddings.list() \-> [EmbeddingListResponse](https://docs.letta.com/api/python/resources/models#(resource)%20models.embeddings%20%3E%20(model)%20embedding_list_response%20%3E%20(schema))

get/v1/models/embedding

---

# Messages | Letta Docs

[Skip to content](https://docs.letta.com/api/typescript/resources/messages#_top)

[API Reference](https://docs.letta.com/api/typescript)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

* * *

**Copy Markdown**

**View as Markdown**

Messages
========

##### [List All Messages](https://docs.letta.com/api/typescript/resources/messages/methods/list)

client.messages.list(MessageListParams { after, before, conversation\_id, 3 more } query?, RequestOptionsoptions?): [MessageListResponse](https://docs.letta.com/api/typescript/resources/messages#(resource)%20messages%20%3E%20(model)%20message_list_response%20%3E%20(schema))
 { , , , 8 more }

get/v1/messages/

##### [Retrieve Message](https://docs.letta.com/api/typescript/resources/messages/methods/retrieve)

client.messages.retrieve(stringmessageID, RequestOptionsoptions?): [MessageRetrieveResponse](https://docs.letta.com/api/typescript/resources/messages#(resource)%20messages%20%3E%20(model)%20message_retrieve_response%20%3E%20(schema))
 { , , , 8 more }

get/v1/messages/{message\_id}

##### [Search All Messages](https://docs.letta.com/api/typescript/resources/messages/methods/search)

client.messages.search(MessageSearchParams { query, agent\_id, conversation\_id, 4 more } body, RequestOptionsoptions?): [MessageSearchResponse](https://docs.letta.com/api/typescript/resources/messages#(resource)%20messages%20%3E%20(model)%20message_search_response%20%3E%20(schema))
 { , , , }

post/v1/messages/search

##### ModelsExpand Collapse

MessageSearchRequest { query, agent\_id, conversation\_id, 4 more }

query: string

Text query for full-text search

agent\_id?: string | null

Filter messages by agent ID

conversation\_id?: string | null

Filter messages by conversation ID

end\_date?: string | null

Filter messages created on or before this date

formatdate-time

limit?: number

Maximum number of results to return

maximum100

minimum1

search\_mode?: "vector" | "fts" | "hybrid"

Search mode to use

Accepts one of the following:

"vector"

"fts"

"hybrid"

start\_date?: string | null

Filter messages created after this date

formatdate-time

MessageSearchResult { embedded\_text, message, rrf\_score, 2 more }

Result from a message search operation with scoring details.

embedded\_text: string

The embedded content (LLM-friendly)

message: [InternalMessage](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20internal_message%20%3E%20(schema))
 { id, role, agent\_id, 22 more }

The raw message object

id: string

The human-friendly ID of the Message

role: [MessageRole](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20message_role%20%3E%20(schema))

The role of the participant.

Accepts one of the following:

"assistant"

"user"

"tool"

"function"

"system"

"approval"

"summary"

agent\_id?: string | null

The unique identifier of the agent.

approval\_request\_id?: string | null

The id of the approval request if this message is associated with a tool call request.

approvals?: Array<[ApprovalReturn](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20approval_return%20%3E%20(schema))
 { approve, tool\_call\_id, reason, type } | LettaSchemasMessageToolReturnOutput { status, func\_response, stderr, 2 more } \> | null

The list of approvals for this message.

Accepts one of the following:

ApprovalReturn { approve, tool\_call\_id, reason, type }

approve: boolean

Whether the tool has been approved

tool\_call\_id: string

The ID of the tool call that corresponds to this approval

reason?: string | null

An optional explanation for the provided approval status

type?: "approval"

The message type to be created.

LettaSchemasMessageToolReturnOutput { status, func\_response, stderr, 2 more }

status: "success" | "error"

The status of the tool call

Accepts one of the following:

"success"

"error"

func\_response?: string | Array<[TextContent](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20text_content%20%3E%20(schema))
 { text, signature, type } | [ImageContent](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20image_content%20%3E%20(schema))
 { source, type } \> | null

The function response - either a string or list of content parts (text/image)

Accepts one of the following:

string

Array<[TextContent](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20text_content%20%3E%20(schema))
 { text, signature, type } | [ImageContent](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20image_content%20%3E%20(schema))
 { source, type } \>

TextContent { text, signature, type }

text: string

The text content of the message.

signature?: string | null

Stores a unique identifier for any reasoning associated with this text content.

type?: "text"

The type of the message.

ImageContent { source, type }

source: URLImage { url, type } | Base64Image { data, media\_type, detail, type } | LettaImage { file\_id, data, detail, 2 more }

The source of the image.

Accepts one of the following:

URLImage { url, type }

url: string

The URL of the image.

type?: "url"

The source type for the image.

Base64Image { data, media\_type, detail, type }

data: string

The base64 encoded image data.

media\_type: string

The media type for the image.

detail?: string | null

What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)

type?: "base64"

The source type for the image.

LettaImage { file\_id, data, detail, 2 more }

file\_id: string

The unique identifier of the image file persisted in storage.

data?: string | null

The base64 encoded image data.

detail?: string | null

What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)

media\_type?: string | null

The media type for the image.

type?: "letta"

The source type for the image.

type?: "image"

The type of the message.

stderr?: Array<string\> | null

Captured stderr from the tool invocation

stdout?: Array<string\> | null

Captured stdout (e.g. prints, logs) from the tool invocation

tool\_call\_id?: unknown

The ID for the tool call

approve?: boolean | null

Whether tool call is approved.

batch\_item\_id?: string | null

The id of the LLMBatchItem that this message is associated with

content?: Array<[TextContent](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20text_content%20%3E%20(schema))
 { text, signature, type } | [ImageContent](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20image_content%20%3E%20(schema))
 { source, type } | [ToolCallContent](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20tool_call_content%20%3E%20(schema))
 { id, input, name, 2 more } | 5 more\> | null

The content of the message.

Accepts one of the following:

TextContent { text, signature, type }

text: string

The text content of the message.

signature?: string | null

Stores a unique identifier for any reasoning associated with this text content.

type?: "text"

The type of the message.

ImageContent { source, type }

source: URLImage { url, type } | Base64Image { data, media\_type, detail, type } | LettaImage { file\_id, data, detail, 2 more }

The source of the image.

Accepts one of the following:

URLImage { url, type }

url: string

The URL of the image.

type?: "url"

The source type for the image.

Base64Image { data, media\_type, detail, type }

data: string

The base64 encoded image data.

media\_type: string

The media type for the image.

detail?: string | null

What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)

type?: "base64"

The source type for the image.

LettaImage { file\_id, data, detail, 2 more }

file\_id: string

The unique identifier of the image file persisted in storage.

data?: string | null

The base64 encoded image data.

detail?: string | null

What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)

media\_type?: string | null

The media type for the image.

type?: "letta"

The source type for the image.

type?: "image"

The type of the message.

ToolCallContent { id, input, name, 2 more }

id: string

A unique identifier for this specific tool call instance.

input: Record<string, unknown\>

The parameters being passed to the tool, structured as a dictionary of parameter names to values.

name: string

The name of the tool being called.

signature?: string | null

Stores a unique identifier for any reasoning associated with this tool call.

type?: "tool\_call"

Indicates this content represents a tool call event.

ToolReturnContent { content, is\_error, tool\_call\_id, type }

content: string

The content returned by the tool execution.

is\_error: boolean

Indicates whether the tool execution resulted in an error.

tool\_call\_id: string

References the ID of the ToolCallContent that initiated this tool call.

type?: "tool\_return"

Indicates this content represents a tool return event.

ReasoningContent { is\_native, reasoning, signature, type }

Sent via the Anthropic Messages API

is\_native: boolean

Whether the reasoning content was generated by a reasoner model that processed this step.

reasoning: string

The intermediate reasoning or thought process content.

signature?: string | null

A unique identifier for this reasoning step.

type?: "reasoning"

Indicates this is a reasoning/intermediate step.

RedactedReasoningContent { data, type }

Sent via the Anthropic Messages API

data: string

The redacted or filtered intermediate reasoning content.

type?: "redacted\_reasoning"

Indicates this is a redacted thinking step.

OmittedReasoningContent { signature, type }

A placeholder for reasoning content we know is present, but isn't returned by the provider (e.g. OpenAI GPT-5 on ChatCompletions)

signature?: string | null

A unique identifier for this reasoning step.

type?: "omitted\_reasoning"

Indicates this is an omitted reasoning step.

SummarizedReasoningContent { id, summary, encrypted\_content, type }

The style of reasoning content returned by the OpenAI Responses API

id: string

The unique identifier for this reasoning step.

summary: Array<Summary\>

Summaries of the reasoning content.

index: number

The index of the summary part.

text: string

The text of the summary part.

encrypted\_content?: string

The encrypted reasoning content.

type?: "summarized\_reasoning"

Indicates this is a summarized reasoning step.

conversation\_id?: string | null

The conversation this message belongs to

created\_at?: string

The timestamp when the object was created.

formatdate-time

created\_by\_id?: string | null

The id of the user that made this object.

denial\_reason?: string | null

The reason the tool call request was denied.

group\_id?: string | null

The multi-agent group that the message was sent in

is\_err?: boolean | null

Whether this message is part of an error step. Used only for debugging purposes.

last\_updated\_by\_id?: string | null

The id of the user that made this object.

model?: string | null

The model used to make the function call.

name?: string | null

For role user/assistant: the (optional) name of the participant. For role tool/function: the name of the function called.

otid?: string | null

The offline threading id associated with this message

run\_id?: string | null

The id of the run that this message was created in.

sender\_id?: string | null

The id of the sender of the message, can be an identity id or agent id

step\_id?: string | null

The id of the step that this message was created in.

tool\_call\_id?: string | null

The ID of the tool call. Only applicable for role tool.

tool\_calls?: Array<ToolCall\> | null

The list of tool calls requested. Only applicable for role assistant.

id: string

function: Function { arguments, name }

The function that the model called.

arguments: string

name: string

type: "function"

tool\_returns?: Array<ToolReturn\> | null

Tool execution return information for prior tool calls

status: "success" | "error"

The status of the tool call

Accepts one of the following:

"success"

"error"

func\_response?: string | Array<[TextContent](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20text_content%20%3E%20(schema))
 { text, signature, type } | [ImageContent](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20image_content%20%3E%20(schema))
 { source, type } \> | null

The function response - either a string or list of content parts (text/image)

Accepts one of the following:

string

Array<[TextContent](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20text_content%20%3E%20(schema))
 { text, signature, type } | [ImageContent](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20image_content%20%3E%20(schema))
 { source, type } \>

TextContent { text, signature, type }

text: string

The text content of the message.

signature?: string | null

Stores a unique identifier for any reasoning associated with this text content.

type?: "text"

The type of the message.

ImageContent { source, type }

source: URLImage { url, type } | Base64Image { data, media\_type, detail, type } | LettaImage { file\_id, data, detail, 2 more }

The source of the image.

Accepts one of the following:

URLImage { url, type }

url: string

The URL of the image.

type?: "url"

The source type for the image.

Base64Image { data, media\_type, detail, type }

data: string

The base64 encoded image data.

media\_type: string

The media type for the image.

detail?: string | null

What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)

type?: "base64"

The source type for the image.

LettaImage { file\_id, data, detail, 2 more }

file\_id: string

The unique identifier of the image file persisted in storage.

data?: string | null

The base64 encoded image data.

detail?: string | null

What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)

media\_type?: string | null

The media type for the image.

type?: "letta"

The source type for the image.

type?: "image"

The type of the message.

stderr?: Array<string\> | null

Captured stderr from the tool invocation

stdout?: Array<string\> | null

Captured stdout (e.g. prints, logs) from the tool invocation

tool\_call\_id?: unknown

The ID for the tool call

updated\_at?: string | null

The timestamp when the object was last updated.

formatdate-time

rrf\_score: number

Reciprocal Rank Fusion combined score

fts\_rank?: number | null

Full-text search rank position if FTS was used

vector\_rank?: number | null

Vector search rank position if vector search was used

---

# Messages | Letta Docs

[Skip to content](https://docs.letta.com/api/python/resources/messages#_top)

[API Reference](https://docs.letta.com/api/python)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

* * *

**Copy Markdown**

**View as Markdown**

Messages
========

##### [List All Messages](https://docs.letta.com/api/python/resources/messages/methods/list)

messages.list(MessageListParams\*\*kwargs) \-> [MessageListResponse](https://docs.letta.com/api/python/resources/messages#(resource)%20messages%20%3E%20(model)%20message_list_response%20%3E%20(schema))

get/v1/messages/

##### [Retrieve Message](https://docs.letta.com/api/python/resources/messages/methods/retrieve)

messages.retrieve(strmessage\_id) \-> [MessageRetrieveResponse](https://docs.letta.com/api/python/resources/messages#(resource)%20messages%20%3E%20(model)%20message_retrieve_response%20%3E%20(schema))

get/v1/messages/{message\_id}

##### [Search All Messages](https://docs.letta.com/api/python/resources/messages/methods/search)

messages.search(MessageSearchParams\*\*kwargs) \-> [MessageSearchResponse](https://docs.letta.com/api/python/resources/messages#(resource)%20messages%20%3E%20(model)%20message_search_response%20%3E%20(schema))

post/v1/messages/search

##### ModelsExpand Collapse

class MessageSearchRequest: …

query: str

Text query for full-text search

agent\_id: Optional\[str\]

Filter messages by agent ID

conversation\_id: Optional\[str\]

Filter messages by conversation ID

end\_date: Optional\[datetime\]

Filter messages created on or before this date

formatdate-time

limit: Optional\[int\]

Maximum number of results to return

maximum100

minimum1

search\_mode: Optional\[Literal\["vector", "fts", "hybrid"\]\]

Search mode to use

Accepts one of the following:

"vector"

"fts"

"hybrid"

start\_date: Optional\[datetime\]

Filter messages created after this date

formatdate-time

class MessageSearchResult: …

Result from a message search operation with scoring details.

embedded\_text: str

The embedded content (LLM-friendly)

message: [InternalMessage](https://docs.letta.com/api/python/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20internal_message%20%3E%20(schema))

The raw message object

id: str

The human-friendly ID of the Message

role: [MessageRole](https://docs.letta.com/api/python/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20message_role%20%3E%20(schema))

The role of the participant.

Accepts one of the following:

"assistant"

"user"

"tool"

"function"

"system"

"approval"

"summary"

agent\_id: Optional\[str\]

The unique identifier of the agent.

approval\_request\_id: Optional\[str\]

The id of the approval request if this message is associated with a tool call request.

approvals: Optional\[List\[Approval\]\]

The list of approvals for this message.

Accepts one of the following:

class ApprovalReturn: …

approve: bool

Whether the tool has been approved

tool\_call\_id: str

The ID of the tool call that corresponds to this approval

reason: Optional\[str\]

An optional explanation for the provided approval status

type: Optional\[Literal\["approval"\]\]

The message type to be created.

class ApprovalLettaSchemasMessageToolReturnOutput: …

status: Literal\["success", "error"\]

The status of the tool call

Accepts one of the following:

"success"

"error"

func\_response: Optional\[Union\[str, List\[ApprovalLettaSchemasMessageToolReturnOutputFuncResponseUnionMember1\], null\]\]

The function response - either a string or list of content parts (text/image)

Accepts one of the following:

str

List\[ApprovalLettaSchemasMessageToolReturnOutputFuncResponseUnionMember1\]

Accepts one of the following:

class TextContent: …

text: str

The text content of the message.

signature: Optional\[str\]

Stores a unique identifier for any reasoning associated with this text content.

type: Optional\[Literal\["text"\]\]

The type of the message.

class ImageContent: …

source: Source

The source of the image.

Accepts one of the following:

class SourceURLImage: …

url: str

The URL of the image.

type: Optional\[Literal\["url"\]\]

The source type for the image.

class SourceBase64Image: …

data: str

The base64 encoded image data.

media\_type: str

The media type for the image.

detail: Optional\[str\]

What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)

type: Optional\[Literal\["base64"\]\]

The source type for the image.

class SourceLettaImage: …

file\_id: str

The unique identifier of the image file persisted in storage.

data: Optional\[str\]

The base64 encoded image data.

detail: Optional\[str\]

What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)

media\_type: Optional\[str\]

The media type for the image.

type: Optional\[Literal\["letta"\]\]

The source type for the image.

type: Optional\[Literal\["image"\]\]

The type of the message.

stderr: Optional\[List\[str\]\]

Captured stderr from the tool invocation

stdout: Optional\[List\[str\]\]

Captured stdout (e.g. prints, logs) from the tool invocation

tool\_call\_id: Optional\[object\]

The ID for the tool call

approve: Optional\[bool\]

Whether tool call is approved.

batch\_item\_id: Optional\[str\]

The id of the LLMBatchItem that this message is associated with

content: Optional\[List\[Content\]\]

The content of the message.

Accepts one of the following:

class TextContent: …

text: str

The text content of the message.

signature: Optional\[str\]

Stores a unique identifier for any reasoning associated with this text content.

type: Optional\[Literal\["text"\]\]

The type of the message.

class ImageContent: …

source: Source

The source of the image.

Accepts one of the following:

class SourceURLImage: …

url: str

The URL of the image.

type: Optional\[Literal\["url"\]\]

The source type for the image.

class SourceBase64Image: …

data: str

The base64 encoded image data.

media\_type: str

The media type for the image.

detail: Optional\[str\]

What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)

type: Optional\[Literal\["base64"\]\]

The source type for the image.

class SourceLettaImage: …

file\_id: str

The unique identifier of the image file persisted in storage.

data: Optional\[str\]

The base64 encoded image data.

detail: Optional\[str\]

What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)

media\_type: Optional\[str\]

The media type for the image.

type: Optional\[Literal\["letta"\]\]

The source type for the image.

type: Optional\[Literal\["image"\]\]

The type of the message.

class ToolCallContent: …

id: str

A unique identifier for this specific tool call instance.

input: Dict\[str, object\]

The parameters being passed to the tool, structured as a dictionary of parameter names to values.

name: str

The name of the tool being called.

signature: Optional\[str\]

Stores a unique identifier for any reasoning associated with this tool call.

type: Optional\[Literal\["tool\_call"\]\]

Indicates this content represents a tool call event.

class ToolReturnContent: …

content: str

The content returned by the tool execution.

is\_error: bool

Indicates whether the tool execution resulted in an error.

tool\_call\_id: str

References the ID of the ToolCallContent that initiated this tool call.

type: Optional\[Literal\["tool\_return"\]\]

Indicates this content represents a tool return event.

class ReasoningContent: …

Sent via the Anthropic Messages API

is\_native: bool

Whether the reasoning content was generated by a reasoner model that processed this step.

reasoning: str

The intermediate reasoning or thought process content.

signature: Optional\[str\]

A unique identifier for this reasoning step.

type: Optional\[Literal\["reasoning"\]\]

Indicates this is a reasoning/intermediate step.

class RedactedReasoningContent: …

Sent via the Anthropic Messages API

data: str

The redacted or filtered intermediate reasoning content.

type: Optional\[Literal\["redacted\_reasoning"\]\]

Indicates this is a redacted thinking step.

class OmittedReasoningContent: …

A placeholder for reasoning content we know is present, but isn't returned by the provider (e.g. OpenAI GPT-5 on ChatCompletions)

signature: Optional\[str\]

A unique identifier for this reasoning step.

type: Optional\[Literal\["omitted\_reasoning"\]\]

Indicates this is an omitted reasoning step.

class ContentSummarizedReasoningContent: …

The style of reasoning content returned by the OpenAI Responses API

id: str

The unique identifier for this reasoning step.

summary: List\[ContentSummarizedReasoningContentSummary\]

Summaries of the reasoning content.

index: int

The index of the summary part.

text: str

The text of the summary part.

encrypted\_content: Optional\[str\]

The encrypted reasoning content.

type: Optional\[Literal\["summarized\_reasoning"\]\]

Indicates this is a summarized reasoning step.

conversation\_id: Optional\[str\]

The conversation this message belongs to

created\_at: Optional\[datetime\]

The timestamp when the object was created.

formatdate-time

created\_by\_id: Optional\[str\]

The id of the user that made this object.

denial\_reason: Optional\[str\]

The reason the tool call request was denied.

group\_id: Optional\[str\]

The multi-agent group that the message was sent in

is\_err: Optional\[bool\]

Whether this message is part of an error step. Used only for debugging purposes.

last\_updated\_by\_id: Optional\[str\]

The id of the user that made this object.

model: Optional\[str\]

The model used to make the function call.

name: Optional\[str\]

For role user/assistant: the (optional) name of the participant. For role tool/function: the name of the function called.

otid: Optional\[str\]

The offline threading id associated with this message

run\_id: Optional\[str\]

The id of the run that this message was created in.

sender\_id: Optional\[str\]

The id of the sender of the message, can be an identity id or agent id

step\_id: Optional\[str\]

The id of the step that this message was created in.

tool\_call\_id: Optional\[str\]

The ID of the tool call. Only applicable for role tool.

tool\_calls: Optional\[List\[ToolCall\]\]

The list of tool calls requested. Only applicable for role assistant.

id: str

function: ToolCallFunction

The function that the model called.

arguments: str

name: str

type: Literal\["function"\]

tool\_returns: Optional\[List\[ToolReturn\]\]

Tool execution return information for prior tool calls

status: Literal\["success", "error"\]

The status of the tool call

Accepts one of the following:

"success"

"error"

func\_response: Optional\[Union\[str, List\[ToolReturnFuncResponseUnionMember1\], null\]\]

The function response - either a string or list of content parts (text/image)

Accepts one of the following:

str

List\[ToolReturnFuncResponseUnionMember1\]

Accepts one of the following:

class TextContent: …

text: str

The text content of the message.

signature: Optional\[str\]

Stores a unique identifier for any reasoning associated with this text content.

type: Optional\[Literal\["text"\]\]

The type of the message.

class ImageContent: …

source: Source

The source of the image.

Accepts one of the following:

class SourceURLImage: …

url: str

The URL of the image.

type: Optional\[Literal\["url"\]\]

The source type for the image.

class SourceBase64Image: …

data: str

The base64 encoded image data.

media\_type: str

The media type for the image.

detail: Optional\[str\]

What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)

type: Optional\[Literal\["base64"\]\]

The source type for the image.

class SourceLettaImage: …

file\_id: str

The unique identifier of the image file persisted in storage.

data: Optional\[str\]

The base64 encoded image data.

detail: Optional\[str\]

What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)

media\_type: Optional\[str\]

The media type for the image.

type: Optional\[Literal\["letta"\]\]

The source type for the image.

type: Optional\[Literal\["image"\]\]

The type of the message.

stderr: Optional\[List\[str\]\]

Captured stderr from the tool invocation

stdout: Optional\[List\[str\]\]

Captured stdout (e.g. prints, logs) from the tool invocation

tool\_call\_id: Optional\[object\]

The ID for the tool call

updated\_at: Optional\[datetime\]

The timestamp when the object was last updated.

formatdate-time

rrf\_score: float

Reciprocal Rank Fusion combined score

fts\_rank: Optional\[int\]

Full-text search rank position if FTS was used

vector\_rank: Optional\[int\]

Vector search rank position if vector search was used

---

# Steps | Letta Docs

[Skip to content](https://docs.letta.com/api/python/resources/steps#_top)

[API Reference](https://docs.letta.com/api/python)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

* * *

**Copy Markdown**

**View as Markdown**

Steps
=====

##### [List Steps](https://docs.letta.com/api/python/resources/steps/methods/list)

steps.list(StepListParams\*\*kwargs) \-> SyncArrayPage\[[Step](https://docs.letta.com/api/python/resources/steps#(resource)%20steps%20%3E%20(model)%20step%20%3E%20(schema))\
\]

get/v1/steps/

##### [Retrieve Step](https://docs.letta.com/api/python/resources/steps/methods/retrieve)

steps.retrieve(strstep\_id) \-> [Step](https://docs.letta.com/api/python/resources/steps#(resource)%20steps%20%3E%20(model)%20step%20%3E%20(schema))

get/v1/steps/{step\_id}

##### ModelsExpand Collapse

class ProviderTrace: …

Letta's internal representation of a provider trace.

Attributes: id (str): The unique identifier of the provider trace. request\_json (Dict\[str, Any\]): JSON content of the provider request. response\_json (Dict\[str, Any\]): JSON content of the provider response. step\_id (str): ID of the step that this trace is associated with. agent\_id (str): ID of the agent that generated this trace. agent\_tags (list\[str\]): Tags associated with the agent for filtering. call\_type (str): Type of call (agent\_step, summarization, etc.). run\_id (str): ID of the run this trace is associated with. source (str): Source service that generated this trace (memgpt-server, lettuce-py). organization\_id (str): The unique identifier of the organization. user\_id (str): The unique identifier of the user who initiated the request. compaction\_settings (Dict\[str, Any\]): Compaction/summarization settings (only for summarization calls). llm\_config (Dict\[str, Any\]): LLM configuration used for this call (only for non-summarization calls). created\_at (datetime): The timestamp when the object was created.

request\_json: Dict\[str, object\]

JSON content of the provider request

response\_json: Dict\[str, object\]

JSON content of the provider response

id: Optional\[str\]

The human-friendly ID of the Provider\_trace

agent\_id: Optional\[str\]

ID of the agent that generated this trace

agent\_tags: Optional\[List\[str\]\]

Tags associated with the agent for filtering

billing\_context: Optional\[BillingContext\]

Billing context for LLM request cost tracking.

cost\_source: Optional\[str\]

Cost source: 'quota' or 'credits'

customer\_id: Optional\[str\]

Customer ID for billing records

plan\_type: Optional\[str\]

Subscription tier

call\_type: Optional\[str\]

Type of call (agent\_step, summarization, etc.)

compaction\_settings: Optional\[Dict\[str, object\]\]

Compaction/summarization settings (summarization calls only)

created\_at: Optional\[datetime\]

The timestamp when the object was created.

formatdate-time

created\_by\_id: Optional\[str\]

The id of the user that made this object.

last\_updated\_by\_id: Optional\[str\]

The id of the user that made this object.

latency\_ms: Optional\[int\]

LLM request latency in milliseconds

llm\_config: Optional\[Dict\[str, object\]\]

LLM configuration used for this call (non-summarization calls only)

org\_id: Optional\[str\]

ID of the organization

run\_id: Optional\[str\]

ID of the run this trace is associated with

source: Optional\[str\]

Source service that generated this trace (memgpt-server, lettuce-py)

step\_id: Optional\[str\]

ID of the step that this trace is associated with

updated\_at: Optional\[datetime\]

The timestamp when the object was last updated.

formatdate-time

class Step: …

id: str

The id of the step. Assigned by the database.

agent\_id: Optional\[str\]

The ID of the agent that performed the step.

cache\_write\_tokens: Optional\[int\]

The number of input tokens written to cache (Anthropic only). None if not reported by provider.

cached\_input\_tokens: Optional\[int\]

The number of input tokens served from cache. None if not reported by provider.

completion\_tokens: Optional\[int\]

The number of tokens generated by the agent during this step.

completion\_tokens\_details: Optional\[Dict\[str, object\]\]

Detailed completion token breakdown (e.g., reasoning\_tokens).

context\_window\_limit: Optional\[int\]

The context window limit configured for this step.

error\_data: Optional\[Dict\[str, object\]\]

Error details including message, traceback, and additional context

error\_type: Optional\[str\]

The type/class of the error that occurred

feedback: Optional\[Literal\["positive", "negative"\]\]

The feedback for this step. Must be either 'positive' or 'negative'.

Accepts one of the following:

"positive"

"negative"

Deprecatedmessages: Optional\[List\[[InternalMessage](https://docs.letta.com/api/python/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20internal_message%20%3E%20(schema))\
\]\]

The messages generated during this step. Deprecated: use `GET /v1/steps/{step_id}/messages` endpoint instead

id: str

The human-friendly ID of the Message

role: [MessageRole](https://docs.letta.com/api/python/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20message_role%20%3E%20(schema))

The role of the participant.

Accepts one of the following:

"assistant"

"user"

"tool"

"function"

"system"

"approval"

"summary"

agent\_id: Optional\[str\]

The unique identifier of the agent.

approval\_request\_id: Optional\[str\]

The id of the approval request if this message is associated with a tool call request.

approvals: Optional\[List\[Approval\]\]

The list of approvals for this message.

Accepts one of the following:

class ApprovalReturn: …

approve: bool

Whether the tool has been approved

tool\_call\_id: str

The ID of the tool call that corresponds to this approval

reason: Optional\[str\]

An optional explanation for the provided approval status

type: Optional\[Literal\["approval"\]\]

The message type to be created.

class ApprovalLettaSchemasMessageToolReturnOutput: …

status: Literal\["success", "error"\]

The status of the tool call

Accepts one of the following:

"success"

"error"

func\_response: Optional\[Union\[str, List\[ApprovalLettaSchemasMessageToolReturnOutputFuncResponseUnionMember1\], null\]\]

The function response - either a string or list of content parts (text/image)

Accepts one of the following:

str

List\[ApprovalLettaSchemasMessageToolReturnOutputFuncResponseUnionMember1\]

Accepts one of the following:

class TextContent: …

text: str

The text content of the message.

signature: Optional\[str\]

Stores a unique identifier for any reasoning associated with this text content.

type: Optional\[Literal\["text"\]\]

The type of the message.

class ImageContent: …

source: Source

The source of the image.

Accepts one of the following:

class SourceURLImage: …

url: str

The URL of the image.

type: Optional\[Literal\["url"\]\]

The source type for the image.

class SourceBase64Image: …

data: str

The base64 encoded image data.

media\_type: str

The media type for the image.

detail: Optional\[str\]

What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)

type: Optional\[Literal\["base64"\]\]

The source type for the image.

class SourceLettaImage: …

file\_id: str

The unique identifier of the image file persisted in storage.

data: Optional\[str\]

The base64 encoded image data.

detail: Optional\[str\]

What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)

media\_type: Optional\[str\]

The media type for the image.

type: Optional\[Literal\["letta"\]\]

The source type for the image.

type: Optional\[Literal\["image"\]\]

The type of the message.

stderr: Optional\[List\[str\]\]

Captured stderr from the tool invocation

stdout: Optional\[List\[str\]\]

Captured stdout (e.g. prints, logs) from the tool invocation

tool\_call\_id: Optional\[object\]

The ID for the tool call

approve: Optional\[bool\]

Whether tool call is approved.

batch\_item\_id: Optional\[str\]

The id of the LLMBatchItem that this message is associated with

content: Optional\[List\[Content\]\]

The content of the message.

Accepts one of the following:

class TextContent: …

text: str

The text content of the message.

signature: Optional\[str\]

Stores a unique identifier for any reasoning associated with this text content.

type: Optional\[Literal\["text"\]\]

The type of the message.

class ImageContent: …

source: Source

The source of the image.

Accepts one of the following:

class SourceURLImage: …

url: str

The URL of the image.

type: Optional\[Literal\["url"\]\]

The source type for the image.

class SourceBase64Image: …

data: str

The base64 encoded image data.

media\_type: str

The media type for the image.

detail: Optional\[str\]

What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)

type: Optional\[Literal\["base64"\]\]

The source type for the image.

class SourceLettaImage: …

file\_id: str

The unique identifier of the image file persisted in storage.

data: Optional\[str\]

The base64 encoded image data.

detail: Optional\[str\]

What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)

media\_type: Optional\[str\]

The media type for the image.

type: Optional\[Literal\["letta"\]\]

The source type for the image.

type: Optional\[Literal\["image"\]\]

The type of the message.

class ToolCallContent: …

id: str

A unique identifier for this specific tool call instance.

input: Dict\[str, object\]

The parameters being passed to the tool, structured as a dictionary of parameter names to values.

name: str

The name of the tool being called.

signature: Optional\[str\]

Stores a unique identifier for any reasoning associated with this tool call.

type: Optional\[Literal\["tool\_call"\]\]

Indicates this content represents a tool call event.

class ToolReturnContent: …

content: str

The content returned by the tool execution.

is\_error: bool

Indicates whether the tool execution resulted in an error.

tool\_call\_id: str

References the ID of the ToolCallContent that initiated this tool call.

type: Optional\[Literal\["tool\_return"\]\]

Indicates this content represents a tool return event.

class ReasoningContent: …

Sent via the Anthropic Messages API

is\_native: bool

Whether the reasoning content was generated by a reasoner model that processed this step.

reasoning: str

The intermediate reasoning or thought process content.

signature: Optional\[str\]

A unique identifier for this reasoning step.

type: Optional\[Literal\["reasoning"\]\]

Indicates this is a reasoning/intermediate step.

class RedactedReasoningContent: …

Sent via the Anthropic Messages API

data: str

The redacted or filtered intermediate reasoning content.

type: Optional\[Literal\["redacted\_reasoning"\]\]

Indicates this is a redacted thinking step.

class OmittedReasoningContent: …

A placeholder for reasoning content we know is present, but isn't returned by the provider (e.g. OpenAI GPT-5 on ChatCompletions)

signature: Optional\[str\]

A unique identifier for this reasoning step.

type: Optional\[Literal\["omitted\_reasoning"\]\]

Indicates this is an omitted reasoning step.

class ContentSummarizedReasoningContent: …

The style of reasoning content returned by the OpenAI Responses API

id: str

The unique identifier for this reasoning step.

summary: List\[ContentSummarizedReasoningContentSummary\]

Summaries of the reasoning content.

index: int

The index of the summary part.

text: str

The text of the summary part.

encrypted\_content: Optional\[str\]

The encrypted reasoning content.

type: Optional\[Literal\["summarized\_reasoning"\]\]

Indicates this is a summarized reasoning step.

conversation\_id: Optional\[str\]

The conversation this message belongs to

created\_at: Optional\[datetime\]

The timestamp when the object was created.

formatdate-time

created\_by\_id: Optional\[str\]

The id of the user that made this object.

denial\_reason: Optional\[str\]

The reason the tool call request was denied.

group\_id: Optional\[str\]

The multi-agent group that the message was sent in

is\_err: Optional\[bool\]

Whether this message is part of an error step. Used only for debugging purposes.

last\_updated\_by\_id: Optional\[str\]

The id of the user that made this object.

model: Optional\[str\]

The model used to make the function call.

name: Optional\[str\]

For role user/assistant: the (optional) name of the participant. For role tool/function: the name of the function called.

otid: Optional\[str\]

The offline threading id associated with this message

run\_id: Optional\[str\]

The id of the run that this message was created in.

sender\_id: Optional\[str\]

The id of the sender of the message, can be an identity id or agent id

step\_id: Optional\[str\]

The id of the step that this message was created in.

tool\_call\_id: Optional\[str\]

The ID of the tool call. Only applicable for role tool.

tool\_calls: Optional\[List\[ToolCall\]\]

The list of tool calls requested. Only applicable for role assistant.

id: str

function: ToolCallFunction

The function that the model called.

arguments: str

name: str

type: Literal\["function"\]

tool\_returns: Optional\[List\[ToolReturn\]\]

Tool execution return information for prior tool calls

status: Literal\["success", "error"\]

The status of the tool call

Accepts one of the following:

"success"

"error"

func\_response: Optional\[Union\[str, List\[ToolReturnFuncResponseUnionMember1\], null\]\]

The function response - either a string or list of content parts (text/image)

Accepts one of the following:

str

List\[ToolReturnFuncResponseUnionMember1\]

Accepts one of the following:

class TextContent: …

text: str

The text content of the message.

signature: Optional\[str\]

Stores a unique identifier for any reasoning associated with this text content.

type: Optional\[Literal\["text"\]\]

The type of the message.

class ImageContent: …

source: Source

The source of the image.

Accepts one of the following:

class SourceURLImage: …

url: str

The URL of the image.

type: Optional\[Literal\["url"\]\]

The source type for the image.

class SourceBase64Image: …

data: str

The base64 encoded image data.

media\_type: str

The media type for the image.

detail: Optional\[str\]

What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)

type: Optional\[Literal\["base64"\]\]

The source type for the image.

class SourceLettaImage: …

file\_id: str

The unique identifier of the image file persisted in storage.

data: Optional\[str\]

The base64 encoded image data.

detail: Optional\[str\]

What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)

media\_type: Optional\[str\]

The media type for the image.

type: Optional\[Literal\["letta"\]\]

The source type for the image.

type: Optional\[Literal\["image"\]\]

The type of the message.

stderr: Optional\[List\[str\]\]

Captured stderr from the tool invocation

stdout: Optional\[List\[str\]\]

Captured stdout (e.g. prints, logs) from the tool invocation

tool\_call\_id: Optional\[object\]

The ID for the tool call

updated\_at: Optional\[datetime\]

The timestamp when the object was last updated.

formatdate-time

model: Optional\[str\]

The name of the model used for this step.

model\_endpoint: Optional\[str\]

The model endpoint url used for this step.

model\_handle: Optional\[str\]

The model handle (e.g., 'openai/gpt-4o-mini') used for this step.

origin: Optional\[str\]

The surface that this agent step was initiated from.

project\_id: Optional\[str\]

The project that the agent that executed this step belongs to (cloud only).

prompt\_tokens: Optional\[int\]

The number of tokens in the prompt during this step.

prompt\_tokens\_details: Optional\[Dict\[str, object\]\]

Detailed prompt token breakdown (e.g., cached\_tokens, cache\_read\_tokens, cache\_creation\_tokens).

provider\_category: Optional\[str\]

The category of the provider used for this step.

provider\_id: Optional\[str\]

The unique identifier of the provider that was configured for this step

provider\_name: Optional\[str\]

The name of the provider used for this step.

reasoning\_tokens: Optional\[int\]

The number of reasoning/thinking tokens generated. None if not reported by provider.

request\_id: Optional\[str\]

The API request log ID from cloud-api for correlating steps with API requests.

run\_id: Optional\[str\]

The unique identifier of the run that this step belongs to. Only included for async calls.

status: Optional\[Literal\["pending", "success", "failed", "cancelled"\]\]

Status of a step execution

Accepts one of the following:

"pending"

"success"

"failed"

"cancelled"

stop\_reason: Optional\[StopReasonType\]

The stop reason associated with the step.

Accepts one of the following:

"end\_turn"

"error"

"llm\_api\_error"

"invalid\_llm\_response"

"invalid\_tool\_call"

"max\_steps"

"max\_tokens\_exceeded"

"no\_tool\_call"

"tool\_rule"

"cancelled"

"insufficient\_credits"

"requires\_approval"

"context\_window\_overflow\_in\_system\_prompt"

tags: Optional\[List\[str\]\]

Metadata tags.

tid: Optional\[str\]

The unique identifier of the transaction that processed this step.

total\_tokens: Optional\[int\]

The total number of tokens processed by the agent during this step.

trace\_id: Optional\[str\]

The trace id of the agent step.

#### StepsMetrics

##### [Retrieve Metrics For Step](https://docs.letta.com/api/python/resources/steps/subresources/metrics/methods/retrieve)

steps.metrics.retrieve(strstep\_id) \-> [MetricRetrieveResponse](https://docs.letta.com/api/python/resources/steps#(resource)%20steps.metrics%20%3E%20(model)%20metric_retrieve_response%20%3E%20(schema))

get/v1/steps/{step\_id}/metrics

#### StepsTrace

##### [Retrieve Trace For Step](https://docs.letta.com/api/python/resources/steps/subresources/trace/methods/retrieve)

steps.trace.retrieve(strstep\_id) \-> [ProviderTrace](https://docs.letta.com/api/python/resources/steps#(resource)%20steps%20%3E%20(model)%20provider_trace%20%3E%20(schema))

get/v1/steps/{step\_id}/trace

#### StepsFeedback

##### [Modify Feedback For Step](https://docs.letta.com/api/python/resources/steps/subresources/feedback/methods/create)

steps.feedback.create(strstep\_id, FeedbackCreateParams\*\*kwargs) \-> [Step](https://docs.letta.com/api/python/resources/steps#(resource)%20steps%20%3E%20(model)%20step%20%3E%20(schema))

patch/v1/steps/{step\_id}/feedback

#### StepsMessages

##### [List Messages For Step](https://docs.letta.com/api/python/resources/steps/subresources/messages/methods/list)

steps.messages.list(strstep\_id, MessageListParams\*\*kwargs) \-> SyncArrayPage\[[MessageListResponse](https://docs.letta.com/api/python/resources/steps#(resource)%20steps.messages%20%3E%20(model)%20message_list_response%20%3E%20(schema))\
\]

get/v1/steps/{step\_id}/messages

---

# Steps | Letta Docs

[Skip to content](https://docs.letta.com/api/typescript/resources/steps#_top)

[API Reference](https://docs.letta.com/api/typescript)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

* * *

**Copy Markdown**

**View as Markdown**

Steps
=====

##### [List Steps](https://docs.letta.com/api/typescript/resources/steps/methods/list)

client.steps.list(StepListParams { after, agent\_id, before, 11 more } query?, RequestOptionsoptions?): ArrayPage<[Step](https://docs.letta.com/api/typescript/resources/steps#(resource)%20steps%20%3E%20(model)%20step%20%3E%20(schema))
 { id, agent\_id, cache\_write\_tokens, 27 more } \>

get/v1/steps/

##### [Retrieve Step](https://docs.letta.com/api/typescript/resources/steps/methods/retrieve)

client.steps.retrieve(stringstepID, RequestOptionsoptions?): [Step](https://docs.letta.com/api/typescript/resources/steps#(resource)%20steps%20%3E%20(model)%20step%20%3E%20(schema))
 { id, agent\_id, cache\_write\_tokens, 27 more }

get/v1/steps/{step\_id}

##### ModelsExpand Collapse

ProviderTrace { request\_json, response\_json, id, 15 more }

Letta's internal representation of a provider trace.

Attributes: id (str): The unique identifier of the provider trace. request\_json (Dict\[str, Any\]): JSON content of the provider request. response\_json (Dict\[str, Any\]): JSON content of the provider response. step\_id (str): ID of the step that this trace is associated with. agent\_id (str): ID of the agent that generated this trace. agent\_tags (list\[str\]): Tags associated with the agent for filtering. call\_type (str): Type of call (agent\_step, summarization, etc.). run\_id (str): ID of the run this trace is associated with. source (str): Source service that generated this trace (memgpt-server, lettuce-py). organization\_id (str): The unique identifier of the organization. user\_id (str): The unique identifier of the user who initiated the request. compaction\_settings (Dict\[str, Any\]): Compaction/summarization settings (only for summarization calls). llm\_config (Dict\[str, Any\]): LLM configuration used for this call (only for non-summarization calls). created\_at (datetime): The timestamp when the object was created.

request\_json: Record<string, unknown\>

JSON content of the provider request

response\_json: Record<string, unknown\>

JSON content of the provider response

id?: string

The human-friendly ID of the Provider\_trace

agent\_id?: string | null

ID of the agent that generated this trace

agent\_tags?: Array<string\> | null

Tags associated with the agent for filtering

billing\_context?: BillingContext | null

Billing context for LLM request cost tracking.

cost\_source?: string | null

Cost source: 'quota' or 'credits'

customer\_id?: string | null

Customer ID for billing records

plan\_type?: string | null

Subscription tier

call\_type?: string | null

Type of call (agent\_step, summarization, etc.)

compaction\_settings?: Record<string, unknown\> | null

Compaction/summarization settings (summarization calls only)

created\_at?: string

The timestamp when the object was created.

formatdate-time

created\_by\_id?: string | null

The id of the user that made this object.

last\_updated\_by\_id?: string | null

The id of the user that made this object.

latency\_ms?: number | null

LLM request latency in milliseconds

llm\_config?: Record<string, unknown\> | null

LLM configuration used for this call (non-summarization calls only)

org\_id?: string | null

ID of the organization

run\_id?: string | null

ID of the run this trace is associated with

source?: string | null

Source service that generated this trace (memgpt-server, lettuce-py)

step\_id?: string | null

ID of the step that this trace is associated with

updated\_at?: string | null

The timestamp when the object was last updated.

formatdate-time

Step { id, agent\_id, cache\_write\_tokens, 27 more }

id: string

The id of the step. Assigned by the database.

agent\_id?: string | null

The ID of the agent that performed the step.

cache\_write\_tokens?: number | null

The number of input tokens written to cache (Anthropic only). None if not reported by provider.

cached\_input\_tokens?: number | null

The number of input tokens served from cache. None if not reported by provider.

completion\_tokens?: number | null

The number of tokens generated by the agent during this step.

completion\_tokens\_details?: Record<string, unknown\> | null

Detailed completion token breakdown (e.g., reasoning\_tokens).

context\_window\_limit?: number | null

The context window limit configured for this step.

error\_data?: Record<string, unknown\> | null

Error details including message, traceback, and additional context

error\_type?: string | null

The type/class of the error that occurred

feedback?: "positive" | "negative" | null

The feedback for this step. Must be either 'positive' or 'negative'.

Accepts one of the following:

"positive"

"negative"

Deprecatedmessages?: Array<[InternalMessage](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20internal_message%20%3E%20(schema))
 { id, role, agent\_id, 22 more } \>

The messages generated during this step. Deprecated: use `GET /v1/steps/{step_id}/messages` endpoint instead

id: string

The human-friendly ID of the Message

role: [MessageRole](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20message_role%20%3E%20(schema))

The role of the participant.

Accepts one of the following:

"assistant"

"user"

"tool"

"function"

"system"

"approval"

"summary"

agent\_id?: string | null

The unique identifier of the agent.

approval\_request\_id?: string | null

The id of the approval request if this message is associated with a tool call request.

approvals?: Array<[ApprovalReturn](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20approval_return%20%3E%20(schema))
 { approve, tool\_call\_id, reason, type } | LettaSchemasMessageToolReturnOutput { status, func\_response, stderr, 2 more } \> | null

The list of approvals for this message.

Accepts one of the following:

ApprovalReturn { approve, tool\_call\_id, reason, type }

approve: boolean

Whether the tool has been approved

tool\_call\_id: string

The ID of the tool call that corresponds to this approval

reason?: string | null

An optional explanation for the provided approval status

type?: "approval"

The message type to be created.

LettaSchemasMessageToolReturnOutput { status, func\_response, stderr, 2 more }

status: "success" | "error"

The status of the tool call

Accepts one of the following:

"success"

"error"

func\_response?: string | Array<[TextContent](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20text_content%20%3E%20(schema))
 { text, signature, type } | [ImageContent](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20image_content%20%3E%20(schema))
 { source, type } \> | null

The function response - either a string or list of content parts (text/image)

Accepts one of the following:

string

Array<[TextContent](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20text_content%20%3E%20(schema))
 { text, signature, type } | [ImageContent](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20image_content%20%3E%20(schema))
 { source, type } \>

TextContent { text, signature, type }

text: string

The text content of the message.

signature?: string | null

Stores a unique identifier for any reasoning associated with this text content.

type?: "text"

The type of the message.

ImageContent { source, type }

source: URLImage { url, type } | Base64Image { data, media\_type, detail, type } | LettaImage { file\_id, data, detail, 2 more }

The source of the image.

Accepts one of the following:

URLImage { url, type }

url: string

The URL of the image.

type?: "url"

The source type for the image.

Base64Image { data, media\_type, detail, type }

data: string

The base64 encoded image data.

media\_type: string

The media type for the image.

detail?: string | null

What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)

type?: "base64"

The source type for the image.

LettaImage { file\_id, data, detail, 2 more }

file\_id: string

The unique identifier of the image file persisted in storage.

data?: string | null

The base64 encoded image data.

detail?: string | null

What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)

media\_type?: string | null

The media type for the image.

type?: "letta"

The source type for the image.

type?: "image"

The type of the message.

stderr?: Array<string\> | null

Captured stderr from the tool invocation

stdout?: Array<string\> | null

Captured stdout (e.g. prints, logs) from the tool invocation

tool\_call\_id?: unknown

The ID for the tool call

approve?: boolean | null

Whether tool call is approved.

batch\_item\_id?: string | null

The id of the LLMBatchItem that this message is associated with

content?: Array<[TextContent](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20text_content%20%3E%20(schema))
 { text, signature, type } | [ImageContent](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20image_content%20%3E%20(schema))
 { source, type } | [ToolCallContent](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20tool_call_content%20%3E%20(schema))
 { id, input, name, 2 more } | 5 more\> | null

The content of the message.

Accepts one of the following:

TextContent { text, signature, type }

text: string

The text content of the message.

signature?: string | null

Stores a unique identifier for any reasoning associated with this text content.

type?: "text"

The type of the message.

ImageContent { source, type }

source: URLImage { url, type } | Base64Image { data, media\_type, detail, type } | LettaImage { file\_id, data, detail, 2 more }

The source of the image.

Accepts one of the following:

URLImage { url, type }

url: string

The URL of the image.

type?: "url"

The source type for the image.

Base64Image { data, media\_type, detail, type }

data: string

The base64 encoded image data.

media\_type: string

The media type for the image.

detail?: string | null

What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)

type?: "base64"

The source type for the image.

LettaImage { file\_id, data, detail, 2 more }

file\_id: string

The unique identifier of the image file persisted in storage.

data?: string | null

The base64 encoded image data.

detail?: string | null

What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)

media\_type?: string | null

The media type for the image.

type?: "letta"

The source type for the image.

type?: "image"

The type of the message.

ToolCallContent { id, input, name, 2 more }

id: string

A unique identifier for this specific tool call instance.

input: Record<string, unknown\>

The parameters being passed to the tool, structured as a dictionary of parameter names to values.

name: string

The name of the tool being called.

signature?: string | null

Stores a unique identifier for any reasoning associated with this tool call.

type?: "tool\_call"

Indicates this content represents a tool call event.

ToolReturnContent { content, is\_error, tool\_call\_id, type }

content: string

The content returned by the tool execution.

is\_error: boolean

Indicates whether the tool execution resulted in an error.

tool\_call\_id: string

References the ID of the ToolCallContent that initiated this tool call.

type?: "tool\_return"

Indicates this content represents a tool return event.

ReasoningContent { is\_native, reasoning, signature, type }

Sent via the Anthropic Messages API

is\_native: boolean

Whether the reasoning content was generated by a reasoner model that processed this step.

reasoning: string

The intermediate reasoning or thought process content.

signature?: string | null

A unique identifier for this reasoning step.

type?: "reasoning"

Indicates this is a reasoning/intermediate step.

RedactedReasoningContent { data, type }

Sent via the Anthropic Messages API

data: string

The redacted or filtered intermediate reasoning content.

type?: "redacted\_reasoning"

Indicates this is a redacted thinking step.

OmittedReasoningContent { signature, type }

A placeholder for reasoning content we know is present, but isn't returned by the provider (e.g. OpenAI GPT-5 on ChatCompletions)

signature?: string | null

A unique identifier for this reasoning step.

type?: "omitted\_reasoning"

Indicates this is an omitted reasoning step.

SummarizedReasoningContent { id, summary, encrypted\_content, type }

The style of reasoning content returned by the OpenAI Responses API

id: string

The unique identifier for this reasoning step.

summary: Array<Summary\>

Summaries of the reasoning content.

index: number

The index of the summary part.

text: string

The text of the summary part.

encrypted\_content?: string

The encrypted reasoning content.

type?: "summarized\_reasoning"

Indicates this is a summarized reasoning step.

conversation\_id?: string | null

The conversation this message belongs to

created\_at?: string

The timestamp when the object was created.

formatdate-time

created\_by\_id?: string | null

The id of the user that made this object.

denial\_reason?: string | null

The reason the tool call request was denied.

group\_id?: string | null

The multi-agent group that the message was sent in

is\_err?: boolean | null

Whether this message is part of an error step. Used only for debugging purposes.

last\_updated\_by\_id?: string | null

The id of the user that made this object.

model?: string | null

The model used to make the function call.

name?: string | null

For role user/assistant: the (optional) name of the participant. For role tool/function: the name of the function called.

otid?: string | null

The offline threading id associated with this message

run\_id?: string | null

The id of the run that this message was created in.

sender\_id?: string | null

The id of the sender of the message, can be an identity id or agent id

step\_id?: string | null

The id of the step that this message was created in.

tool\_call\_id?: string | null

The ID of the tool call. Only applicable for role tool.

tool\_calls?: Array<ToolCall\> | null

The list of tool calls requested. Only applicable for role assistant.

id: string

function: Function { arguments, name }

The function that the model called.

arguments: string

name: string

type: "function"

tool\_returns?: Array<ToolReturn\> | null

Tool execution return information for prior tool calls

status: "success" | "error"

The status of the tool call

Accepts one of the following:

"success"

"error"

func\_response?: string | Array<[TextContent](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20text_content%20%3E%20(schema))
 { text, signature, type } | [ImageContent](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20image_content%20%3E%20(schema))
 { source, type } \> | null

The function response - either a string or list of content parts (text/image)

Accepts one of the following:

string

Array<[TextContent](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20text_content%20%3E%20(schema))
 { text, signature, type } | [ImageContent](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20image_content%20%3E%20(schema))
 { source, type } \>

TextContent { text, signature, type }

text: string

The text content of the message.

signature?: string | null

Stores a unique identifier for any reasoning associated with this text content.

type?: "text"

The type of the message.

ImageContent { source, type }

source: URLImage { url, type } | Base64Image { data, media\_type, detail, type } | LettaImage { file\_id, data, detail, 2 more }

The source of the image.

Accepts one of the following:

URLImage { url, type }

url: string

The URL of the image.

type?: "url"

The source type for the image.

Base64Image { data, media\_type, detail, type }

data: string

The base64 encoded image data.

media\_type: string

The media type for the image.

detail?: string | null

What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)

type?: "base64"

The source type for the image.

LettaImage { file\_id, data, detail, 2 more }

file\_id: string

The unique identifier of the image file persisted in storage.

data?: string | null

The base64 encoded image data.

detail?: string | null

What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)

media\_type?: string | null

The media type for the image.

type?: "letta"

The source type for the image.

type?: "image"

The type of the message.

stderr?: Array<string\> | null

Captured stderr from the tool invocation

stdout?: Array<string\> | null

Captured stdout (e.g. prints, logs) from the tool invocation

tool\_call\_id?: unknown

The ID for the tool call

updated\_at?: string | null

The timestamp when the object was last updated.

formatdate-time

model?: string | null

The name of the model used for this step.

model\_endpoint?: string | null

The model endpoint url used for this step.

model\_handle?: string | null

The model handle (e.g., 'openai/gpt-4o-mini') used for this step.

origin?: string | null

The surface that this agent step was initiated from.

project\_id?: string | null

The project that the agent that executed this step belongs to (cloud only).

prompt\_tokens?: number | null

The number of tokens in the prompt during this step.

prompt\_tokens\_details?: Record<string, unknown\> | null

Detailed prompt token breakdown (e.g., cached\_tokens, cache\_read\_tokens, cache\_creation\_tokens).

provider\_category?: string | null

The category of the provider used for this step.

provider\_id?: string | null

The unique identifier of the provider that was configured for this step

provider\_name?: string | null

The name of the provider used for this step.

reasoning\_tokens?: number | null

The number of reasoning/thinking tokens generated. None if not reported by provider.

request\_id?: string | null

The API request log ID from cloud-api for correlating steps with API requests.

run\_id?: string | null

The unique identifier of the run that this step belongs to. Only included for async calls.

status?: "pending" | "success" | "failed" | "cancelled" | null

Status of a step execution

Accepts one of the following:

"pending"

"success"

"failed"

"cancelled"

stop\_reason?: [StopReasonType](https://docs.letta.com/api/typescript/resources/runs#(resource)%20runs%20%3E%20(model)%20stop_reason_type%20%3E%20(schema))
 | null

The stop reason associated with the step.

Accepts one of the following:

"end\_turn"

"error"

"llm\_api\_error"

"invalid\_llm\_response"

"invalid\_tool\_call"

"max\_steps"

"max\_tokens\_exceeded"

"no\_tool\_call"

"tool\_rule"

"cancelled"

"insufficient\_credits"

"requires\_approval"

"context\_window\_overflow\_in\_system\_prompt"

tags?: Array<string\>

Metadata tags.

tid?: string | null

The unique identifier of the transaction that processed this step.

total\_tokens?: number | null

The total number of tokens processed by the agent during this step.

trace\_id?: string | null

The trace id of the agent step.

#### StepsMetrics

##### [Retrieve Metrics For Step](https://docs.letta.com/api/typescript/resources/steps/subresources/metrics/methods/retrieve)

client.steps.metrics.retrieve(stringstepID, RequestOptionsoptions?): [MetricRetrieveResponse](https://docs.letta.com/api/typescript/resources/steps#(resource)%20steps.metrics%20%3E%20(model)%20metric_retrieve_response%20%3E%20(schema))
 { id, agent\_id, base\_template\_id, 9 more }

get/v1/steps/{step\_id}/metrics

#### StepsTrace

##### [Retrieve Trace For Step](https://docs.letta.com/api/typescript/resources/steps/subresources/trace/methods/retrieve)

client.steps.trace.retrieve(stringstepID, RequestOptionsoptions?): [ProviderTrace](https://docs.letta.com/api/typescript/resources/steps#(resource)%20steps%20%3E%20(model)%20provider_trace%20%3E%20(schema))
 { request\_json, response\_json, id, 15 more } | null

get/v1/steps/{step\_id}/trace

#### StepsFeedback

##### [Modify Feedback For Step](https://docs.letta.com/api/typescript/resources/steps/subresources/feedback/methods/create)

client.steps.feedback.create(stringstepID, FeedbackCreateParams { feedback, tags } body, RequestOptionsoptions?): [Step](https://docs.letta.com/api/typescript/resources/steps#(resource)%20steps%20%3E%20(model)%20step%20%3E%20(schema))
 { id, agent\_id, cache\_write\_tokens, 27 more }

patch/v1/steps/{step\_id}/feedback

#### StepsMessages

##### [List Messages For Step](https://docs.letta.com/api/typescript/resources/steps/subresources/messages/methods/list)

client.steps.messages.list(stringstepID, MessageListParams { after, before, limit, 2 more } query?, RequestOptionsoptions?): ArrayPage<[MessageListResponse](https://docs.letta.com/api/typescript/resources/steps#(resource)%20steps.messages%20%3E%20(model)%20message_list_response%20%3E%20(schema))
\>

get/v1/steps/{step\_id}/messages

---

# Conversations | Letta Docs

[Skip to content](https://docs.letta.com/api/typescript/resources/conversations#_top)

[API Reference](https://docs.letta.com/api/typescript)

Copy Markdown

Open in **Claude**

Open in **ChatGPT**

Open in **Cursor**

* * *

**Copy Markdown**

**View as Markdown**

Conversations
=============

##### [Create Conversation](https://docs.letta.com/api/typescript/resources/conversations/methods/create)

client.conversations.create(ConversationCreateParams { agent\_id, context\_window\_limit, hidden, 4 more } params, RequestOptionsoptions?): [Conversation](https://docs.letta.com/api/typescript/resources/conversations#(resource)%20conversations%20%3E%20(model)%20conversation%20%3E%20(schema))
 { id, agent\_id, archived, 12 more }

post/v1/conversations/

##### [List Conversations](https://docs.letta.com/api/typescript/resources/conversations/methods/list)

client.conversations.list(ConversationListParams { after, agent\_id, archive\_status, 4 more } query?, RequestOptionsoptions?): [ConversationListResponse](https://docs.letta.com/api/typescript/resources/conversations#(resource)%20conversations%20%3E%20(model)%20conversation_list_response%20%3E%20(schema))
 { id, agent\_id, archived, 12 more }

get/v1/conversations/

##### [Retrieve Conversation](https://docs.letta.com/api/typescript/resources/conversations/methods/retrieve)

client.conversations.retrieve(stringconversationID, RequestOptionsoptions?): [Conversation](https://docs.letta.com/api/typescript/resources/conversations#(resource)%20conversations%20%3E%20(model)%20conversation%20%3E%20(schema))
 { id, agent\_id, archived, 12 more }

get/v1/conversations/{conversation\_id}

##### [Update Conversation](https://docs.letta.com/api/typescript/resources/conversations/methods/update)

client.conversations.update(stringconversationID, ConversationUpdateParams { archived, context\_window\_limit, last\_message\_at, 3 more } body, RequestOptionsoptions?): [Conversation](https://docs.letta.com/api/typescript/resources/conversations#(resource)%20conversations%20%3E%20(model)%20conversation%20%3E%20(schema))
 { id, agent\_id, archived, 12 more }

patch/v1/conversations/{conversation\_id}

##### [Delete Conversation](https://docs.letta.com/api/typescript/resources/conversations/methods/delete)

client.conversations.delete(stringconversationID, RequestOptionsoptions?): [ConversationDeleteResponse](https://docs.letta.com/api/typescript/resources/conversations#(resource)%20conversations%20%3E%20(model)%20conversation_delete_response%20%3E%20(schema))

delete/v1/conversations/{conversation\_id}

##### [Cancel Conversation](https://docs.letta.com/api/typescript/resources/conversations/methods/cancel)

client.conversations.cancel(stringconversationID, ConversationCancelParams { agent\_id } params?, RequestOptionsoptions?): [ConversationCancelResponse](https://docs.letta.com/api/typescript/resources/conversations#(resource)%20conversations%20%3E%20(model)%20conversation_cancel_response%20%3E%20(schema))

post/v1/conversations/{conversation\_id}/cancel

##### [Recompile Conversation](https://docs.letta.com/api/typescript/resources/conversations/methods/recompile)

client.conversations.recompile(stringconversationID, ConversationRecompileParams { dry\_run, agent\_id, compaction\_settings } params?, RequestOptionsoptions?): [ConversationRecompileResponse](https://docs.letta.com/api/typescript/resources/conversations#(resource)%20conversations%20%3E%20(model)%20conversation_recompile_response%20%3E%20(schema))

post/v1/conversations/{conversation\_id}/recompile

##### [Fork Conversation](https://docs.letta.com/api/typescript/resources/conversations/methods/fork)

client.conversations.fork(stringconversationID, ConversationForkParams { agent\_id, hidden } params?, RequestOptionsoptions?): [Conversation](https://docs.letta.com/api/typescript/resources/conversations#(resource)%20conversations%20%3E%20(model)%20conversation%20%3E%20(schema))
 { id, agent\_id, archived, 12 more }

post/v1/conversations/{conversation\_id}/fork

##### ModelsExpand Collapse

Conversation { id, agent\_id, archived, 12 more }

Represents a conversation on an agent for concurrent messaging.

id: string

The unique identifier of the conversation.

agent\_id: string

The ID of the agent this conversation belongs to.

archived?: boolean

Whether the conversation is archived.

archived\_at?: string | null

Timestamp of when the conversation was archived.

formatdate-time

context\_window\_limit?: number | null

The context window limit for this conversation (overrides agent's context window).

created\_at?: string | null

The timestamp when the object was created.

formatdate-time

created\_by\_id?: string | null

The id of the user that made this object.

in\_context\_message\_ids?: Array<string\> | null

The IDs of in-context messages for the conversation. Null means this field was not retrieved/hydrated for this response.

isolated\_block\_ids?: Array<string\>

IDs of blocks that are isolated (specific to this conversation, overriding agent defaults).

last\_message\_at?: string | null

Timestamp of the most recent message request sent to this conversation.

formatdate-time

last\_updated\_by\_id?: string | null

The id of the user that made this object.

model?: string | null

The model handle for this conversation (overrides agent's model). Format: provider/model-name.

model\_settings?: [OpenAIModelSettings](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20openai_model_settings%20%3E%20(schema))
 { max\_output\_tokens, parallel\_tool\_calls, provider\_type, 4 more } | SgLangModelSettings { max\_output\_tokens, parallel\_tool\_calls, provider\_type, 5 more } | [AnthropicModelSettings](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20anthropic_model_settings%20%3E%20(schema))
 { effort, max\_output\_tokens, parallel\_tool\_calls, 6 more } | 12 more | null

The model settings for this conversation (overrides agent's model settings).

Accepts one of the following:

OpenAIModelSettings { max\_output\_tokens, parallel\_tool\_calls, provider\_type, 4 more }

max\_output\_tokens?: number

The maximum number of tokens the model can generate.

parallel\_tool\_calls?: boolean

Whether to enable parallel tool calling.

provider\_type?: "openai"

The type of the provider.

reasoning?: Reasoning { reasoning\_effort }

The reasoning configuration for the model.

reasoning\_effort?: "none" | "minimal" | "low" | 3 more

The reasoning effort to use when generating text reasoning models

Accepts one of the following:

"none"

"minimal"

"low"

"medium"

"high"

"xhigh"

response\_format?: [TextResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20text_response_format%20%3E%20(schema))
 { type } | [JsonSchemaResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_schema_response_format%20%3E%20(schema))
 { json\_schema, type } | [JsonObjectResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_object_response_format%20%3E%20(schema))
 { type } | null

The response format for the model.

Accepts one of the following:

TextResponseFormat { type }

Response format for plain text responses.

type?: "text"

The type of the response format.

JsonSchemaResponseFormat { json\_schema, type }

Response format for JSON schema-based responses.

json\_schema: Record<string, unknown\>

The JSON schema of the response.

type?: "json\_schema"

The type of the response format.

JsonObjectResponseFormat { type }

Response format for JSON object responses.

type?: "json\_object"

The type of the response format.

strict?: boolean

Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas.

temperature?: number

The temperature of the model.

SgLangModelSettings { max\_output\_tokens, parallel\_tool\_calls, provider\_type, 5 more }

SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing).

max\_output\_tokens?: number

The maximum number of tokens the model can generate.

parallel\_tool\_calls?: boolean

Whether to enable parallel tool calling.

provider\_type?: "sglang"

The type of the provider.

reasoning?: Reasoning { reasoning\_effort }

The reasoning configuration for the model.

reasoning\_effort?: "none" | "minimal" | "low" | 3 more

The reasoning effort to use when generating text reasoning models

Accepts one of the following:

"none"

"minimal"

"low"

"medium"

"high"

"xhigh"

response\_format?: [TextResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20text_response_format%20%3E%20(schema))
 { type } | [JsonSchemaResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_schema_response_format%20%3E%20(schema))
 { json\_schema, type } | [JsonObjectResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_object_response_format%20%3E%20(schema))
 { type } | null

The response format for the model.

Accepts one of the following:

TextResponseFormat { type }

Response format for plain text responses.

type?: "text"

The type of the response format.

JsonSchemaResponseFormat { json\_schema, type }

Response format for JSON schema-based responses.

json\_schema: Record<string, unknown\>

The JSON schema of the response.

type?: "json\_schema"

The type of the response format.

JsonObjectResponseFormat { type }

Response format for JSON object responses.

type?: "json\_object"

The type of the response format.

strict?: boolean

Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas.

temperature?: number

The temperature of the model.

tool\_call\_parser?: string | null

SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes').

AnthropicModelSettings { effort, max\_output\_tokens, parallel\_tool\_calls, 6 more }

effort?: "low" | "medium" | "high" | 2 more | null

Effort level for supported Anthropic models (controls token spending). 'xhigh' and 'max' are available on Opus 4.6+. Not setting this gives similar performance to 'high'.

Accepts one of the following:

"low"

"medium"

"high"

"xhigh"

"max"

max\_output\_tokens?: number

The maximum number of tokens the model can generate.

parallel\_tool\_calls?: boolean

Whether to enable parallel tool calling.

provider\_type?: "anthropic"

The type of the provider.

response\_format?: [TextResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20text_response_format%20%3E%20(schema))
 { type } | [JsonSchemaResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_schema_response_format%20%3E%20(schema))
 { json\_schema, type } | [JsonObjectResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_object_response_format%20%3E%20(schema))
 { type } | null

The response format for the model.

Accepts one of the following:

TextResponseFormat { type }

Response format for plain text responses.

type?: "text"

The type of the response format.

JsonSchemaResponseFormat { json\_schema, type }

Response format for JSON schema-based responses.

json\_schema: Record<string, unknown\>

The JSON schema of the response.

type?: "json\_schema"

The type of the response format.

JsonObjectResponseFormat { type }

Response format for JSON object responses.

type?: "json\_object"

The type of the response format.

strict?: boolean

Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas.

temperature?: number

The temperature of the model.

thinking?: Thinking { budget\_tokens, type }

The thinking configuration for the model.

budget\_tokens?: number

The maximum number of tokens the model can use for extended thinking.

type?: "enabled" | "disabled"

The type of thinking to use.

Accepts one of the following:

"enabled"

"disabled"

verbosity?: "low" | "medium" | "high" | null

Soft control for how verbose model output should be, used for GPT-5 models.

Accepts one of the following:

"low"

"medium"

"high"

GoogleAIModelSettings { max\_output\_tokens, parallel\_tool\_calls, provider\_type, 3 more }

max\_output\_tokens?: number

The maximum number of tokens the model can generate.

parallel\_tool\_calls?: boolean

Whether to enable parallel tool calling.

provider\_type?: "google\_ai"

The type of the provider.

response\_schema?: [TextResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20text_response_format%20%3E%20(schema))
 { type } | [JsonSchemaResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_schema_response_format%20%3E%20(schema))
 { json\_schema, type } | [JsonObjectResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_object_response_format%20%3E%20(schema))
 { type } | null

The response schema for the model.

Accepts one of the following:

TextResponseFormat { type }

Response format for plain text responses.

type?: "text"

The type of the response format.

JsonSchemaResponseFormat { json\_schema, type }

Response format for JSON schema-based responses.

json\_schema: Record<string, unknown\>

The JSON schema of the response.

type?: "json\_schema"

The type of the response format.

JsonObjectResponseFormat { type }

Response format for JSON object responses.

type?: "json\_object"

The type of the response format.

temperature?: number

The temperature of the model.

thinking\_config?: ThinkingConfig { include\_thoughts, thinking\_budget }

The thinking configuration for the model.

include\_thoughts?: boolean

Whether to include thoughts in the model's response.

thinking\_budget?: number

The thinking budget for the model.

GoogleVertexModelSettings { max\_output\_tokens, parallel\_tool\_calls, provider\_type, 3 more }

max\_output\_tokens?: number

The maximum number of tokens the model can generate.

parallel\_tool\_calls?: boolean

Whether to enable parallel tool calling.

provider\_type?: "google\_vertex"

The type of the provider.

response\_schema?: [TextResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20text_response_format%20%3E%20(schema))
 { type } | [JsonSchemaResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_schema_response_format%20%3E%20(schema))
 { json\_schema, type } | [JsonObjectResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_object_response_format%20%3E%20(schema))
 { type } | null

The response schema for the model.

Accepts one of the following:

TextResponseFormat { type }

Response format for plain text responses.

type?: "text"

The type of the response format.

JsonSchemaResponseFormat { json\_schema, type }

Response format for JSON schema-based responses.

json\_schema: Record<string, unknown\>

The JSON schema of the response.

type?: "json\_schema"

The type of the response format.

JsonObjectResponseFormat { type }

Response format for JSON object responses.

type?: "json\_object"

The type of the response format.

temperature?: number

The temperature of the model.

thinking\_config?: ThinkingConfig { include\_thoughts, thinking\_budget }

The thinking configuration for the model.

include\_thoughts?: boolean

Whether to include thoughts in the model's response.

thinking\_budget?: number

The thinking budget for the model.

AzureModelSettings { max\_output\_tokens, parallel\_tool\_calls, provider\_type, 2 more }

Azure OpenAI model configuration (OpenAI-compatible).

max\_output\_tokens?: number

The maximum number of tokens the model can generate.

parallel\_tool\_calls?: boolean

Whether to enable parallel tool calling.

provider\_type?: "azure"

The type of the provider.

response\_format?: [TextResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20text_response_format%20%3E%20(schema))
 { type } | [JsonSchemaResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_schema_response_format%20%3E%20(schema))
 { json\_schema, type } | [JsonObjectResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_object_response_format%20%3E%20(schema))
 { type } | null

The response format for the model.

Accepts one of the following:

TextResponseFormat { type }

Response format for plain text responses.

type?: "text"

The type of the response format.

JsonSchemaResponseFormat { json\_schema, type }

Response format for JSON schema-based responses.

json\_schema: Record<string, unknown\>

The JSON schema of the response.

type?: "json\_schema"

The type of the response format.

JsonObjectResponseFormat { type }

Response format for JSON object responses.

type?: "json\_object"

The type of the response format.

temperature?: number

The temperature of the model.

XaiModelSettings { max\_output\_tokens, parallel\_tool\_calls, provider\_type, 2 more }

xAI model configuration (OpenAI-compatible).

max\_output\_tokens?: number

The maximum number of tokens the model can generate.

parallel\_tool\_calls?: boolean

Whether to enable parallel tool calling.

provider\_type?: "xai"

The type of the provider.

response\_format?: [TextResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20text_response_format%20%3E%20(schema))
 { type } | [JsonSchemaResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_schema_response_format%20%3E%20(schema))
 { json\_schema, type } | [JsonObjectResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_object_response_format%20%3E%20(schema))
 { type } | null

The response format for the model.

Accepts one of the following:

TextResponseFormat { type }

Response format for plain text responses.

type?: "text"

The type of the response format.

JsonSchemaResponseFormat { json\_schema, type }

Response format for JSON schema-based responses.

json\_schema: Record<string, unknown\>

The JSON schema of the response.

type?: "json\_schema"

The type of the response format.

JsonObjectResponseFormat { type }

Response format for JSON object responses.

type?: "json\_object"

The type of the response format.

temperature?: number

The temperature of the model.

ZaiModelSettings { max\_output\_tokens, parallel\_tool\_calls, provider\_type, 3 more }

Z.ai (ZhipuAI) model configuration (OpenAI-compatible).

max\_output\_tokens?: number

The maximum number of tokens the model can generate.

parallel\_tool\_calls?: boolean

Whether to enable parallel tool calling.

provider\_type?: "zai"

The type of the provider.

response\_format?: [TextResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20text_response_format%20%3E%20(schema))
 { type } | [JsonSchemaResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_schema_response_format%20%3E%20(schema))
 { json\_schema, type } | [JsonObjectResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_object_response_format%20%3E%20(schema))
 { type } | null

The response format for the model.

Accepts one of the following:

TextResponseFormat { type }

Response format for plain text responses.

type?: "text"

The type of the response format.

JsonSchemaResponseFormat { json\_schema, type }

Response format for JSON schema-based responses.

json\_schema: Record<string, unknown\>

The JSON schema of the response.

type?: "json\_schema"

The type of the response format.

JsonObjectResponseFormat { type }

Response format for JSON object responses.

type?: "json\_object"

The type of the response format.

temperature?: number

The temperature of the model.

thinking?: Thinking { clear\_thinking, type }

The thinking configuration for GLM-4.5+ models.

clear\_thinking?: boolean

If False, preserved thinking is used (recommended for agents).

type?: "enabled" | "disabled"

Whether thinking is enabled or disabled.

Accepts one of the following:

"enabled"

"disabled"

GroqModelSettings { max\_output\_tokens, parallel\_tool\_calls, provider\_type, 2 more }

Groq model configuration (OpenAI-compatible).

max\_output\_tokens?: number

The maximum number of tokens the model can generate.

parallel\_tool\_calls?: boolean

Whether to enable parallel tool calling.

provider\_type?: "groq"

The type of the provider.

response\_format?: [TextResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20text_response_format%20%3E%20(schema))
 { type } | [JsonSchemaResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_schema_response_format%20%3E%20(schema))
 { json\_schema, type } | [JsonObjectResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_object_response_format%20%3E%20(schema))
 { type } | null

The response format for the model.

Accepts one of the following:

TextResponseFormat { type }

Response format for plain text responses.

type?: "text"

The type of the response format.

JsonSchemaResponseFormat { json\_schema, type }

Response format for JSON schema-based responses.

json\_schema: Record<string, unknown\>

The JSON schema of the response.

type?: "json\_schema"

The type of the response format.

JsonObjectResponseFormat { type }

Response format for JSON object responses.

type?: "json\_object"

The type of the response format.

temperature?: number

The temperature of the model.

DeepseekModelSettings { max\_output\_tokens, parallel\_tool\_calls, provider\_type, 2 more }

Deepseek model configuration (OpenAI-compatible).

max\_output\_tokens?: number

The maximum number of tokens the model can generate.

parallel\_tool\_calls?: boolean

Whether to enable parallel tool calling.

provider\_type?: "deepseek"

The type of the provider.

response\_format?: [TextResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20text_response_format%20%3E%20(schema))
 { type } | [JsonSchemaResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_schema_response_format%20%3E%20(schema))
 { json\_schema, type } | [JsonObjectResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_object_response_format%20%3E%20(schema))
 { type } | null

The response format for the model.

Accepts one of the following:

TextResponseFormat { type }

Response format for plain text responses.

type?: "text"

The type of the response format.

JsonSchemaResponseFormat { json\_schema, type }

Response format for JSON schema-based responses.

json\_schema: Record<string, unknown\>

The JSON schema of the response.

type?: "json\_schema"

The type of the response format.

JsonObjectResponseFormat { type }

Response format for JSON object responses.

type?: "json\_object"

The type of the response format.

temperature?: number

The temperature of the model.

TogetherModelSettings { max\_output\_tokens, parallel\_tool\_calls, provider\_type, 2 more }

Together AI model configuration (OpenAI-compatible).

max\_output\_tokens?: number

The maximum number of tokens the model can generate.

parallel\_tool\_calls?: boolean

Whether to enable parallel tool calling.

provider\_type?: "together"

The type of the provider.

response\_format?: [TextResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20text_response_format%20%3E%20(schema))
 { type } | [JsonSchemaResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_schema_response_format%20%3E%20(schema))
 { json\_schema, type } | [JsonObjectResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_object_response_format%20%3E%20(schema))
 { type } | null

The response format for the model.

Accepts one of the following:

TextResponseFormat { type }

Response format for plain text responses.

type?: "text"

The type of the response format.

JsonSchemaResponseFormat { json\_schema, type }

Response format for JSON schema-based responses.

json\_schema: Record<string, unknown\>

The JSON schema of the response.

type?: "json\_schema"

The type of the response format.

JsonObjectResponseFormat { type }

Response format for JSON object responses.

type?: "json\_object"

The type of the response format.

temperature?: number

The temperature of the model.

BedrockModelSettings { max\_output\_tokens, parallel\_tool\_calls, provider\_type, 2 more }

AWS Bedrock model configuration.

max\_output\_tokens?: number

The maximum number of tokens the model can generate.

parallel\_tool\_calls?: boolean

Whether to enable parallel tool calling.

provider\_type?: "bedrock"

The type of the provider.

response\_format?: [TextResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20text_response_format%20%3E%20(schema))
 { type } | [JsonSchemaResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_schema_response_format%20%3E%20(schema))
 { json\_schema, type } | [JsonObjectResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_object_response_format%20%3E%20(schema))
 { type } | null

The response format for the model.

Accepts one of the following:

TextResponseFormat { type }

Response format for plain text responses.

type?: "text"

The type of the response format.

JsonSchemaResponseFormat { json\_schema, type }

Response format for JSON schema-based responses.

json\_schema: Record<string, unknown\>

The JSON schema of the response.

type?: "json\_schema"

The type of the response format.

JsonObjectResponseFormat { type }

Response format for JSON object responses.

type?: "json\_object"

The type of the response format.

temperature?: number

The temperature of the model.

BasetenModelSettings { max\_output\_tokens, parallel\_tool\_calls, provider\_type, temperature }

Baseten model configuration (OpenAI-compatible).

max\_output\_tokens?: number

The maximum number of tokens the model can generate.

parallel\_tool\_calls?: boolean

Whether to enable parallel tool calling.

provider\_type?: "baseten"

The type of the provider.

temperature?: number

The temperature of the model.

OpenRouterModelSettings { max\_output\_tokens, parallel\_tool\_calls, provider\_type, 2 more }

OpenRouter model configuration (OpenAI-compatible).

max\_output\_tokens?: number

The maximum number of tokens the model can generate.

parallel\_tool\_calls?: boolean

Whether to enable parallel tool calling.

provider\_type?: "openrouter"

The type of the provider.

response\_format?: [TextResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20text_response_format%20%3E%20(schema))
 { type } | [JsonSchemaResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_schema_response_format%20%3E%20(schema))
 { json\_schema, type } | [JsonObjectResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_object_response_format%20%3E%20(schema))
 { type } | null

The response format for the model.

Accepts one of the following:

TextResponseFormat { type }

Response format for plain text responses.

type?: "text"

The type of the response format.

JsonSchemaResponseFormat { json\_schema, type }

Response format for JSON schema-based responses.

json\_schema: Record<string, unknown\>

The JSON schema of the response.

type?: "json\_schema"

The type of the response format.

JsonObjectResponseFormat { type }

Response format for JSON object responses.

type?: "json\_object"

The type of the response format.

temperature?: number

The temperature of the model.

ChatGptoAuthModelSettings { max\_output\_tokens, parallel\_tool\_calls, provider\_type, 2 more }

ChatGPT OAuth model configuration (uses ChatGPT backend API).

max\_output\_tokens?: number

The maximum number of tokens the model can generate.

parallel\_tool\_calls?: boolean

Whether to enable parallel tool calling.

provider\_type?: "chatgpt\_oauth"

The type of the provider.

reasoning?: Reasoning { reasoning\_effort }

The reasoning configuration for the model.

reasoning\_effort?: "none" | "low" | "medium" | 2 more

The reasoning effort level for GPT-5.x and o-series models.

Accepts one of the following:

"none"

"low"

"medium"

"high"

"xhigh"

temperature?: number

The temperature of the model.

summary?: string | null

A summary of the conversation.

updated\_at?: string | null

The timestamp when the object was last updated.

formatdate-time

CreateConversation { context\_window\_limit, hidden, isolated\_block\_labels, 3 more }

Request model for creating a new conversation.

context\_window\_limit?: number | null

The context window limit for this conversation (overrides agent's context window).

hidden?: boolean

Whether the new conversation should be hidden from listings.

isolated\_block\_labels?: Array<string\> | null

List of block labels that should be isolated (conversation-specific) rather than shared across conversations. New blocks will be created as copies of the agent's blocks with these labels.

model?: string | null

The model handle for this conversation (overrides agent's model). Format: provider/model-name.

model\_settings?: [OpenAIModelSettings](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20openai_model_settings%20%3E%20(schema))
 { max\_output\_tokens, parallel\_tool\_calls, provider\_type, 4 more } | SgLangModelSettings { max\_output\_tokens, parallel\_tool\_calls, provider\_type, 5 more } | [AnthropicModelSettings](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20anthropic_model_settings%20%3E%20(schema))
 { effort, max\_output\_tokens, parallel\_tool\_calls, 6 more } | 12 more | null

The model settings for this conversation (overrides agent's model settings).

Accepts one of the following:

OpenAIModelSettings { max\_output\_tokens, parallel\_tool\_calls, provider\_type, 4 more }

max\_output\_tokens?: number

The maximum number of tokens the model can generate.

parallel\_tool\_calls?: boolean

Whether to enable parallel tool calling.

provider\_type?: "openai"

The type of the provider.

reasoning?: Reasoning { reasoning\_effort }

The reasoning configuration for the model.

reasoning\_effort?: "none" | "minimal" | "low" | 3 more

The reasoning effort to use when generating text reasoning models

Accepts one of the following:

"none"

"minimal"

"low"

"medium"

"high"

"xhigh"

response\_format?: [TextResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20text_response_format%20%3E%20(schema))
 { type } | [JsonSchemaResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_schema_response_format%20%3E%20(schema))
 { json\_schema, type } | [JsonObjectResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_object_response_format%20%3E%20(schema))
 { type } | null

The response format for the model.

Accepts one of the following:

TextResponseFormat { type }

Response format for plain text responses.

type?: "text"

The type of the response format.

JsonSchemaResponseFormat { json\_schema, type }

Response format for JSON schema-based responses.

json\_schema: Record<string, unknown\>

The JSON schema of the response.

type?: "json\_schema"

The type of the response format.

JsonObjectResponseFormat { type }

Response format for JSON object responses.

type?: "json\_object"

The type of the response format.

strict?: boolean

Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas.

temperature?: number

The temperature of the model.

SgLangModelSettings { max\_output\_tokens, parallel\_tool\_calls, provider\_type, 5 more }

SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing).

max\_output\_tokens?: number

The maximum number of tokens the model can generate.

parallel\_tool\_calls?: boolean

Whether to enable parallel tool calling.

provider\_type?: "sglang"

The type of the provider.

reasoning?: Reasoning { reasoning\_effort }

The reasoning configuration for the model.

reasoning\_effort?: "none" | "minimal" | "low" | 3 more

The reasoning effort to use when generating text reasoning models

Accepts one of the following:

"none"

"minimal"

"low"

"medium"

"high"

"xhigh"

response\_format?: [TextResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20text_response_format%20%3E%20(schema))
 { type } | [JsonSchemaResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_schema_response_format%20%3E%20(schema))
 { json\_schema, type } | [JsonObjectResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_object_response_format%20%3E%20(schema))
 { type } | null

The response format for the model.

Accepts one of the following:

TextResponseFormat { type }

Response format for plain text responses.

type?: "text"

The type of the response format.

JsonSchemaResponseFormat { json\_schema, type }

Response format for JSON schema-based responses.

json\_schema: Record<string, unknown\>

The JSON schema of the response.

type?: "json\_schema"

The type of the response format.

JsonObjectResponseFormat { type }

Response format for JSON object responses.

type?: "json\_object"

The type of the response format.

strict?: boolean

Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas.

temperature?: number

The temperature of the model.

tool\_call\_parser?: string | null

SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes').

AnthropicModelSettings { effort, max\_output\_tokens, parallel\_tool\_calls, 6 more }

effort?: "low" | "medium" | "high" | 2 more | null

Effort level for supported Anthropic models (controls token spending). 'xhigh' and 'max' are available on Opus 4.6+. Not setting this gives similar performance to 'high'.

Accepts one of the following:

"low"

"medium"

"high"

"xhigh"

"max"

max\_output\_tokens?: number

The maximum number of tokens the model can generate.

parallel\_tool\_calls?: boolean

Whether to enable parallel tool calling.

provider\_type?: "anthropic"

The type of the provider.

response\_format?: [TextResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20text_response_format%20%3E%20(schema))
 { type } | [JsonSchemaResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_schema_response_format%20%3E%20(schema))
 { json\_schema, type } | [JsonObjectResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_object_response_format%20%3E%20(schema))
 { type } | null

The response format for the model.

Accepts one of the following:

TextResponseFormat { type }

Response format for plain text responses.

type?: "text"

The type of the response format.

JsonSchemaResponseFormat { json\_schema, type }

Response format for JSON schema-based responses.

json\_schema: Record<string, unknown\>

The JSON schema of the response.

type?: "json\_schema"

The type of the response format.

JsonObjectResponseFormat { type }

Response format for JSON object responses.

type?: "json\_object"

The type of the response format.

strict?: boolean

Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas.

temperature?: number

The temperature of the model.

thinking?: Thinking { budget\_tokens, type }

The thinking configuration for the model.

budget\_tokens?: number

The maximum number of tokens the model can use for extended thinking.

type?: "enabled" | "disabled"

The type of thinking to use.

Accepts one of the following:

"enabled"

"disabled"

verbosity?: "low" | "medium" | "high" | null

Soft control for how verbose model output should be, used for GPT-5 models.

Accepts one of the following:

"low"

"medium"

"high"

GoogleAIModelSettings { max\_output\_tokens, parallel\_tool\_calls, provider\_type, 3 more }

max\_output\_tokens?: number

The maximum number of tokens the model can generate.

parallel\_tool\_calls?: boolean

Whether to enable parallel tool calling.

provider\_type?: "google\_ai"

The type of the provider.

response\_schema?: [TextResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20text_response_format%20%3E%20(schema))
 { type } | [JsonSchemaResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_schema_response_format%20%3E%20(schema))
 { json\_schema, type } | [JsonObjectResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_object_response_format%20%3E%20(schema))
 { type } | null

The response schema for the model.

Accepts one of the following:

TextResponseFormat { type }

Response format for plain text responses.

type?: "text"

The type of the response format.

JsonSchemaResponseFormat { json\_schema, type }

Response format for JSON schema-based responses.

json\_schema: Record<string, unknown\>

The JSON schema of the response.

type?: "json\_schema"

The type of the response format.

JsonObjectResponseFormat { type }

Response format for JSON object responses.

type?: "json\_object"

The type of the response format.

temperature?: number

The temperature of the model.

thinking\_config?: ThinkingConfig { include\_thoughts, thinking\_budget }

The thinking configuration for the model.

include\_thoughts?: boolean

Whether to include thoughts in the model's response.

thinking\_budget?: number

The thinking budget for the model.

GoogleVertexModelSettings { max\_output\_tokens, parallel\_tool\_calls, provider\_type, 3 more }

max\_output\_tokens?: number

The maximum number of tokens the model can generate.

parallel\_tool\_calls?: boolean

Whether to enable parallel tool calling.

provider\_type?: "google\_vertex"

The type of the provider.

response\_schema?: [TextResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20text_response_format%20%3E%20(schema))
 { type } | [JsonSchemaResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_schema_response_format%20%3E%20(schema))
 { json\_schema, type } | [JsonObjectResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_object_response_format%20%3E%20(schema))
 { type } | null

The response schema for the model.

Accepts one of the following:

TextResponseFormat { type }

Response format for plain text responses.

type?: "text"

The type of the response format.

JsonSchemaResponseFormat { json\_schema, type }

Response format for JSON schema-based responses.

json\_schema: Record<string, unknown\>

The JSON schema of the response.

type?: "json\_schema"

The type of the response format.

JsonObjectResponseFormat { type }

Response format for JSON object responses.

type?: "json\_object"

The type of the response format.

temperature?: number

The temperature of the model.

thinking\_config?: ThinkingConfig { include\_thoughts, thinking\_budget }

The thinking configuration for the model.

include\_thoughts?: boolean

Whether to include thoughts in the model's response.

thinking\_budget?: number

The thinking budget for the model.

AzureModelSettings { max\_output\_tokens, parallel\_tool\_calls, provider\_type, 2 more }

Azure OpenAI model configuration (OpenAI-compatible).

max\_output\_tokens?: number

The maximum number of tokens the model can generate.

parallel\_tool\_calls?: boolean

Whether to enable parallel tool calling.

provider\_type?: "azure"

The type of the provider.

response\_format?: [TextResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20text_response_format%20%3E%20(schema))
 { type } | [JsonSchemaResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_schema_response_format%20%3E%20(schema))
 { json\_schema, type } | [JsonObjectResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_object_response_format%20%3E%20(schema))
 { type } | null

The response format for the model.

Accepts one of the following:

TextResponseFormat { type }

Response format for plain text responses.

type?: "text"

The type of the response format.

JsonSchemaResponseFormat { json\_schema, type }

Response format for JSON schema-based responses.

json\_schema: Record<string, unknown\>

The JSON schema of the response.

type?: "json\_schema"

The type of the response format.

JsonObjectResponseFormat { type }

Response format for JSON object responses.

type?: "json\_object"

The type of the response format.

temperature?: number

The temperature of the model.

XaiModelSettings { max\_output\_tokens, parallel\_tool\_calls, provider\_type, 2 more }

xAI model configuration (OpenAI-compatible).

max\_output\_tokens?: number

The maximum number of tokens the model can generate.

parallel\_tool\_calls?: boolean

Whether to enable parallel tool calling.

provider\_type?: "xai"

The type of the provider.

response\_format?: [TextResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20text_response_format%20%3E%20(schema))
 { type } | [JsonSchemaResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_schema_response_format%20%3E%20(schema))
 { json\_schema, type } | [JsonObjectResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_object_response_format%20%3E%20(schema))
 { type } | null

The response format for the model.

Accepts one of the following:

TextResponseFormat { type }

Response format for plain text responses.

type?: "text"

The type of the response format.

JsonSchemaResponseFormat { json\_schema, type }

Response format for JSON schema-based responses.

json\_schema: Record<string, unknown\>

The JSON schema of the response.

type?: "json\_schema"

The type of the response format.

JsonObjectResponseFormat { type }

Response format for JSON object responses.

type?: "json\_object"

The type of the response format.

temperature?: number

The temperature of the model.

ZaiModelSettings { max\_output\_tokens, parallel\_tool\_calls, provider\_type, 3 more }

Z.ai (ZhipuAI) model configuration (OpenAI-compatible).

max\_output\_tokens?: number

The maximum number of tokens the model can generate.

parallel\_tool\_calls?: boolean

Whether to enable parallel tool calling.

provider\_type?: "zai"

The type of the provider.

response\_format?: [TextResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20text_response_format%20%3E%20(schema))
 { type } | [JsonSchemaResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_schema_response_format%20%3E%20(schema))
 { json\_schema, type } | [JsonObjectResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_object_response_format%20%3E%20(schema))
 { type } | null

The response format for the model.

Accepts one of the following:

TextResponseFormat { type }

Response format for plain text responses.

type?: "text"

The type of the response format.

JsonSchemaResponseFormat { json\_schema, type }

Response format for JSON schema-based responses.

json\_schema: Record<string, unknown\>

The JSON schema of the response.

type?: "json\_schema"

The type of the response format.

JsonObjectResponseFormat { type }

Response format for JSON object responses.

type?: "json\_object"

The type of the response format.

temperature?: number

The temperature of the model.

thinking?: Thinking { clear\_thinking, type }

The thinking configuration for GLM-4.5+ models.

clear\_thinking?: boolean

If False, preserved thinking is used (recommended for agents).

type?: "enabled" | "disabled"

Whether thinking is enabled or disabled.

Accepts one of the following:

"enabled"

"disabled"

GroqModelSettings { max\_output\_tokens, parallel\_tool\_calls, provider\_type, 2 more }

Groq model configuration (OpenAI-compatible).

max\_output\_tokens?: number

The maximum number of tokens the model can generate.

parallel\_tool\_calls?: boolean

Whether to enable parallel tool calling.

provider\_type?: "groq"

The type of the provider.

response\_format?: [TextResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20text_response_format%20%3E%20(schema))
 { type } | [JsonSchemaResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_schema_response_format%20%3E%20(schema))
 { json\_schema, type } | [JsonObjectResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_object_response_format%20%3E%20(schema))
 { type } | null

The response format for the model.

Accepts one of the following:

TextResponseFormat { type }

Response format for plain text responses.

type?: "text"

The type of the response format.

JsonSchemaResponseFormat { json\_schema, type }

Response format for JSON schema-based responses.

json\_schema: Record<string, unknown\>

The JSON schema of the response.

type?: "json\_schema"

The type of the response format.

JsonObjectResponseFormat { type }

Response format for JSON object responses.

type?: "json\_object"

The type of the response format.

temperature?: number

The temperature of the model.

DeepseekModelSettings { max\_output\_tokens, parallel\_tool\_calls, provider\_type, 2 more }

Deepseek model configuration (OpenAI-compatible).

max\_output\_tokens?: number

The maximum number of tokens the model can generate.

parallel\_tool\_calls?: boolean

Whether to enable parallel tool calling.

provider\_type?: "deepseek"

The type of the provider.

response\_format?: [TextResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20text_response_format%20%3E%20(schema))
 { type } | [JsonSchemaResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_schema_response_format%20%3E%20(schema))
 { json\_schema, type } | [JsonObjectResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_object_response_format%20%3E%20(schema))
 { type } | null

The response format for the model.

Accepts one of the following:

TextResponseFormat { type }

Response format for plain text responses.

type?: "text"

The type of the response format.

JsonSchemaResponseFormat { json\_schema, type }

Response format for JSON schema-based responses.

json\_schema: Record<string, unknown\>

The JSON schema of the response.

type?: "json\_schema"

The type of the response format.

JsonObjectResponseFormat { type }

Response format for JSON object responses.

type?: "json\_object"

The type of the response format.

temperature?: number

The temperature of the model.

TogetherModelSettings { max\_output\_tokens, parallel\_tool\_calls, provider\_type, 2 more }

Together AI model configuration (OpenAI-compatible).

max\_output\_tokens?: number

The maximum number of tokens the model can generate.

parallel\_tool\_calls?: boolean

Whether to enable parallel tool calling.

provider\_type?: "together"

The type of the provider.

response\_format?: [TextResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20text_response_format%20%3E%20(schema))
 { type } | [JsonSchemaResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_schema_response_format%20%3E%20(schema))
 { json\_schema, type } | [JsonObjectResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_object_response_format%20%3E%20(schema))
 { type } | null

The response format for the model.

Accepts one of the following:

TextResponseFormat { type }

Response format for plain text responses.

type?: "text"

The type of the response format.

JsonSchemaResponseFormat { json\_schema, type }

Response format for JSON schema-based responses.

json\_schema: Record<string, unknown\>

The JSON schema of the response.

type?: "json\_schema"

The type of the response format.

JsonObjectResponseFormat { type }

Response format for JSON object responses.

type?: "json\_object"

The type of the response format.

temperature?: number

The temperature of the model.

BedrockModelSettings { max\_output\_tokens, parallel\_tool\_calls, provider\_type, 2 more }

AWS Bedrock model configuration.

max\_output\_tokens?: number

The maximum number of tokens the model can generate.

parallel\_tool\_calls?: boolean

Whether to enable parallel tool calling.

provider\_type?: "bedrock"

The type of the provider.

response\_format?: [TextResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20text_response_format%20%3E%20(schema))
 { type } | [JsonSchemaResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_schema_response_format%20%3E%20(schema))
 { json\_schema, type } | [JsonObjectResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_object_response_format%20%3E%20(schema))
 { type } | null

The response format for the model.

Accepts one of the following:

TextResponseFormat { type }

Response format for plain text responses.

type?: "text"

The type of the response format.

JsonSchemaResponseFormat { json\_schema, type }

Response format for JSON schema-based responses.

json\_schema: Record<string, unknown\>

The JSON schema of the response.

type?: "json\_schema"

The type of the response format.

JsonObjectResponseFormat { type }

Response format for JSON object responses.

type?: "json\_object"

The type of the response format.

temperature?: number

The temperature of the model.

BasetenModelSettings { max\_output\_tokens, parallel\_tool\_calls, provider\_type, temperature }

Baseten model configuration (OpenAI-compatible).

max\_output\_tokens?: number

The maximum number of tokens the model can generate.

parallel\_tool\_calls?: boolean

Whether to enable parallel tool calling.

provider\_type?: "baseten"

The type of the provider.

temperature?: number

The temperature of the model.

OpenRouterModelSettings { max\_output\_tokens, parallel\_tool\_calls, provider\_type, 2 more }

OpenRouter model configuration (OpenAI-compatible).

max\_output\_tokens?: number

The maximum number of tokens the model can generate.

parallel\_tool\_calls?: boolean

Whether to enable parallel tool calling.

provider\_type?: "openrouter"

The type of the provider.

response\_format?: [TextResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20text_response_format%20%3E%20(schema))
 { type } | [JsonSchemaResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_schema_response_format%20%3E%20(schema))
 { json\_schema, type } | [JsonObjectResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_object_response_format%20%3E%20(schema))
 { type } | null

The response format for the model.

Accepts one of the following:

TextResponseFormat { type }

Response format for plain text responses.

type?: "text"

The type of the response format.

JsonSchemaResponseFormat { json\_schema, type }

Response format for JSON schema-based responses.

json\_schema: Record<string, unknown\>

The JSON schema of the response.

type?: "json\_schema"

The type of the response format.

JsonObjectResponseFormat { type }

Response format for JSON object responses.

type?: "json\_object"

The type of the response format.

temperature?: number

The temperature of the model.

ChatGptoAuthModelSettings { max\_output\_tokens, parallel\_tool\_calls, provider\_type, 2 more }

ChatGPT OAuth model configuration (uses ChatGPT backend API).

max\_output\_tokens?: number

The maximum number of tokens the model can generate.

parallel\_tool\_calls?: boolean

Whether to enable parallel tool calling.

provider\_type?: "chatgpt\_oauth"

The type of the provider.

reasoning?: Reasoning { reasoning\_effort }

The reasoning configuration for the model.

reasoning\_effort?: "none" | "low" | "medium" | 2 more

The reasoning effort level for GPT-5.x and o-series models.

Accepts one of the following:

"none"

"low"

"medium"

"high"

"xhigh"

temperature?: number

The temperature of the model.

summary?: string | null

A summary of the conversation.

UpdateConversation { archived, context\_window\_limit, last\_message\_at, 3 more }

Request model for updating a conversation.

archived?: boolean | null

Whether the conversation is archived.

context\_window\_limit?: number | null

The context window limit for this conversation (overrides agent's context window).

last\_message\_at?: string | null

Timestamp of the most recent message request sent to this conversation.

formatdate-time

model?: string | null

The model handle for this conversation (overrides agent's model). Format: provider/model-name.

model\_settings?: [OpenAIModelSettings](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20openai_model_settings%20%3E%20(schema))
 { max\_output\_tokens, parallel\_tool\_calls, provider\_type, 4 more } | SgLangModelSettings { max\_output\_tokens, parallel\_tool\_calls, provider\_type, 5 more } | [AnthropicModelSettings](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20anthropic_model_settings%20%3E%20(schema))
 { effort, max\_output\_tokens, parallel\_tool\_calls, 6 more } | 12 more | null

The model settings for this conversation (overrides agent's model settings).

Accepts one of the following:

OpenAIModelSettings { max\_output\_tokens, parallel\_tool\_calls, provider\_type, 4 more }

max\_output\_tokens?: number

The maximum number of tokens the model can generate.

parallel\_tool\_calls?: boolean

Whether to enable parallel tool calling.

provider\_type?: "openai"

The type of the provider.

reasoning?: Reasoning { reasoning\_effort }

The reasoning configuration for the model.

reasoning\_effort?: "none" | "minimal" | "low" | 3 more

The reasoning effort to use when generating text reasoning models

Accepts one of the following:

"none"

"minimal"

"low"

"medium"

"high"

"xhigh"

response\_format?: [TextResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20text_response_format%20%3E%20(schema))
 { type } | [JsonSchemaResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_schema_response_format%20%3E%20(schema))
 { json\_schema, type } | [JsonObjectResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_object_response_format%20%3E%20(schema))
 { type } | null

The response format for the model.

Accepts one of the following:

TextResponseFormat { type }

Response format for plain text responses.

type?: "text"

The type of the response format.

JsonSchemaResponseFormat { json\_schema, type }

Response format for JSON schema-based responses.

json\_schema: Record<string, unknown\>

The JSON schema of the response.

type?: "json\_schema"

The type of the response format.

JsonObjectResponseFormat { type }

Response format for JSON object responses.

type?: "json\_object"

The type of the response format.

strict?: boolean

Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas.

temperature?: number

The temperature of the model.

SgLangModelSettings { max\_output\_tokens, parallel\_tool\_calls, provider\_type, 5 more }

SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing).

max\_output\_tokens?: number

The maximum number of tokens the model can generate.

parallel\_tool\_calls?: boolean

Whether to enable parallel tool calling.

provider\_type?: "sglang"

The type of the provider.

reasoning?: Reasoning { reasoning\_effort }

The reasoning configuration for the model.

reasoning\_effort?: "none" | "minimal" | "low" | 3 more

The reasoning effort to use when generating text reasoning models

Accepts one of the following:

"none"

"minimal"

"low"

"medium"

"high"

"xhigh"

response\_format?: [TextResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20text_response_format%20%3E%20(schema))
 { type } | [JsonSchemaResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_schema_response_format%20%3E%20(schema))
 { json\_schema, type } | [JsonObjectResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_object_response_format%20%3E%20(schema))
 { type } | null

The response format for the model.

Accepts one of the following:

TextResponseFormat { type }

Response format for plain text responses.

type?: "text"

The type of the response format.

JsonSchemaResponseFormat { json\_schema, type }

Response format for JSON schema-based responses.

json\_schema: Record<string, unknown\>

The JSON schema of the response.

type?: "json\_schema"

The type of the response format.

JsonObjectResponseFormat { type }

Response format for JSON object responses.

type?: "json\_object"

The type of the response format.

strict?: boolean

Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas.

temperature?: number

The temperature of the model.

tool\_call\_parser?: string | null

SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes').

AnthropicModelSettings { effort, max\_output\_tokens, parallel\_tool\_calls, 6 more }

effort?: "low" | "medium" | "high" | 2 more | null

Effort level for supported Anthropic models (controls token spending). 'xhigh' and 'max' are available on Opus 4.6+. Not setting this gives similar performance to 'high'.

Accepts one of the following:

"low"

"medium"

"high"

"xhigh"

"max"

max\_output\_tokens?: number

The maximum number of tokens the model can generate.

parallel\_tool\_calls?: boolean

Whether to enable parallel tool calling.

provider\_type?: "anthropic"

The type of the provider.

response\_format?: [TextResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20text_response_format%20%3E%20(schema))
 { type } | [JsonSchemaResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_schema_response_format%20%3E%20(schema))
 { json\_schema, type } | [JsonObjectResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_object_response_format%20%3E%20(schema))
 { type } | null

The response format for the model.

Accepts one of the following:

TextResponseFormat { type }

Response format for plain text responses.

type?: "text"

The type of the response format.

JsonSchemaResponseFormat { json\_schema, type }

Response format for JSON schema-based responses.

json\_schema: Record<string, unknown\>

The JSON schema of the response.

type?: "json\_schema"

The type of the response format.

JsonObjectResponseFormat { type }

Response format for JSON object responses.

type?: "json\_object"

The type of the response format.

strict?: boolean

Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas.

temperature?: number

The temperature of the model.

thinking?: Thinking { budget\_tokens, type }

The thinking configuration for the model.

budget\_tokens?: number

The maximum number of tokens the model can use for extended thinking.

type?: "enabled" | "disabled"

The type of thinking to use.

Accepts one of the following:

"enabled"

"disabled"

verbosity?: "low" | "medium" | "high" | null

Soft control for how verbose model output should be, used for GPT-5 models.

Accepts one of the following:

"low"

"medium"

"high"

GoogleAIModelSettings { max\_output\_tokens, parallel\_tool\_calls, provider\_type, 3 more }

max\_output\_tokens?: number

The maximum number of tokens the model can generate.

parallel\_tool\_calls?: boolean

Whether to enable parallel tool calling.

provider\_type?: "google\_ai"

The type of the provider.

response\_schema?: [TextResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20text_response_format%20%3E%20(schema))
 { type } | [JsonSchemaResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_schema_response_format%20%3E%20(schema))
 { json\_schema, type } | [JsonObjectResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_object_response_format%20%3E%20(schema))
 { type } | null

The response schema for the model.

Accepts one of the following:

TextResponseFormat { type }

Response format for plain text responses.

type?: "text"

The type of the response format.

JsonSchemaResponseFormat { json\_schema, type }

Response format for JSON schema-based responses.

json\_schema: Record<string, unknown\>

The JSON schema of the response.

type?: "json\_schema"

The type of the response format.

JsonObjectResponseFormat { type }

Response format for JSON object responses.

type?: "json\_object"

The type of the response format.

temperature?: number

The temperature of the model.

thinking\_config?: ThinkingConfig { include\_thoughts, thinking\_budget }

The thinking configuration for the model.

include\_thoughts?: boolean

Whether to include thoughts in the model's response.

thinking\_budget?: number

The thinking budget for the model.

GoogleVertexModelSettings { max\_output\_tokens, parallel\_tool\_calls, provider\_type, 3 more }

max\_output\_tokens?: number

The maximum number of tokens the model can generate.

parallel\_tool\_calls?: boolean

Whether to enable parallel tool calling.

provider\_type?: "google\_vertex"

The type of the provider.

response\_schema?: [TextResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20text_response_format%20%3E%20(schema))
 { type } | [JsonSchemaResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_schema_response_format%20%3E%20(schema))
 { json\_schema, type } | [JsonObjectResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_object_response_format%20%3E%20(schema))
 { type } | null

The response schema for the model.

Accepts one of the following:

TextResponseFormat { type }

Response format for plain text responses.

type?: "text"

The type of the response format.

JsonSchemaResponseFormat { json\_schema, type }

Response format for JSON schema-based responses.

json\_schema: Record<string, unknown\>

The JSON schema of the response.

type?: "json\_schema"

The type of the response format.

JsonObjectResponseFormat { type }

Response format for JSON object responses.

type?: "json\_object"

The type of the response format.

temperature?: number

The temperature of the model.

thinking\_config?: ThinkingConfig { include\_thoughts, thinking\_budget }

The thinking configuration for the model.

include\_thoughts?: boolean

Whether to include thoughts in the model's response.

thinking\_budget?: number

The thinking budget for the model.

AzureModelSettings { max\_output\_tokens, parallel\_tool\_calls, provider\_type, 2 more }

Azure OpenAI model configuration (OpenAI-compatible).

max\_output\_tokens?: number

The maximum number of tokens the model can generate.

parallel\_tool\_calls?: boolean

Whether to enable parallel tool calling.

provider\_type?: "azure"

The type of the provider.

response\_format?: [TextResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20text_response_format%20%3E%20(schema))
 { type } | [JsonSchemaResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_schema_response_format%20%3E%20(schema))
 { json\_schema, type } | [JsonObjectResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_object_response_format%20%3E%20(schema))
 { type } | null

The response format for the model.

Accepts one of the following:

TextResponseFormat { type }

Response format for plain text responses.

type?: "text"

The type of the response format.

JsonSchemaResponseFormat { json\_schema, type }

Response format for JSON schema-based responses.

json\_schema: Record<string, unknown\>

The JSON schema of the response.

type?: "json\_schema"

The type of the response format.

JsonObjectResponseFormat { type }

Response format for JSON object responses.

type?: "json\_object"

The type of the response format.

temperature?: number

The temperature of the model.

XaiModelSettings { max\_output\_tokens, parallel\_tool\_calls, provider\_type, 2 more }

xAI model configuration (OpenAI-compatible).

max\_output\_tokens?: number

The maximum number of tokens the model can generate.

parallel\_tool\_calls?: boolean

Whether to enable parallel tool calling.

provider\_type?: "xai"

The type of the provider.

response\_format?: [TextResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20text_response_format%20%3E%20(schema))
 { type } | [JsonSchemaResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_schema_response_format%20%3E%20(schema))
 { json\_schema, type } | [JsonObjectResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_object_response_format%20%3E%20(schema))
 { type } | null

The response format for the model.

Accepts one of the following:

TextResponseFormat { type }

Response format for plain text responses.

type?: "text"

The type of the response format.

JsonSchemaResponseFormat { json\_schema, type }

Response format for JSON schema-based responses.

json\_schema: Record<string, unknown\>

The JSON schema of the response.

type?: "json\_schema"

The type of the response format.

JsonObjectResponseFormat { type }

Response format for JSON object responses.

type?: "json\_object"

The type of the response format.

temperature?: number

The temperature of the model.

ZaiModelSettings { max\_output\_tokens, parallel\_tool\_calls, provider\_type, 3 more }

Z.ai (ZhipuAI) model configuration (OpenAI-compatible).

max\_output\_tokens?: number

The maximum number of tokens the model can generate.

parallel\_tool\_calls?: boolean

Whether to enable parallel tool calling.

provider\_type?: "zai"

The type of the provider.

response\_format?: [TextResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20text_response_format%20%3E%20(schema))
 { type } | [JsonSchemaResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_schema_response_format%20%3E%20(schema))
 { json\_schema, type } | [JsonObjectResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_object_response_format%20%3E%20(schema))
 { type } | null

The response format for the model.

Accepts one of the following:

TextResponseFormat { type }

Response format for plain text responses.

type?: "text"

The type of the response format.

JsonSchemaResponseFormat { json\_schema, type }

Response format for JSON schema-based responses.

json\_schema: Record<string, unknown\>

The JSON schema of the response.

type?: "json\_schema"

The type of the response format.

JsonObjectResponseFormat { type }

Response format for JSON object responses.

type?: "json\_object"

The type of the response format.

temperature?: number

The temperature of the model.

thinking?: Thinking { clear\_thinking, type }

The thinking configuration for GLM-4.5+ models.

clear\_thinking?: boolean

If False, preserved thinking is used (recommended for agents).

type?: "enabled" | "disabled"

Whether thinking is enabled or disabled.

Accepts one of the following:

"enabled"

"disabled"

GroqModelSettings { max\_output\_tokens, parallel\_tool\_calls, provider\_type, 2 more }

Groq model configuration (OpenAI-compatible).

max\_output\_tokens?: number

The maximum number of tokens the model can generate.

parallel\_tool\_calls?: boolean

Whether to enable parallel tool calling.

provider\_type?: "groq"

The type of the provider.

response\_format?: [TextResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20text_response_format%20%3E%20(schema))
 { type } | [JsonSchemaResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_schema_response_format%20%3E%20(schema))
 { json\_schema, type } | [JsonObjectResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_object_response_format%20%3E%20(schema))
 { type } | null

The response format for the model.

Accepts one of the following:

TextResponseFormat { type }

Response format for plain text responses.

type?: "text"

The type of the response format.

JsonSchemaResponseFormat { json\_schema, type }

Response format for JSON schema-based responses.

json\_schema: Record<string, unknown\>

The JSON schema of the response.

type?: "json\_schema"

The type of the response format.

JsonObjectResponseFormat { type }

Response format for JSON object responses.

type?: "json\_object"

The type of the response format.

temperature?: number

The temperature of the model.

DeepseekModelSettings { max\_output\_tokens, parallel\_tool\_calls, provider\_type, 2 more }

Deepseek model configuration (OpenAI-compatible).

max\_output\_tokens?: number

The maximum number of tokens the model can generate.

parallel\_tool\_calls?: boolean

Whether to enable parallel tool calling.

provider\_type?: "deepseek"

The type of the provider.

response\_format?: [TextResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20text_response_format%20%3E%20(schema))
 { type } | [JsonSchemaResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_schema_response_format%20%3E%20(schema))
 { json\_schema, type } | [JsonObjectResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_object_response_format%20%3E%20(schema))
 { type } | null

The response format for the model.

Accepts one of the following:

TextResponseFormat { type }

Response format for plain text responses.

type?: "text"

The type of the response format.

JsonSchemaResponseFormat { json\_schema, type }

Response format for JSON schema-based responses.

json\_schema: Record<string, unknown\>

The JSON schema of the response.

type?: "json\_schema"

The type of the response format.

JsonObjectResponseFormat { type }

Response format for JSON object responses.

type?: "json\_object"

The type of the response format.

temperature?: number

The temperature of the model.

TogetherModelSettings { max\_output\_tokens, parallel\_tool\_calls, provider\_type, 2 more }

Together AI model configuration (OpenAI-compatible).

max\_output\_tokens?: number

The maximum number of tokens the model can generate.

parallel\_tool\_calls?: boolean

Whether to enable parallel tool calling.

provider\_type?: "together"

The type of the provider.

response\_format?: [TextResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20text_response_format%20%3E%20(schema))
 { type } | [JsonSchemaResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_schema_response_format%20%3E%20(schema))
 { json\_schema, type } | [JsonObjectResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_object_response_format%20%3E%20(schema))
 { type } | null

The response format for the model.

Accepts one of the following:

TextResponseFormat { type }

Response format for plain text responses.

type?: "text"

The type of the response format.

JsonSchemaResponseFormat { json\_schema, type }

Response format for JSON schema-based responses.

json\_schema: Record<string, unknown\>

The JSON schema of the response.

type?: "json\_schema"

The type of the response format.

JsonObjectResponseFormat { type }

Response format for JSON object responses.

type?: "json\_object"

The type of the response format.

temperature?: number

The temperature of the model.

BedrockModelSettings { max\_output\_tokens, parallel\_tool\_calls, provider\_type, 2 more }

AWS Bedrock model configuration.

max\_output\_tokens?: number

The maximum number of tokens the model can generate.

parallel\_tool\_calls?: boolean

Whether to enable parallel tool calling.

provider\_type?: "bedrock"

The type of the provider.

response\_format?: [TextResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20text_response_format%20%3E%20(schema))
 { type } | [JsonSchemaResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_schema_response_format%20%3E%20(schema))
 { json\_schema, type } | [JsonObjectResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_object_response_format%20%3E%20(schema))
 { type } | null

The response format for the model.

Accepts one of the following:

TextResponseFormat { type }

Response format for plain text responses.

type?: "text"

The type of the response format.

JsonSchemaResponseFormat { json\_schema, type }

Response format for JSON schema-based responses.

json\_schema: Record<string, unknown\>

The JSON schema of the response.

type?: "json\_schema"

The type of the response format.

JsonObjectResponseFormat { type }

Response format for JSON object responses.

type?: "json\_object"

The type of the response format.

temperature?: number

The temperature of the model.

BasetenModelSettings { max\_output\_tokens, parallel\_tool\_calls, provider\_type, temperature }

Baseten model configuration (OpenAI-compatible).

max\_output\_tokens?: number

The maximum number of tokens the model can generate.

parallel\_tool\_calls?: boolean

Whether to enable parallel tool calling.

provider\_type?: "baseten"

The type of the provider.

temperature?: number

The temperature of the model.

OpenRouterModelSettings { max\_output\_tokens, parallel\_tool\_calls, provider\_type, 2 more }

OpenRouter model configuration (OpenAI-compatible).

max\_output\_tokens?: number

The maximum number of tokens the model can generate.

parallel\_tool\_calls?: boolean

Whether to enable parallel tool calling.

provider\_type?: "openrouter"

The type of the provider.

response\_format?: [TextResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20text_response_format%20%3E%20(schema))
 { type } | [JsonSchemaResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_schema_response_format%20%3E%20(schema))
 { json\_schema, type } | [JsonObjectResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_object_response_format%20%3E%20(schema))
 { type } | null

The response format for the model.

Accepts one of the following:

TextResponseFormat { type }

Response format for plain text responses.

type?: "text"

The type of the response format.

JsonSchemaResponseFormat { json\_schema, type }

Response format for JSON schema-based responses.

json\_schema: Record<string, unknown\>

The JSON schema of the response.

type?: "json\_schema"

The type of the response format.

JsonObjectResponseFormat { type }

Response format for JSON object responses.

type?: "json\_object"

The type of the response format.

temperature?: number

The temperature of the model.

ChatGptoAuthModelSettings { max\_output\_tokens, parallel\_tool\_calls, provider\_type, 2 more }

ChatGPT OAuth model configuration (uses ChatGPT backend API).

max\_output\_tokens?: number

The maximum number of tokens the model can generate.

parallel\_tool\_calls?: boolean

Whether to enable parallel tool calling.

provider\_type?: "chatgpt\_oauth"

The type of the provider.

reasoning?: Reasoning { reasoning\_effort }

The reasoning configuration for the model.

reasoning\_effort?: "none" | "low" | "medium" | 2 more

The reasoning effort level for GPT-5.x and o-series models.

Accepts one of the following:

"none"

"low"

"medium"

"high"

"xhigh"

temperature?: number

The temperature of the model.

summary?: string | null

A summary of the conversation.

#### ConversationsMessages

##### [List Conversation Messages](https://docs.letta.com/api/typescript/resources/conversations/subresources/messages/methods/list)

client.conversations.messages.list(stringconversationID, MessageListParams { after, agent\_id, before, 6 more } query?, RequestOptionsoptions?): ArrayPage<[Message](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20message%20%3E%20(schema))
\>

get/v1/conversations/{conversation\_id}/messages

##### [Send Conversation Message](https://docs.letta.com/api/typescript/resources/conversations/subresources/messages/methods/create)

client.conversations.messages.create(stringconversationID, MessageCreateParams { agent\_id, assistant\_message\_tool\_kwarg, assistant\_message\_tool\_name, 18 more } body, RequestOptionsoptions?): [LettaResponse](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20letta_response%20%3E%20(schema))
 { messages, stop\_reason, usage, 2 more } | Stream<[LettaStreamingResponse](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20letta_streaming_response%20%3E%20(schema))
\>

post/v1/conversations/{conversation\_id}/messages

##### [Retrieve Conversation Stream](https://docs.letta.com/api/typescript/resources/conversations/subresources/messages/methods/stream)

client.conversations.messages.stream(stringconversationID, MessageStreamParams { agent\_id, batch\_size, include\_pings, 4 more } body?, RequestOptionsoptions?): [MessageStreamResponse](https://docs.letta.com/api/typescript/resources/conversations#(resource)%20conversations.messages%20%3E%20(model)%20message_stream_response%20%3E%20(schema))
 | Stream<[LettaStreamingResponse](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents.messages%20%3E%20(model)%20letta_streaming_response%20%3E%20(schema))
\>

post/v1/conversations/{conversation\_id}/stream

##### [Compact Conversation](https://docs.letta.com/api/typescript/resources/conversations/subresources/messages/methods/compact)

client.conversations.messages.compact(stringconversationID, MessageCompactParams { agent\_id, compaction\_settings } body?, RequestOptionsoptions?): [CompactionResponse](https://docs.letta.com/api/typescript/resources/conversations#(resource)%20conversations.messages%20%3E%20(model)%20compaction_response%20%3E%20(schema))
 { num\_messages\_after, num\_messages\_before, summary }

post/v1/conversations/{conversation\_id}/compact

##### ModelsExpand Collapse

CompactionRequest { compaction\_settings }

compaction\_settings?: CompactionSettings | null

Configuration for conversation compaction / summarization.

Per-model settings (temperature, max tokens, etc.) are derived from the default configuration for that handle.

clip\_chars?: number | null

The maximum length of the summary in characters. If none, no clipping is performed.

mode?: "all" | "sliding\_window" | "self\_compact\_all" | "self\_compact\_sliding\_window"

The type of summarization technique use.

Accepts one of the following:

"all"

"sliding\_window"

"self\_compact\_all"

"self\_compact\_sliding\_window"

model?: string | null

Model handle to use for sliding\_window/all summarization (format: provider/model-name). If None, uses lightweight provider-specific defaults.

model\_settings?: [OpenAIModelSettings](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20openai_model_settings%20%3E%20(schema))
 { max\_output\_tokens, parallel\_tool\_calls, provider\_type, 4 more } | SgLangModelSettings { max\_output\_tokens, parallel\_tool\_calls, provider\_type, 5 more } | [AnthropicModelSettings](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20anthropic_model_settings%20%3E%20(schema))
 { effort, max\_output\_tokens, parallel\_tool\_calls, 6 more } | 12 more | null

Optional model settings used to override defaults for the summarizer model.

Accepts one of the following:

OpenAIModelSettings { max\_output\_tokens, parallel\_tool\_calls, provider\_type, 4 more }

max\_output\_tokens?: number

The maximum number of tokens the model can generate.

parallel\_tool\_calls?: boolean

Whether to enable parallel tool calling.

provider\_type?: "openai"

The type of the provider.

reasoning?: Reasoning { reasoning\_effort }

The reasoning configuration for the model.

reasoning\_effort?: "none" | "minimal" | "low" | 3 more

The reasoning effort to use when generating text reasoning models

Accepts one of the following:

"none"

"minimal"

"low"

"medium"

"high"

"xhigh"

response\_format?: [TextResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20text_response_format%20%3E%20(schema))
 { type } | [JsonSchemaResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_schema_response_format%20%3E%20(schema))
 { json\_schema, type } | [JsonObjectResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_object_response_format%20%3E%20(schema))
 { type } | null

The response format for the model.

Accepts one of the following:

TextResponseFormat { type }

Response format for plain text responses.

type?: "text"

The type of the response format.

JsonSchemaResponseFormat { json\_schema, type }

Response format for JSON schema-based responses.

json\_schema: Record<string, unknown\>

The JSON schema of the response.

type?: "json\_schema"

The type of the response format.

JsonObjectResponseFormat { type }

Response format for JSON object responses.

type?: "json\_object"

The type of the response format.

strict?: boolean

Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas.

temperature?: number

The temperature of the model.

SgLangModelSettings { max\_output\_tokens, parallel\_tool\_calls, provider\_type, 5 more }

SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing).

max\_output\_tokens?: number

The maximum number of tokens the model can generate.

parallel\_tool\_calls?: boolean

Whether to enable parallel tool calling.

provider\_type?: "sglang"

The type of the provider.

reasoning?: Reasoning { reasoning\_effort }

The reasoning configuration for the model.

reasoning\_effort?: "none" | "minimal" | "low" | 3 more

The reasoning effort to use when generating text reasoning models

Accepts one of the following:

"none"

"minimal"

"low"

"medium"

"high"

"xhigh"

response\_format?: [TextResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20text_response_format%20%3E%20(schema))
 { type } | [JsonSchemaResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_schema_response_format%20%3E%20(schema))
 { json\_schema, type } | [JsonObjectResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_object_response_format%20%3E%20(schema))
 { type } | null

The response format for the model.

Accepts one of the following:

TextResponseFormat { type }

Response format for plain text responses.

type?: "text"

The type of the response format.

JsonSchemaResponseFormat { json\_schema, type }

Response format for JSON schema-based responses.

json\_schema: Record<string, unknown\>

The JSON schema of the response.

type?: "json\_schema"

The type of the response format.

JsonObjectResponseFormat { type }

Response format for JSON object responses.

type?: "json\_object"

The type of the response format.

strict?: boolean

Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas.

temperature?: number

The temperature of the model.

tool\_call\_parser?: string | null

SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes').

AnthropicModelSettings { effort, max\_output\_tokens, parallel\_tool\_calls, 6 more }

effort?: "low" | "medium" | "high" | 2 more | null

Effort level for supported Anthropic models (controls token spending). 'xhigh' and 'max' are available on Opus 4.6+. Not setting this gives similar performance to 'high'.

Accepts one of the following:

"low"

"medium"

"high"

"xhigh"

"max"

max\_output\_tokens?: number

The maximum number of tokens the model can generate.

parallel\_tool\_calls?: boolean

Whether to enable parallel tool calling.

provider\_type?: "anthropic"

The type of the provider.

response\_format?: [TextResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20text_response_format%20%3E%20(schema))
 { type } | [JsonSchemaResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_schema_response_format%20%3E%20(schema))
 { json\_schema, type } | [JsonObjectResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_object_response_format%20%3E%20(schema))
 { type } | null

The response format for the model.

Accepts one of the following:

TextResponseFormat { type }

Response format for plain text responses.

type?: "text"

The type of the response format.

JsonSchemaResponseFormat { json\_schema, type }

Response format for JSON schema-based responses.

json\_schema: Record<string, unknown\>

The JSON schema of the response.

type?: "json\_schema"

The type of the response format.

JsonObjectResponseFormat { type }

Response format for JSON object responses.

type?: "json\_object"

The type of the response format.

strict?: boolean

Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas.

temperature?: number

The temperature of the model.

thinking?: Thinking { budget\_tokens, type }

The thinking configuration for the model.

budget\_tokens?: number

The maximum number of tokens the model can use for extended thinking.

type?: "enabled" | "disabled"

The type of thinking to use.

Accepts one of the following:

"enabled"

"disabled"

verbosity?: "low" | "medium" | "high" | null

Soft control for how verbose model output should be, used for GPT-5 models.

Accepts one of the following:

"low"

"medium"

"high"

GoogleAIModelSettings { max\_output\_tokens, parallel\_tool\_calls, provider\_type, 3 more }

max\_output\_tokens?: number

The maximum number of tokens the model can generate.

parallel\_tool\_calls?: boolean

Whether to enable parallel tool calling.

provider\_type?: "google\_ai"

The type of the provider.

response\_schema?: [TextResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20text_response_format%20%3E%20(schema))
 { type } | [JsonSchemaResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_schema_response_format%20%3E%20(schema))
 { json\_schema, type } | [JsonObjectResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_object_response_format%20%3E%20(schema))
 { type } | null

The response schema for the model.

Accepts one of the following:

TextResponseFormat { type }

Response format for plain text responses.

type?: "text"

The type of the response format.

JsonSchemaResponseFormat { json\_schema, type }

Response format for JSON schema-based responses.

json\_schema: Record<string, unknown\>

The JSON schema of the response.

type?: "json\_schema"

The type of the response format.

JsonObjectResponseFormat { type }

Response format for JSON object responses.

type?: "json\_object"

The type of the response format.

temperature?: number

The temperature of the model.

thinking\_config?: ThinkingConfig { include\_thoughts, thinking\_budget }

The thinking configuration for the model.

include\_thoughts?: boolean

Whether to include thoughts in the model's response.

thinking\_budget?: number

The thinking budget for the model.

GoogleVertexModelSettings { max\_output\_tokens, parallel\_tool\_calls, provider\_type, 3 more }

max\_output\_tokens?: number

The maximum number of tokens the model can generate.

parallel\_tool\_calls?: boolean

Whether to enable parallel tool calling.

provider\_type?: "google\_vertex"

The type of the provider.

response\_schema?: [TextResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20text_response_format%20%3E%20(schema))
 { type } | [JsonSchemaResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_schema_response_format%20%3E%20(schema))
 { json\_schema, type } | [JsonObjectResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_object_response_format%20%3E%20(schema))
 { type } | null

The response schema for the model.

Accepts one of the following:

TextResponseFormat { type }

Response format for plain text responses.

type?: "text"

The type of the response format.

JsonSchemaResponseFormat { json\_schema, type }

Response format for JSON schema-based responses.

json\_schema: Record<string, unknown\>

The JSON schema of the response.

type?: "json\_schema"

The type of the response format.

JsonObjectResponseFormat { type }

Response format for JSON object responses.

type?: "json\_object"

The type of the response format.

temperature?: number

The temperature of the model.

thinking\_config?: ThinkingConfig { include\_thoughts, thinking\_budget }

The thinking configuration for the model.

include\_thoughts?: boolean

Whether to include thoughts in the model's response.

thinking\_budget?: number

The thinking budget for the model.

AzureModelSettings { max\_output\_tokens, parallel\_tool\_calls, provider\_type, 2 more }

Azure OpenAI model configuration (OpenAI-compatible).

max\_output\_tokens?: number

The maximum number of tokens the model can generate.

parallel\_tool\_calls?: boolean

Whether to enable parallel tool calling.

provider\_type?: "azure"

The type of the provider.

response\_format?: [TextResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20text_response_format%20%3E%20(schema))
 { type } | [JsonSchemaResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_schema_response_format%20%3E%20(schema))
 { json\_schema, type } | [JsonObjectResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_object_response_format%20%3E%20(schema))
 { type } | null

The response format for the model.

Accepts one of the following:

TextResponseFormat { type }

Response format for plain text responses.

type?: "text"

The type of the response format.

JsonSchemaResponseFormat { json\_schema, type }

Response format for JSON schema-based responses.

json\_schema: Record<string, unknown\>

The JSON schema of the response.

type?: "json\_schema"

The type of the response format.

JsonObjectResponseFormat { type }

Response format for JSON object responses.

type?: "json\_object"

The type of the response format.

temperature?: number

The temperature of the model.

XaiModelSettings { max\_output\_tokens, parallel\_tool\_calls, provider\_type, 2 more }

xAI model configuration (OpenAI-compatible).

max\_output\_tokens?: number

The maximum number of tokens the model can generate.

parallel\_tool\_calls?: boolean

Whether to enable parallel tool calling.

provider\_type?: "xai"

The type of the provider.

response\_format?: [TextResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20text_response_format%20%3E%20(schema))
 { type } | [JsonSchemaResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_schema_response_format%20%3E%20(schema))
 { json\_schema, type } | [JsonObjectResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_object_response_format%20%3E%20(schema))
 { type } | null

The response format for the model.

Accepts one of the following:

TextResponseFormat { type }

Response format for plain text responses.

type?: "text"

The type of the response format.

JsonSchemaResponseFormat { json\_schema, type }

Response format for JSON schema-based responses.

json\_schema: Record<string, unknown\>

The JSON schema of the response.

type?: "json\_schema"

The type of the response format.

JsonObjectResponseFormat { type }

Response format for JSON object responses.

type?: "json\_object"

The type of the response format.

temperature?: number

The temperature of the model.

ZaiModelSettings { max\_output\_tokens, parallel\_tool\_calls, provider\_type, 3 more }

Z.ai (ZhipuAI) model configuration (OpenAI-compatible).

max\_output\_tokens?: number

The maximum number of tokens the model can generate.

parallel\_tool\_calls?: boolean

Whether to enable parallel tool calling.

provider\_type?: "zai"

The type of the provider.

response\_format?: [TextResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20text_response_format%20%3E%20(schema))
 { type } | [JsonSchemaResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_schema_response_format%20%3E%20(schema))
 { json\_schema, type } | [JsonObjectResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_object_response_format%20%3E%20(schema))
 { type } | null

The response format for the model.

Accepts one of the following:

TextResponseFormat { type }

Response format for plain text responses.

type?: "text"

The type of the response format.

JsonSchemaResponseFormat { json\_schema, type }

Response format for JSON schema-based responses.

json\_schema: Record<string, unknown\>

The JSON schema of the response.

type?: "json\_schema"

The type of the response format.

JsonObjectResponseFormat { type }

Response format for JSON object responses.

type?: "json\_object"

The type of the response format.

temperature?: number

The temperature of the model.

thinking?: Thinking { clear\_thinking, type }

The thinking configuration for GLM-4.5+ models.

clear\_thinking?: boolean

If False, preserved thinking is used (recommended for agents).

type?: "enabled" | "disabled"

Whether thinking is enabled or disabled.

Accepts one of the following:

"enabled"

"disabled"

GroqModelSettings { max\_output\_tokens, parallel\_tool\_calls, provider\_type, 2 more }

Groq model configuration (OpenAI-compatible).

max\_output\_tokens?: number

The maximum number of tokens the model can generate.

parallel\_tool\_calls?: boolean

Whether to enable parallel tool calling.

provider\_type?: "groq"

The type of the provider.

response\_format?: [TextResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20text_response_format%20%3E%20(schema))
 { type } | [JsonSchemaResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_schema_response_format%20%3E%20(schema))
 { json\_schema, type } | [JsonObjectResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_object_response_format%20%3E%20(schema))
 { type } | null

The response format for the model.

Accepts one of the following:

TextResponseFormat { type }

Response format for plain text responses.

type?: "text"

The type of the response format.

JsonSchemaResponseFormat { json\_schema, type }

Response format for JSON schema-based responses.

json\_schema: Record<string, unknown\>

The JSON schema of the response.

type?: "json\_schema"

The type of the response format.

JsonObjectResponseFormat { type }

Response format for JSON object responses.

type?: "json\_object"

The type of the response format.

temperature?: number

The temperature of the model.

DeepseekModelSettings { max\_output\_tokens, parallel\_tool\_calls, provider\_type, 2 more }

Deepseek model configuration (OpenAI-compatible).

max\_output\_tokens?: number

The maximum number of tokens the model can generate.

parallel\_tool\_calls?: boolean

Whether to enable parallel tool calling.

provider\_type?: "deepseek"

The type of the provider.

response\_format?: [TextResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20text_response_format%20%3E%20(schema))
 { type } | [JsonSchemaResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_schema_response_format%20%3E%20(schema))
 { json\_schema, type } | [JsonObjectResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_object_response_format%20%3E%20(schema))
 { type } | null

The response format for the model.

Accepts one of the following:

TextResponseFormat { type }

Response format for plain text responses.

type?: "text"

The type of the response format.

JsonSchemaResponseFormat { json\_schema, type }

Response format for JSON schema-based responses.

json\_schema: Record<string, unknown\>

The JSON schema of the response.

type?: "json\_schema"

The type of the response format.

JsonObjectResponseFormat { type }

Response format for JSON object responses.

type?: "json\_object"

The type of the response format.

temperature?: number

The temperature of the model.

TogetherModelSettings { max\_output\_tokens, parallel\_tool\_calls, provider\_type, 2 more }

Together AI model configuration (OpenAI-compatible).

max\_output\_tokens?: number

The maximum number of tokens the model can generate.

parallel\_tool\_calls?: boolean

Whether to enable parallel tool calling.

provider\_type?: "together"

The type of the provider.

response\_format?: [TextResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20text_response_format%20%3E%20(schema))
 { type } | [JsonSchemaResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_schema_response_format%20%3E%20(schema))
 { json\_schema, type } | [JsonObjectResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_object_response_format%20%3E%20(schema))
 { type } | null

The response format for the model.

Accepts one of the following:

TextResponseFormat { type }

Response format for plain text responses.

type?: "text"

The type of the response format.

JsonSchemaResponseFormat { json\_schema, type }

Response format for JSON schema-based responses.

json\_schema: Record<string, unknown\>

The JSON schema of the response.

type?: "json\_schema"

The type of the response format.

JsonObjectResponseFormat { type }

Response format for JSON object responses.

type?: "json\_object"

The type of the response format.

temperature?: number

The temperature of the model.

BedrockModelSettings { max\_output\_tokens, parallel\_tool\_calls, provider\_type, 2 more }

AWS Bedrock model configuration.

max\_output\_tokens?: number

The maximum number of tokens the model can generate.

parallel\_tool\_calls?: boolean

Whether to enable parallel tool calling.

provider\_type?: "bedrock"

The type of the provider.

response\_format?: [TextResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20text_response_format%20%3E%20(schema))
 { type } | [JsonSchemaResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_schema_response_format%20%3E%20(schema))
 { json\_schema, type } | [JsonObjectResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_object_response_format%20%3E%20(schema))
 { type } | null

The response format for the model.

Accepts one of the following:

TextResponseFormat { type }

Response format for plain text responses.

type?: "text"

The type of the response format.

JsonSchemaResponseFormat { json\_schema, type }

Response format for JSON schema-based responses.

json\_schema: Record<string, unknown\>

The JSON schema of the response.

type?: "json\_schema"

The type of the response format.

JsonObjectResponseFormat { type }

Response format for JSON object responses.

type?: "json\_object"

The type of the response format.

temperature?: number

The temperature of the model.

BasetenModelSettings { max\_output\_tokens, parallel\_tool\_calls, provider\_type, temperature }

Baseten model configuration (OpenAI-compatible).

max\_output\_tokens?: number

The maximum number of tokens the model can generate.

parallel\_tool\_calls?: boolean

Whether to enable parallel tool calling.

provider\_type?: "baseten"

The type of the provider.

temperature?: number

The temperature of the model.

OpenRouterModelSettings { max\_output\_tokens, parallel\_tool\_calls, provider\_type, 2 more }

OpenRouter model configuration (OpenAI-compatible).

max\_output\_tokens?: number

The maximum number of tokens the model can generate.

parallel\_tool\_calls?: boolean

Whether to enable parallel tool calling.

provider\_type?: "openrouter"

The type of the provider.

response\_format?: [TextResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20text_response_format%20%3E%20(schema))
 { type } | [JsonSchemaResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_schema_response_format%20%3E%20(schema))
 { json\_schema, type } | [JsonObjectResponseFormat](https://docs.letta.com/api/typescript/resources/agents#(resource)%20agents%20%3E%20(model)%20json_object_response_format%20%3E%20(schema))
 { type } | null

The response format for the model.

Accepts one of the following:

TextResponseFormat { type }

Response format for plain text responses.

type?: "text"

The type of the response format.

JsonSchemaResponseFormat { json\_schema, type }

Response format for JSON schema-based responses.

json\_schema: Record<string, unknown\>

The JSON schema of the response.

type?: "json\_schema"

The type of the response format.

JsonObjectResponseFormat { type }

Response format for JSON object responses.

type?: "json\_object"

The type of the response format.

temperature?: number

The temperature of the model.

ChatGptoAuthModelSettings { max\_output\_tokens, parallel\_tool\_calls, provider\_type, 2 more }

ChatGPT OAuth model configuration (uses ChatGPT backend API).

max\_output\_tokens?: number

The maximum number of tokens the model can generate.

parallel\_tool\_calls?: boolean

Whether to enable parallel tool calling.

provider\_type?: "chatgpt\_oauth"

The type of the provider.

reasoning?: Reasoning { reasoning\_effort }

The reasoning configuration for the model.

reasoning\_effort?: "none" | "low" | "medium" | 2 more

The reasoning effort level for GPT-5.x and o-series models.

Accepts one of the following:

"none"

"low"

"medium"

"high"

"xhigh"

temperature?: number

The temperature of the model.

prompt?: string | null

The prompt to use for summarization. If None, uses mode-specific default.

prompt\_acknowledgement?: boolean

Whether to include an acknowledgement post-prompt (helps prevent non-summary outputs).

sliding\_window\_percentage?: number

The percentage of the context window to keep post-summarization (only used in sliding window modes).

CompactionResponse { num\_messages\_after, num\_messages\_before, summary }

num\_messages\_after: number

num\_messages\_before: number

summary: string

---