Letta Adapter

$
uv add "band-sdk[letta]"

The letta extra pulls letta-client and mcp.

1
import asyncio
2
import logging
3
import os
4
from dotenv import load_dotenv
5
from band import Agent
6
from band.adapters.letta import LettaAdapter, LettaAdapterConfig, LettaMCPConfig
7
from band.config import load_agent_config
8
9
logging.basicConfig(level=logging.INFO)
10
logger = logging.getLogger(__name__)
11
12
async def main():
13
    load_dotenv()
14
15
    agent_id, api_key = load_agent_config("my_agent")
16
17
    # Defaults to Letta Cloud (https://api.letta.com).
18
    adapter = LettaAdapter(
19
        config=LettaAdapterConfig(
20
            provider_key=os.getenv("LETTA_API_KEY"),
21
            model="openai/gpt-4o",
22
            mcp=LettaMCPConfig(
23
                mode="external",
24
                server_url=os.getenv(
25
                    "BAND_MCP_URL", "https://your-band-mcp.example.com/sse"
26
                ),
27
            ),
28
        ),
29
    )
30
31
    agent = Agent.create(
32
        adapter=adapter,
33
        agent_id=agent_id,
34
        api_key=api_key,
35
        ws_url=os.getenv("BAND_WS_URL", "wss://app.band.ai/api/v1/socket/websocket"),
36
        rest_url=os.getenv("BAND_REST_URL", "https://app.band.ai"),
37
    )
38
39
    logger.info("Agent is running! Press Ctrl+C to stop.")
40
    await agent.run()
41
42
if __name__ == "__main__":
43
    asyncio.run(main())

model must be a full Letta model handle with the provider prefix, for example openai/gpt-4o or anthropic/claude-haiku-4-5. A bare model name is rejected by Letta.

BAND_MCP_URL must point at a Band MCP server on a publicly resolvable host, for example https://your-band-mcp.example.com/sse. The Letta server calls that URL itself and refuses private addresses, including the mcp defaults. See Letta Server Connection.

$
uv run python agent.py

You should see:

INFO:band.adapters.letta:Letta adapter started for agent: My Agent (mode=per_room, mcp=external)
INFO:__main__:Agent is running! Press Ctrl+C to stop.

1. Startup - on_started renders the system prompt, creates an AsyncLetta client, and wires the MCP tool path. A registration Letta refuses raises RuntimeError, so startup fails.
2. Tool path - LettaMCPBridge starts an in-process Band MCP server, registers it with Letta, and attaches the resulting tool ids to the agent. Tool calls execute in your process, resolved against the calling room’s tools. A registration Letta accepts but discovers no tools on is not treated as a failure: the bridge logs a warning plus Discovered 0 MCP tools: [], reports itself ready with an empty tool id list, and the agent runs with no platform tools. Check that log line before assuming the tool path is live, see Letta Server Connection.
3. Agent resolution - In per_room mode each room gets its own Letta agent. The adapter resumes letta_agent_id from the room’s task-event metadata; if the agent is gone, it creates a new one and seeds it with the room’s history lines as prior context.
4. Turn composition - Letta takes one user message per call, so the seed, the rejoin note (“You have rejoined this room after 4h”, plus the previous topic), participants, and contacts updates ride inline as [System]: lines ahead of the triggering message.
5. Turn execution - The turn runs under turn_timeout_s. The adapter observes tool_call_message and tool_return_message events for execution reporting; it does not execute the platform tools itself.
6. Response - If the agent called the MCP send tool, the message is already on the platform. If it did not, auto_relay relays the assistant text and logs a warning, because an unused tool path would otherwise hide behind a successful reply.
7. Cleanup - Letta agents are kept by default so resume-by-id works. consolidate_memory_on_cleanup sends a final consolidation prompt so the agent writes key context to memory; delete_agents_on_cleanup deletes the agent instead.

LettaAdapter(config=None, history_converter=None, **features)

LettaAdapterConfig fields:

LettaAdapterConfig rejects unknown field names, so a typo fails construction rather than vanishing. The removed enable_task_events, enable_memory_tools, and enable_execution_reporting booleans are unknown names now: pass emit and capabilities to the adapter instead.

Most fields also read a LETTA_-prefixed environment variable, for example LETTA_BASE_URL, LETTA_MODEL, and LETTA_EMBEDDING. provider_key additionally accepts LETTA_API_KEY, matching Letta Cloud’s own naming. An explicit constructor argument always wins over the environment.

LettaMCPConfig fields:

Capabilities and event emission are keyword arguments on the adapter, not fields on the config:

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

