---
title: Letta Agent SDK reference | Letta Docs
description: Client methods, session interface, and option types for the Letta Agent SDK
---

Use this reference after the [Quickstart](/agent-sdk/quickstart/index.md) when you need method names, session shape, or option interfaces.

### Client methods

| Method                                     | Description                                                                                         |
| ------------------------------------------ | --------------------------------------------------------------------------------------------------- |
| `client.createAgent(options?)`             | Create a new persistent agent                                                                       |
| `client.createSession(agentId?, options?)` | Start a new conversation (uses default agent if no ID provided)                                     |
| `client.resumeSession(id, options?)`       | Resume session (pass `agent-xxx` for default conversation, or `conv-xxx` for specific conversation) |
| `client.prompt(message, agentId?)`         | One-shot query (uses default agent if no ID provided)                                               |

### Cloud repository client

`client.repositories` manages hosted repositories for clients configured with `backend: "cloud"`. Accessing this property on a local or remote client throws an error.

| Method                                                        | Returns                                 | Description                               |
| ------------------------------------------------------------- | --------------------------------------- | ----------------------------------------- |
| `client.repositories.create(params)`                          | `Promise<Repository>`                   | Create a hosted repository                |
| `client.repositories.list(params?)`                           | `Promise<ListRepositoriesResult>`       | List repositories using offset pagination |
| `client.repositories.get(repositoryId)`                       | `Promise<Repository>`                   | Get a repository by ID                    |
| `client.repositories.delete(repositoryId)`                    | `Promise<void>`                         | Soft-delete a repository                  |
| `client.repositories.files.list(repositoryId, params?)`       | `Promise<ListRepositoryFilesResult>`    | List files and directories                |
| `client.repositories.files.create(repositoryId, params)`      | `Promise<RepositoryFileMutationResult>` | Create a text file                        |
| `client.repositories.files.read(repositoryId, params)`        | `Promise<RepositoryFile>`               | Read a file at the current or a given ref |
| `client.repositories.files.update(repositoryId, params)`      | `Promise<RepositoryFileMutationResult>` | Update content or rename a file           |
| `client.repositories.files.delete(repositoryId, params)`      | `Promise<DeleteRepositoryFileResult>`   | Delete a file                             |
| `client.repositories.versions.list(repositoryId, params?)`    | `Promise<RepositoryVersion[]>`          | List repository or file history           |
| `client.repositories.versions.get(repositoryId, sha, params)` | `Promise<RepositoryFile>`               | Read one file at a commit                 |

See [Cloud repositories](/agent-sdk/repositories/index.md) for an end-to-end example, session lifecycle behavior, permissions, and limits.

### Session interface

```
interface Session {
  send(message: string): Promise<void>;
  stream(): AsyncGenerator<SDKMessage>;
  close(): void;


  listMessages(options?: ListMessagesOptions): Promise<ListMessagesResult>;


  readonly agentId: string | null;
  readonly conversationId: string | null;
  readonly sessionId: string | null;
}
```

### CreateAgentOptions

Options for `client.createAgent()` - these configure the persistent agent:

```
interface CreateAgentOptions {
  model?: string;
  reasoningEffort?: ReasoningEffort;
  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
  skillSources?: SkillSource[];
  systemInfoReminder?: boolean;
  dreaming?: DreamingOptions;
}
```

### CreateSessionOptions

Options for `client.createSession()` and `client.resumeSession()` - these configure runtime behavior:

```
interface CreateSessionOptions {
  // Model configuration
  model?: string;
  reasoningEffort?: ReasoningEffort;


  // System prompt preset (updates the agent)
  systemPrompt?: SystemPromptPreset;


  // Tool restrictions
  allowedTools?: string[];
  disallowedTools?: string[];
  permissionMode?: "standard" | "acceptEdits" | "unrestricted";
  canUseTool?: (
    toolName: string,
    toolInput: object,
  ) => Promise<CanUseToolResponse>;


  // File system
  cwd?: string;


  // Runtime/harness controls
  skillSources?: SkillSource[]; // [] => --no-skills
  systemInfoReminder?: boolean; // false => --no-system-info-reminder
  dreaming?: DreamingOptions;


  // Cloud repository resources
  resources?: RepositoryResource[];
}
```

Supporting types:

```
type SkillSource = "bundled" | "global" | "agent" | "project";


interface DreamingOptions {
  trigger?: "off" | "step-count" | "compaction-event";
  behavior?: "reminder" | "auto-launch";
  stepCount?: number;
}
```

### Repository types

```
interface Repository {
  id: string;
  name: string;
  createdAt: string;
  updatedAt: string;
}


interface CreateRepositoryParams {
  name: string;
}


interface ListRepositoriesParams {
  limit?: number;
  offset?: number;
}


interface ListRepositoriesResult {
  repositories: Repository[];
  hasNextPage: boolean;
}


interface RepositoryResource {
  type: "repository";
  repositoryId: string;
}


interface RepositoryFileEntry {
  path: string;
  type: "file" | "directory";
}


interface ListRepositoryFilesParams {
  pathPrefix?: string;
  depth?: number;
  ref?: string;
}


interface ListRepositoryFilesResult {
  files: RepositoryFileEntry[];
  ref: string;
}


interface CreateRepositoryFileParams {
  path: string;
  content: string;
}


interface RepositoryFile {
  path: string;
  content: string;
  contentSha256: string;
  ref?: string;
}


interface UpdateRepositoryFileParams {
  path: string;
  content?: string;
  newPath?: string;
  precondition?: {
    contentSha256: string;
  };
}


interface RepositoryFileMutationResult {
  path: string;
  contentSha256: string;
  commitSha: string;
}


interface DeleteRepositoryFileParams {
  path: string;
}


interface DeleteRepositoryFileResult {
  success: boolean;
  commitSha: string;
}


interface RepositoryVersion {
  sha: string;
  message: string;
  timestamp: string;
  author_name: string | null;
}


interface ListRepositoryVersionsParams {
  path?: string;
  limit?: number;
}


interface GetRepositoryVersionParams {
  path: string;
}
```

`files.read()` accepts `{ path: string; ref?: string }`. All types above are exported from `@letta-ai/letta-agent-sdk`.