# letta-ai/letta-agent-sdk architecture

> Architecture diagram of the GitHub repository letta-ai/letta-agent-sdk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/letta-ai/letta-agent-sdk
- Repository: https://github.com/letta-ai/letta-agent-sdk

## Overview

Letta Agent SDK exposes a shared client for creating stateful agents, resuming sessions, and running one-shot queries across cloud, local App Server, and remote App Server backends. The central workflow initializes a backend-specific session, sends turns, and streams results; distinct branches cover management, repositories, skills, tools, and cloud execution. Edges reflect README behavior and SOURCE INDEX references or shown calls; unsampled implementation details are omitted where wiring is uncertain.

Main entry points: [`src/client-base.ts`](https://github.com/letta-ai/letta-agent-sdk/blob/main/src/client-base.ts) (Agent client), [`src/cloud-session.ts`](https://github.com/letta-ai/letta-agent-sdk/blob/main/src/cloud-session.ts) (Cloud session), [`src/app-server-session.ts`](https://github.com/letta-ai/letta-agent-sdk/blob/main/src/app-server-session.ts) (Session lifecycle), [`src/management.ts`](https://github.com/letta-ai/letta-agent-sdk/blob/main/src/management.ts) (Agent management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client workflows"]
  node_client["Agent client<br/>[client-base.ts]"]
  node_query["One-shot query<br/>[query.ts]"]
  node_agentcreate["Agent creation<br/>[agent-creation.ts]"]
end

subgraph group_sessions["Session runtime"]
  node_session["Session lifecycle"]
  node_remote_core["Remote session core"]
  node_turn["Turn coordination"]
  node_protocol["Session protocol"]
  node_transcript["Transcript accumulation"]
end

subgraph group_backends["Backend connections"]
  node_cloud_session["Cloud session<br/>[cloud-session.ts]"]
  node_cloud_api["Cloud API client<br/>[cloud-client.ts]"]
  node_local_session["Local App Server session"]
  node_local_server["Local App Server"]
end

subgraph group_capabilities["Agent capabilities"]
  node_management["Agent management<br/>[management.ts]"]
  node_management_transport["App Server management"]
  node_cloud_management["Cloud management"]
  node_repositories["Repositories<br/>[repositories.ts]"]
  node_skills["Skill loading<br/>[skill-loading.ts]"]
  node_mcp["MCP tools<br/>[mcp-runtime.ts]"]
  node_computers["Connected computers<br/>[computers.ts]"]
  node_sandbox["Cloud sandbox<br/>[cloud-sandbox.ts]"]
end

node_user(("SDK caller"))
node_cloud[("Letta Cloud")]
node_appserver["Letta App Server"]
node_assistant(("Agent assistant"))

node_user -->|"creates or resumes"| node_client
node_client -->|"creates agent"| node_agentcreate
node_client -->|"opens cloud session"| node_cloud_session
node_client -->|"opens local session"| node_local_session
node_client -->|"runs query"| node_query
node_query -->|"streams turn"| node_session
node_session -->|"sends messages"| node_assistant
node_session -->|"connects tools"| node_mcp
node_session -->|"builds creation body"| node_agentcreate
node_cloud_session -->|"uses API client"| node_cloud_api
node_cloud_session -->|"opens runtime transport"| node_appserver
node_local_session -->|"connects session"| node_appserver
node_client -->|"starts server"| node_local_server
node_remote_core -->|"maps protocol data"| node_protocol
node_remote_core -->|"coordinates turns"| node_turn
node_turn -->|"uses protocol helpers"| node_protocol
node_transcript -->|"parses stream messages"| node_protocol
node_client -->|"exposes management"| node_management
node_management -->|"dispatches operations"| node_management_transport
node_management -->|"cloud transport"| node_cloud_management
node_client -->|"provides repository access"| node_repositories
node_client -->|"resolves skills"| node_skills
node_agentcreate -->|"seeds skill content"| node_skills
node_cloud_session -->|"resolves skills"| node_skills
node_client -->|"computer access"| node_computers
node_cloud_session -->|"manages sandbox"| node_sandbox
node_cloud_api -->|"API requests"| node_cloud
node_cloud_management -->|"manages cloud records"| node_cloud
node_computers -->|"remote connection"| node_appserver

click node_client "https://github.com/letta-ai/letta-agent-sdk/blob/main/src/client-base.ts"
click node_query "https://github.com/letta-ai/letta-agent-sdk/blob/main/src/query.ts"
click node_agentcreate "https://github.com/letta-ai/letta-agent-sdk/blob/main/src/agent-creation.ts"
click node_session "https://github.com/letta-ai/letta-agent-sdk/blob/main/src/app-server-session.ts"
click node_remote_core "https://github.com/letta-ai/letta-agent-sdk/blob/main/src/remote-client-session-core.ts"
click node_turn "https://github.com/letta-ai/letta-agent-sdk/blob/main/src/remote-turn-coordinator.ts"
click node_protocol "https://github.com/letta-ai/letta-agent-sdk/blob/main/src/remote-session-protocol.ts"
click node_transcript "https://github.com/letta-ai/letta-agent-sdk/blob/main/src/transcript-accumulator.ts"
click node_cloud_session "https://github.com/letta-ai/letta-agent-sdk/blob/main/src/cloud-session.ts"
click node_cloud_api "https://github.com/letta-ai/letta-agent-sdk/blob/main/src/cloud-client.ts"
click node_local_session "https://github.com/letta-ai/letta-agent-sdk/blob/main/src/local-app-server-session.ts"
click node_local_server "https://github.com/letta-ai/letta-agent-sdk/blob/main/src/local-app-server.ts"
click node_management "https://github.com/letta-ai/letta-agent-sdk/blob/main/src/management.ts"
click node_management_transport "https://github.com/letta-ai/letta-agent-sdk/blob/main/src/app-server-management.ts"
click node_cloud_management "https://github.com/letta-ai/letta-agent-sdk/blob/main/src/cloud-management.ts"
click node_repositories "https://github.com/letta-ai/letta-agent-sdk/blob/main/src/repositories.ts"
click node_skills "https://github.com/letta-ai/letta-agent-sdk/blob/main/src/skill-loading.ts"
click node_mcp "https://github.com/letta-ai/letta-agent-sdk/blob/main/src/mcp-runtime.ts"
click node_computers "https://github.com/letta-ai/letta-agent-sdk/blob/main/src/computers.ts"
click node_sandbox "https://github.com/letta-ai/letta-agent-sdk/blob/main/src/cloud-sandbox.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_client,node_query,node_agentcreate toneBlue
class node_session,node_remote_core,node_turn,node_protocol,node_transcript,node_cloud toneAmber
class node_cloud_session,node_cloud_api,node_local_session,node_local_server,node_appserver toneMint
class node_management,node_management_transport,node_cloud_management,node_repositories,node_skills,node_mcp,node_computers,node_sandbox toneRose
class node_user,node_assistant toneIndigo
```

## Components

### Client workflows

- [Agent client](https://github.com/letta-ai/letta-agent-sdk/blob/main/src/client-base.ts): `src/client-base.ts`
- [One-shot query](https://github.com/letta-ai/letta-agent-sdk/blob/main/src/query.ts): `src/query.ts`
- [Agent creation](https://github.com/letta-ai/letta-agent-sdk/blob/main/src/agent-creation.ts): `src/agent-creation.ts`

### Session runtime

- [Session lifecycle](https://github.com/letta-ai/letta-agent-sdk/blob/main/src/app-server-session.ts): `src/app-server-session.ts`
- [Remote session core](https://github.com/letta-ai/letta-agent-sdk/blob/main/src/remote-client-session-core.ts): `src/remote-client-session-core.ts`
- [Turn coordination](https://github.com/letta-ai/letta-agent-sdk/blob/main/src/remote-turn-coordinator.ts): `src/remote-turn-coordinator.ts`
- [Session protocol](https://github.com/letta-ai/letta-agent-sdk/blob/main/src/remote-session-protocol.ts): `src/remote-session-protocol.ts`
- [Transcript accumulation](https://github.com/letta-ai/letta-agent-sdk/blob/main/src/transcript-accumulator.ts): `src/transcript-accumulator.ts`

### Backend connections

- [Cloud session](https://github.com/letta-ai/letta-agent-sdk/blob/main/src/cloud-session.ts): `src/cloud-session.ts`
- [Cloud API client](https://github.com/letta-ai/letta-agent-sdk/blob/main/src/cloud-client.ts): `src/cloud-client.ts`
- [Local App Server session](https://github.com/letta-ai/letta-agent-sdk/blob/main/src/local-app-server-session.ts): `src/local-app-server-session.ts`
- [Local App Server](https://github.com/letta-ai/letta-agent-sdk/blob/main/src/local-app-server.ts): `src/local-app-server.ts`

### Agent capabilities

- [Agent management](https://github.com/letta-ai/letta-agent-sdk/blob/main/src/management.ts): `src/management.ts`
- [App Server management](https://github.com/letta-ai/letta-agent-sdk/blob/main/src/app-server-management.ts): `src/app-server-management.ts`
- [Cloud management](https://github.com/letta-ai/letta-agent-sdk/blob/main/src/cloud-management.ts): `src/cloud-management.ts`
- [Repositories](https://github.com/letta-ai/letta-agent-sdk/blob/main/src/repositories.ts): `src/repositories.ts`
- [Skill loading](https://github.com/letta-ai/letta-agent-sdk/blob/main/src/skill-loading.ts): `src/skill-loading.ts`
- [MCP tools](https://github.com/letta-ai/letta-agent-sdk/blob/main/src/mcp-runtime.ts): `src/mcp-runtime.ts`
- [Connected computers](https://github.com/letta-ai/letta-agent-sdk/blob/main/src/computers.ts): `src/computers.ts`
- [Cloud sandbox](https://github.com/letta-ai/letta-agent-sdk/blob/main/src/cloud-sandbox.ts): `src/cloud-sandbox.ts`

### Other components

- **SDK caller**
- **Letta Cloud**
- **Letta App Server**
- **Agent assistant**

## Connections

- SDK caller → Agent client: creates or resumes (evidence: `README.md`)
- Agent client → Agent creation: creates agent (evidence: `src/client-base.ts`)
- Agent client → Cloud session: opens cloud session (evidence: `src/client-base.ts`)
- Agent client → Local App Server session: opens local session (evidence: `src/client.ts`)
- Agent client → One-shot query: runs query (evidence: `README.md`)
- One-shot query → Session lifecycle: streams turn (evidence: `src/query.ts`)
- Session lifecycle → Agent assistant: sends messages (evidence: `README.md`)
- Session lifecycle → MCP tools: connects tools (evidence: `src/app-server-session.ts`)
- Session lifecycle → Agent creation: builds creation body (evidence: `src/app-server-session.ts`)
- Cloud session → Cloud API client: uses API client (evidence: `src/cloud-session.ts`)
- Cloud session → Letta App Server: opens runtime transport (evidence: `src/cloud-session.ts`)
- Local App Server session → Letta App Server: connects session (evidence: `src/local-app-server-session.ts`)
- Agent client → Local App Server: starts server (evidence: `src/client.ts`)
- Remote session core → Session protocol: maps protocol data (evidence: `src/remote-client-session-core.ts`)
- Remote session core → Turn coordination: coordinates turns (evidence: `src/remote-client-session-core.ts`)
- Turn coordination → Session protocol: uses protocol helpers (evidence: `src/remote-turn-coordinator.ts`)
- Transcript accumulation → Session protocol: parses stream messages (evidence: `src/transcript-accumulator.ts`)
- Agent client → Agent management: exposes management (evidence: `src/client-base.ts`)
- Agent management → App Server management: dispatches operations (evidence: `src/app-server-management.ts`)
- Agent management → Cloud management: cloud transport (evidence: `src/client-base.ts`)
- Agent client → Repositories: provides repository access (evidence: `src/client-base.ts`)
- Agent client → Skill loading: resolves skills (evidence: `src/client-base.ts`)
- Agent creation → Skill loading: seeds skill content (evidence: `src/agent-creation.ts`)
- Cloud session → Skill loading: resolves skills (evidence: `src/cloud-session.ts`)
- Agent client → Connected computers: computer access (evidence: `src/client-base.ts`)
- Cloud session → Cloud sandbox: manages sandbox (evidence: `src/cloud-session.ts`)
- Cloud API client → Letta Cloud: API requests (evidence: `src/cloud-client.ts`)
- Cloud management → Letta Cloud: manages cloud records (evidence: `src/cloud-management.ts`)
- Connected computers → Letta App Server: remote connection (evidence: `src/computers.ts`)