Supported capabilities are MEMORY and CONTACTS, both opt-in. Supported emissions are TOOL_CALLS, TASK_EVENTS, and USAGE, and omitting emit resolves to all three, so the example above is the default spelled out. emit=() silences the adapter; naming any other Emit member raises BandConfigError at construction. Token usage is only available on the per_room path, since the shared-mode Conversations stream carries no aggregate usage.

Three fields configure the connection. Each also reads a LETTA_-prefixed environment variable, so wire your own settings in explicitly when you do not want that fallback.

Agent identity is not configured for per_room mode. The adapter records letta_agent_id in a task event and the history converter reads it back on the next session, so restarts resume the same Letta agent. Passing agent_id only takes effect in shared mode.

To run a self-hosted Letta server, start it detached, with a persistent volume and at least one model provider key:

$
docker run -d --name letta \
>
    -v ~/.letta/.persist/pgdata:/var/lib/postgresql/data \
>
    -p 8283:8283 \
>
    -e OPENAI_API_KEY="$OPENAI_API_KEY" \
>
    -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
>
    letta/letta:latest

Letta syncs each provider’s model list at startup, so a server started without a provider key exposes only the letta/letta-free handle and model="anthropic/claude-haiku-4-5" does not resolve. Add the key, restart the container, then check what the server exposes with curl -fsS http://localhost:8283/v1/models/. Without the volume, agents and MCP registrations are lost when the container is removed.

Reaching Band’s tools

MCP is the Python SDK’s only platform-tool transport: the Letta server calls back into a Band MCP server over HTTP. Letta validates that URL against its own SSRF guard, letta/helpers/url_validation.py, which rejects localhost, any literal private IP, and any hostname that resolves to a non-global IP. The Band MCP server therefore has to sit on a publicly resolvable host, whichever Letta you point at.

Two configurations work today:

1
mcp=LettaMCPConfig(
2
    mode="external",
3
    server_url="https://your-band-mcp.example.com/sse",
4
)

The defaults reach nothing. LettaMCPConfig() self-hosts on 127.0.0.1, and Letta rejects that registration with 422 Non-public IP not allowed: 127.0.0.1, so on_started raises and the agent never starts. The server_url default, http://localhost:8002/sse, is refused the same way as Blocked internal hostname: localhost.

Letta.letta.services.mcp_server_manager - WARNING - Error listing tools for MCP server mcp_server-...: Hostname resolves to non-public IP: 0.250.250.254
Letta.letta.services.mcp_server_manager - WARNING - Failed to auto-sync tools from MCP server band-...: Hostname resolves to non-public IP: 0.250.250.254. Server was created successfully but tools were not persisted.

Letta Cloud, an external Band MCP server on a public host, memory and contacts capabilities on, execution and usage events emitted, and a custom memory block:

1
import asyncio
2
import logging
3
import os
4
from dotenv import load_dotenv
5
from band import Agent, Capability, Emit
6
from band.adapters.letta import LettaAdapter, LettaAdapterConfig, LettaMCPConfig
7
from band.config import load_agent_config
8
9
logging.basicConfig(level=logging.INFO)
10
logger = logging.getLogger(__name__)
11
12
async def main():
13
    load_dotenv()
14
15
    agent_id, api_key = load_agent_config("my_agent")
16
17
    adapter = LettaAdapter(
18
        config=LettaAdapterConfig(
19
            provider_key=os.getenv("LETTA_API_KEY"),
20
            model="anthropic/claude-haiku-4-5",
21
            custom_section="You are a project assistant. Track decisions and owners.",
22
            memory_blocks=[
23
                {
24
                    "label": "project",
25
                    "value": "Current project: Q1 platform launch.",
26
                },
27
            ],
28
            mcp=LettaMCPConfig(
29
                mode="external",
30
                server_url=os.getenv(
31
                    "BAND_MCP_URL", "https://your-band-mcp.example.com/sse"
32
                ),
33
            ),
34
            turn_timeout_s=180.0,
35
        ),
36
        capabilities={Capability.MEMORY, Capability.CONTACTS},
37
        emit={Emit.TOOL_CALLS, Emit.TASK_EVENTS, Emit.USAGE},
38
    )
39
40
    agent = Agent.create(
41
        adapter=adapter,
42
        agent_id=agent_id,
43
        api_key=api_key,
44
        ws_url=os.getenv("BAND_WS_URL", "wss://app.band.ai/api/v1/socket/websocket"),
45
        rest_url=os.getenv("BAND_REST_URL", "https://app.band.ai"),
46
    )
47
48
    logger.info("Letta agent is running! Press Ctrl+C to stop.")
49
    await agent.run()
50
51
if __name__ == "__main__":
52
    asyncio.run(main())