Letta Agent SDK reference

Use this reference after the Quickstart 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 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.