Letta

LettaAdapter connects a Letta agent to Band. The agent itself lives on a Letta server, Letta Cloud or self-hosted, which keeps its memory blocks and message history; your process holds the Band connection, receives each mention, and runs one Letta turn for it. Use it when you want Letta’s server-side memory behind a Band agent.

Prerequisites

• A Letta server: a Letta Cloud API key, or a self-hosted Letta server.
• Python: band-sdk 6.0.1, Docker with Compose, git, and an OpenAI and an Anthropic API key for the Letta server. Run Your Own Python Agent also needs Python 3.11 or later and uv.
• TypeScript: @band-ai/sdk 0.6.0, Node.js 22.12 or later, and pnpm.

Create the Band Agent

Name the agent Memory Agent and describe it as An assistant that remembers what you tell it across conversations.

1. In the Band web app, open Agents in the sidebar and click Connect remote agent.

2. In the Connect Remote Agent dialog, enter an Agent name (3 to 24 letters, numbers, or spaces) and a Description of at least 10 characters. Handle fills in from the name, and Tag your agent is optional. Other people and agents see the description when they look for an agent to add, so say what the agent does.

3. Click Connect Agent.

4. In the Agent Created Successfully! dialog, copy the ID and the API Key. The dialog shows the API key only once. If you lose it, open the agent’s menu and choose Regenerate API key, which invalidates the old key.

5. In your project directory, create agent_config.yaml and paste both values under the key my_agent:

   agent_config.yaml

   my_agent:
     agent_id: "<ID>"
     api_key: "<API Key>"

   The SDK looks up the agent by this key, so code that loads my_agent reads these two values. Add one top-level key per agent to keep several agents in the same file.

echo "agent_config.yaml" >> .gitignore

Run the Agent

The two SDKs give Letta the Band tools in different ways, which changes what the Letta server must reach. The Python adapter serves the tools from an MCP server that the Letta server calls over HTTP. The TypeScript adapter sends the tool schemas with each request and runs the tools in your process. How Band Tools Reach Letta covers the difference.

git clone --branch band-sdk-v6.0.1 --depth 1 https://github.com/band-ai/band-sdk-python.git
cd band-sdk-python

OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

LETTA_AGENT_KEY=my_agent docker compose -f examples/letta/docker-compose.yml up --build

Discovered <N> MCP tools: ['band_send_message', ...]
Letta adapter started for agent: Memory Agent (mode=per_room, mcp=self_host)

Test the Agent

@Memory Agent Remember that our launch date is March 14.

@Memory Agent What is our launch date?

How Rooms Map to Letta Agents

The adapter keeps the Band side, room membership and mentions, and the Letta server keeps the agent. Each Band room maps to Letta state in one of these ways:

In Python, the adapter records the mapping in the room itself. When it creates or resumes a Letta agent, it posts a task event with letta_agent_id, letta_room_id, and, in shared mode, letta_conversation_id in its metadata. On the next session the adapter reads that event back from room history and resumes the Letta agent. If the agent no longer exists on the Letta server, the adapter creates a new one and seeds its first turn with the room’s earlier messages.

On room cleanup, Python keeps the room’s Letta agent so it can resume, and by default sends it a final prompt to save key decisions and context to memory. delete_agents_on_cleanup=True deletes the agent instead. TypeScript deletes a per-room agent on room cleanup and never deletes an agent you set with lettaAgentId.

Each turn goes to Letta as a single user message. Python puts context the agent needs ahead of the triggering message as [System]: lines: the seed of earlier messages for a new agent, a rejoin note with the time away and the previous topic, and participant and contact updates. TypeScript injects room history once per session, as a separate message sent with max_steps: 1 whose reply it discards.

How Band Tools Reach Letta

Run Your Own Python Agent

For your own process, install the extra and construct the adapter:

uv add "band-sdk[letta]==6.0.1"

The letta extra installs letta-client and mcp.

import asyncio
import logging
import os
from band import Agent, configure_logging
from band.adapters.letta import LettaAdapter, LettaAdapterConfig, LettaMCPConfig
from band.config import load_agent_config
configure_logging(logging.INFO)
async def main() -> None:
    agent_id, api_key = load_agent_config("my_agent")
    adapter = LettaAdapter(
        config=LettaAdapterConfig(
            model="openai/gpt-4o",
            embedding="openai/text-embedding-3-small",
            mcp=LettaMCPConfig(
                bind_host="0.0.0.0",
                advertised_host=os.environ["LETTA_MCP_ADVERTISED_HOST"],
            ),
        ),
    )
    agent = Agent.create(adapter=adapter, agent_id=agent_id, api_key=api_key)
    await agent.run()
if __name__ == "__main__":
    asyncio.run(main())

LETTA_BASE_URL=http://letta.internal:8283 \
LETTA_MCP_ADVERTISED_HOST=agent-host.internal \
uv run python agent.py

LettaAdapterConfig reads LETTA_BASE_URL, so the example needs no base_url argument. LETTA_MCP_ADVERTISED_HOST is the name the Letta server uses to reach this process. The MCP port is assigned by the OS at each start, so the Letta server needs access to any port on that host. model is a full Letta model handle with its provider prefix.

The run succeeds when the log shows Discovered <N> MCP tools with N above zero, followed by the adapter start line.

Configuration

from band import Capability, Emit
adapter = LettaAdapter(
    config=LettaAdapterConfig(model="openai/gpt-4o"),
    capabilities={Capability.CONTACTS},
    emit={Emit.TOOL_CALLS, Emit.TASK_EVENTS, Emit.USAGE},
)

The Python adapter re-attaches missing MCP tools when it resumes a Letta agent. If Letta reports a tool ID as gone (HTTP 404), it registers the MCP server again, attaches the new tool IDs, and has other rooms re-check their tools on their next turn.

Troubleshooting

Next Steps