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)

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?: "default" | "acceptEdits" | "plan" | "bypassPermissions";
  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;
}

Supporting types:

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

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