@letta-ai/letta-client 1.0.0-alpha.14 → 1.0.0-alpha.16

package/src/resources/agents/messages.ts

@@ -6,7 +6,7 @@ import * as ToolsAPI from '../tools';
 import * as AgentsAPI from './agents';
 import * as RunsAPI from '../runs/runs';
 import { APIPromise } from '../../core/api-promise';
-import { ArrayPage, type ArrayPageParams, PagePromise } from '../../core/pagination';
+import { ArrayPage, type ArrayPageParams, ObjectPage, PagePromise } from '../../core/pagination';
 import { Stream } from '../../core/streaming';
 import { buildHeaders } from '../../internal/headers';
 import { RequestOptions } from '../../internal/request-options';
@@ -67,9 +67,44 @@ export class Messages extends APIResource {
   /**
    * Process a user message and return the agent's response. This endpoint accepts a
    * message from a user and processes it through the agent.
+   *
+   * The response format is controlled by the `streaming` field in the request body:
+   *
+   * - If `streaming=false` (default): Returns a complete LettaResponse with all
+   *   messages
+   * - If `streaming=true`: Returns a Server-Sent Events (SSE) stream
+   *
+   * Additional streaming options (only used when streaming=true):
+   *
+   * - `stream_tokens`: Stream individual tokens instead of complete steps
+   * - `include_pings`: Include keepalive pings to prevent connection timeouts
+   * - `background`: Process the request in the background
    */
-  send(agentID: string, body: MessageSendParams, options?: RequestOptions): APIPromise<LettaResponse> {
-    return this._client.post(path`/v1/agents/${agentID}/messages`, { body, ...options });
+  send(
+    agentID: string,
+    body: MessageSendParamsNonStreaming,
+    options?: RequestOptions,
+  ): APIPromise<LettaResponse>;
+  send(
+    agentID: string,
+    body: MessageSendParamsStreaming,
+    options?: RequestOptions,
+  ): APIPromise<Stream<LettaStreamingResponse>>;
+  send(
+    agentID: string,
+    body: MessageSendParamsBase,
+    options?: RequestOptions,
+  ): APIPromise<Stream<LettaStreamingResponse> | LettaResponse>;
+  send(
+    agentID: string,
+    body: MessageSendParams,
+    options?: RequestOptions,
+  ): APIPromise<LettaResponse> | APIPromise<Stream<LettaStreamingResponse>> {
+    return this._client.post(path`/v1/agents/${agentID}/messages`, {
+      body,
+      ...options,
+      stream: body.streaming ?? false,
+    }) as APIPromise<LettaResponse> | APIPromise<Stream<LettaStreamingResponse>>;
   }
 
   /**
@@ -114,6 +149,10 @@ export class Messages extends APIResource {
 
 export type LettaMessageUnionsArrayPage = ArrayPage<LettaMessageUnion>;
 
+export type RunsArrayPage = ArrayPage<Run>;
+
+export type MessagesObjectPage = ObjectPage<Message>;
+
 /**
  * Input to approve or deny a tool call request
  */
@@ -133,6 +172,11 @@ export interface ApprovalCreate {
    */
   approve?: boolean | null;
 
+  /**
+   * The multi-agent group that the message was sent in
+   */
+  group_id?: string | null;
+
   /**
    * @deprecated An optional explanation for the provided approval status
    */
@@ -330,6 +374,36 @@ export interface AssistantMessage {
   step_id?: string | null;
 }
 
+/**
+ * A message for notifying the developer that an event that has occured (e.g. a
+ * compaction). Events are NOT part of the context window.
+ */
+export interface EventMessage {
+  id: string;
+
+  date: string;
+
+  event_data: { [key: string]: unknown };
+
+  event_type: 'compaction';
+
+  is_err?: boolean | null;
+
+  message_type?: 'event';
+
+  name?: string | null;
+
+  otid?: string | null;
+
+  run_id?: string | null;
+
+  sender_id?: string | null;
+
+  seq_id?: number | null;
+
+  step_id?: string | null;
+}
+
 /**
  * Representation of an agent's internal reasoning where reasoning content has been
  * hidden from the response.
@@ -487,14 +561,11 @@ export type LettaMessageUnion =
   | ToolsAPI.ToolReturnMessage
   | AssistantMessage
   | ApprovalRequestMessage
-  | ApprovalResponseMessage;
+  | ApprovalResponseMessage
+  | SummaryMessage
+  | EventMessage;
 
 export interface LettaRequest {
-  /**
-   * The messages to be sent to the agent.
-   */
-  messages: Array<AgentsAPI.MessageCreate | ApprovalCreate>;
-
   /**
    * @deprecated The name of the message argument in the designated message tool.
    * Still supported for legacy agent types, but deprecated for letta_v1_agent
@@ -520,11 +591,34 @@ export interface LettaRequest {
    */
   include_return_message_types?: Array<MessageType> | null;
 
+  /**
+   * Syntactic sugar for a single user message. Equivalent to messages=[{'role':
+   * 'user', 'content': input}].
+   */
+  input?:
+    | string
+    | Array<
+        | TextContent
+        | ImageContent
+        | ToolCallContent
+        | ToolReturnContent
+        | ReasoningContent
+        | RedactedReasoningContent
+        | OmittedReasoningContent
+        | LettaRequest.SummarizedReasoningContent
+      >
+    | null;
+
   /**
    * Maximum number of steps the agent should take to process the request.
    */
   max_steps?: number;
 
+  /**
+   * The messages to be sent to the agent.
+   */
+  messages?: Array<AgentsAPI.MessageCreate | ApprovalCreate> | null;
+
   /**
    * @deprecated Whether the server should parse specific tool call arguments
    * (default `send_message`) as `AssistantMessage` objects. Still supported for
@@ -533,6 +627,47 @@ export interface LettaRequest {
   use_assistant_message?: boolean;
 }
 
+export namespace LettaRequest {
+  /**
+   * The style of reasoning content returned by the OpenAI Responses API
+   */
+  export interface SummarizedReasoningContent {
+    /**
+     * The unique identifier for this reasoning step.
+     */
+    id: string;
+
+    /**
+     * Summaries of the reasoning content.
+     */
+    summary: Array<SummarizedReasoningContent.Summary>;
+
+    /**
+     * The encrypted reasoning content.
+     */
+    encrypted_content?: string;
+
+    /**
+     * Indicates this is a summarized reasoning step.
+     */
+    type?: 'summarized_reasoning';
+  }
+
+  export namespace SummarizedReasoningContent {
+    export interface Summary {
+      /**
+       * The index of the summary part.
+       */
+      index: number;
+
+      /**
+       * The text of the summary part.
+       */
+      text: string;
+    }
+  }
+}
+
 /**
  * Response object from an agent interaction, consisting of the new messages
  * generated by the agent and usage statistics. The type of the returned messages
@@ -609,11 +744,6 @@ export namespace LettaResponse {
 }
 
 export interface LettaStreamingRequest {
-  /**
-   * The messages to be sent to the agent.
-   */
-  messages: Array<AgentsAPI.MessageCreate | ApprovalCreate>;
-
   /**
    * @deprecated The name of the message argument in the designated message tool.
    * Still supported for legacy agent types, but deprecated for letta_v1_agent
@@ -628,7 +758,8 @@ export interface LettaStreamingRequest {
   assistant_message_tool_name?: string;
 
   /**
-   * Whether to process the request in the background.
+   * Whether to process the request in the background (only used when
+   * streaming=true).
    */
   background?: boolean;
 
@@ -640,7 +771,7 @@ export interface LettaStreamingRequest {
 
   /**
    * Whether to include periodic keepalive ping messages in the stream to prevent
-   * connection timeouts.
+   * connection timeouts (only used when streaming=true).
    */
   include_pings?: boolean;
 
@@ -650,17 +781,46 @@ export interface LettaStreamingRequest {
    */
   include_return_message_types?: Array<MessageType> | null;
 
+  /**
+   * Syntactic sugar for a single user message. Equivalent to messages=[{'role':
+   * 'user', 'content': input}].
+   */
+  input?:
+    | string
+    | Array<
+        | TextContent
+        | ImageContent
+        | ToolCallContent
+        | ToolReturnContent
+        | ReasoningContent
+        | RedactedReasoningContent
+        | OmittedReasoningContent
+        | LettaStreamingRequest.SummarizedReasoningContent
+      >
+    | null;
+
   /**
    * Maximum number of steps the agent should take to process the request.
    */
   max_steps?: number;
 
+  /**
+   * The messages to be sent to the agent.
+   */
+  messages?: Array<AgentsAPI.MessageCreate | ApprovalCreate> | null;
+
   /**
    * Flag to determine if individual tokens should be streamed, rather than streaming
-   * per step.
+   * per step (only used when streaming=true).
    */
   stream_tokens?: boolean;
 
+  /**
+   * If True, returns a streaming response (Server-Sent Events). If False (default),
+   * returns a complete response.
+   */
+  streaming?: boolean;
+
   /**
    * @deprecated Whether the server should parse specific tool call arguments
    * (default `send_message`) as `AssistantMessage` objects. Still supported for
@@ -669,6 +829,47 @@ export interface LettaStreamingRequest {
   use_assistant_message?: boolean;
 }
 
+export namespace LettaStreamingRequest {
+  /**
+   * The style of reasoning content returned by the OpenAI Responses API
+   */
+  export interface SummarizedReasoningContent {
+    /**
+     * The unique identifier for this reasoning step.
+     */
+    id: string;
+
+    /**
+     * Summaries of the reasoning content.
+     */
+    summary: Array<SummarizedReasoningContent.Summary>;
+
+    /**
+     * The encrypted reasoning content.
+     */
+    encrypted_content?: string;
+
+    /**
+     * Indicates this is a summarized reasoning step.
+     */
+    type?: 'summarized_reasoning';
+  }
+
+  export namespace SummarizedReasoningContent {
+    export interface Summary {
+      /**
+       * The index of the summary part.
+       */
+      index: number;
+
+      /**
+       * The text of the summary part.
+       */
+      text: string;
+    }
+  }
+}
+
 /**
  * Streaming response type for Server-Sent Events (SSE) endpoints. Each event in
  * the stream will be one of these types.
@@ -778,14 +979,14 @@ export type LettaUserMessageContentUnion = TextContent | ImageContent;
  */
 export interface Message {
   /**
-   * The role of the participant.
+   * The human-friendly ID of the Message
    */
-  role: MessageRole;
+  id: string;
 
   /**
-   * The human-friendly ID of the Message
+   * The role of the participant.
    */
-  id?: string;
+  role: MessageRole;
 
   /**
    * The unique identifier of the agent.
@@ -1174,14 +1375,14 @@ export interface RedactedReasoningContent {
  */
 export interface Run {
   /**
-   * The unique identifier of the agent associated with the run.
+   * The human-friendly ID of the Run
    */
-  agent_id: string;
+  id: string;
 
   /**
-   * The human-friendly ID of the Run
+   * The unique identifier of the agent associated with the run.
    */
-  id?: string;
+  agent_id: string;
 
   /**
    * Whether the run was created in background mode.
@@ -1283,6 +1484,34 @@ export namespace Run {
   }
 }
 
+/**
+ * A message representing a summary of the conversation. Sent to the LLM as a user
+ * or system message depending on the provider.
+ */
+export interface SummaryMessage {
+  id: string;
+
+  date: string;
+
+  summary: string;
+
+  is_err?: boolean | null;
+
+  message_type?: 'summary';
+
+  name?: string | null;
+
+  otid?: string | null;
+
+  run_id?: string | null;
+
+  sender_id?: string | null;
+
+  seq_id?: number | null;
+
+  step_id?: string | null;
+}
+
 /**
  * A message generated by the system. Never streamed back on a response, only used
  * for cursor pagination.
@@ -1557,7 +1786,9 @@ export type MessageModifyResponse =
   | ToolsAPI.ToolReturnMessage
   | AssistantMessage
   | ApprovalRequestMessage
-  | ApprovalResponseMessage;
+  | ApprovalResponseMessage
+  | SummaryMessage
+  | EventMessage;
 
 export interface MessageListParams extends ArrayPageParams {
   /**
@@ -1680,12 +1911,9 @@ export interface MessageResetParams {
   add_default_initial_messages?: boolean;
 }
 
-export interface MessageSendParams {
-  /**
-   * The messages to be sent to the agent.
-   */
-  messages: Array<AgentsAPI.MessageCreate | ApprovalCreate>;
+export type MessageSendParams = MessageSendParamsNonStreaming | MessageSendParamsStreaming;
 
+export interface MessageSendParamsBase {
   /**
    * @deprecated The name of the message argument in the designated message tool.
    * Still supported for legacy agent types, but deprecated for letta_v1_agent
@@ -1699,23 +1927,70 @@ export interface MessageSendParams {
    */
   assistant_message_tool_name?: string;
 
+  /**
+   * Whether to process the request in the background (only used when
+   * streaming=true).
+   */
+  background?: boolean;
+
   /**
    * @deprecated If set to True, enables reasoning before responses or tool calls
    * from the agent.
    */
   enable_thinking?: string;
 
+  /**
+   * Whether to include periodic keepalive ping messages in the stream to prevent
+   * connection timeouts (only used when streaming=true).
+   */
+  include_pings?: boolean;
+
   /**
    * Only return specified message types in the response. If `None` (default) returns
    * all messages.
    */
   include_return_message_types?: Array<MessageType> | null;
 
+  /**
+   * Syntactic sugar for a single user message. Equivalent to messages=[{'role':
+   * 'user', 'content': input}].
+   */
+  input?:
+    | string
+    | Array<
+        | TextContent
+        | ImageContent
+        | ToolCallContent
+        | ToolReturnContent
+        | ReasoningContent
+        | RedactedReasoningContent
+        | OmittedReasoningContent
+        | MessageSendParams.SummarizedReasoningContent
+      >
+    | null;
+
   /**
    * Maximum number of steps the agent should take to process the request.
    */
   max_steps?: number;
 
+  /**
+   * The messages to be sent to the agent.
+   */
+  messages?: Array<AgentsAPI.MessageCreate | ApprovalCreate> | null;
+
+  /**
+   * Flag to determine if individual tokens should be streamed, rather than streaming
+   * per step (only used when streaming=true).
+   */
+  stream_tokens?: boolean;
+
+  /**
+   * If True, returns a streaming response (Server-Sent Events). If False (default),
+   * returns a complete response.
+   */
+  streaming?: boolean;
+
   /**
    * @deprecated Whether the server should parse specific tool call arguments
    * (default `send_message`) as `AssistantMessage` objects. Still supported for
@@ -1724,12 +1999,67 @@ export interface MessageSendParams {
   use_assistant_message?: boolean;
 }
 
-export interface MessageSendAsyncParams {
+export namespace MessageSendParams {
   /**
-   * The messages to be sent to the agent.
+   * The style of reasoning content returned by the OpenAI Responses API
    */
-  messages: Array<AgentsAPI.MessageCreate | ApprovalCreate>;
+  export interface SummarizedReasoningContent {
+    /**
+     * The unique identifier for this reasoning step.
+     */
+    id: string;
 
+    /**
+     * Summaries of the reasoning content.
+     */
+    summary: Array<SummarizedReasoningContent.Summary>;
+
+    /**
+     * The encrypted reasoning content.
+     */
+    encrypted_content?: string;
+
+    /**
+     * Indicates this is a summarized reasoning step.
+     */
+    type?: 'summarized_reasoning';
+  }
+
+  export namespace SummarizedReasoningContent {
+    export interface Summary {
+      /**
+       * The index of the summary part.
+       */
+      index: number;
+
+      /**
+       * The text of the summary part.
+       */
+      text: string;
+    }
+  }
+
+  export type MessageSendParamsNonStreaming = MessagesAPI.MessageSendParamsNonStreaming;
+  export type MessageSendParamsStreaming = MessagesAPI.MessageSendParamsStreaming;
+}
+
+export interface MessageSendParamsNonStreaming extends MessageSendParamsBase {
+  /**
+   * If True, returns a streaming response (Server-Sent Events). If False (default),
+   * returns a complete response.
+   */
+  streaming?: false;
+}
+
+export interface MessageSendParamsStreaming extends MessageSendParamsBase {
+  /**
+   * If True, returns a streaming response (Server-Sent Events). If False (default),
+   * returns a complete response.
+   */
+  streaming: true;
+}
+
+export interface MessageSendAsyncParams {
   /**
    * @deprecated The name of the message argument in the designated message tool.
    * Still supported for legacy agent types, but deprecated for letta_v1_agent
@@ -1760,11 +2090,34 @@ export interface MessageSendAsyncParams {
    */
   include_return_message_types?: Array<MessageType> | null;
 
+  /**
+   * Syntactic sugar for a single user message. Equivalent to messages=[{'role':
+   * 'user', 'content': input}].
+   */
+  input?:
+    | string
+    | Array<
+        | TextContent
+        | ImageContent
+        | ToolCallContent
+        | ToolReturnContent
+        | ReasoningContent
+        | RedactedReasoningContent
+        | OmittedReasoningContent
+        | MessageSendAsyncParams.SummarizedReasoningContent
+      >
+    | null;
+
   /**
    * Maximum number of steps the agent should take to process the request.
    */
   max_steps?: number;
 
+  /**
+   * The messages to be sent to the agent.
+   */
+  messages?: Array<AgentsAPI.MessageCreate | ApprovalCreate> | null;
+
   /**
    * @deprecated Whether the server should parse specific tool call arguments
    * (default `send_message`) as `AssistantMessage` objects. Still supported for
@@ -1773,12 +2126,48 @@ export interface MessageSendAsyncParams {
   use_assistant_message?: boolean;
 }
 
-export interface MessageStreamParams {
+export namespace MessageSendAsyncParams {
   /**
-   * The messages to be sent to the agent.
+   * The style of reasoning content returned by the OpenAI Responses API
    */
-  messages: Array<AgentsAPI.MessageCreate | ApprovalCreate>;
+  export interface SummarizedReasoningContent {
+    /**
+     * The unique identifier for this reasoning step.
+     */
+    id: string;
 
+    /**
+     * Summaries of the reasoning content.
+     */
+    summary: Array<SummarizedReasoningContent.Summary>;
+
+    /**
+     * The encrypted reasoning content.
+     */
+    encrypted_content?: string;
+
+    /**
+     * Indicates this is a summarized reasoning step.
+     */
+    type?: 'summarized_reasoning';
+  }
+
+  export namespace SummarizedReasoningContent {
+    export interface Summary {
+      /**
+       * The index of the summary part.
+       */
+      index: number;
+
+      /**
+       * The text of the summary part.
+       */
+      text: string;
+    }
+  }
+}
+
+export interface MessageStreamParams {
   /**
    * @deprecated The name of the message argument in the designated message tool.
    * Still supported for legacy agent types, but deprecated for letta_v1_agent
@@ -1793,7 +2182,8 @@ export interface MessageStreamParams {
   assistant_message_tool_name?: string;
 
   /**
-   * Whether to process the request in the background.
+   * Whether to process the request in the background (only used when
+   * streaming=true).
    */
   background?: boolean;
 
@@ -1805,7 +2195,7 @@ export interface MessageStreamParams {
 
   /**
    * Whether to include periodic keepalive ping messages in the stream to prevent
-   * connection timeouts.
+   * connection timeouts (only used when streaming=true).
    */
   include_pings?: boolean;
 
@@ -1815,17 +2205,46 @@ export interface MessageStreamParams {
    */
   include_return_message_types?: Array<MessageType> | null;
 
+  /**
+   * Syntactic sugar for a single user message. Equivalent to messages=[{'role':
+   * 'user', 'content': input}].
+   */
+  input?:
+    | string
+    | Array<
+        | TextContent
+        | ImageContent
+        | ToolCallContent
+        | ToolReturnContent
+        | ReasoningContent
+        | RedactedReasoningContent
+        | OmittedReasoningContent
+        | MessageStreamParams.SummarizedReasoningContent
+      >
+    | null;
+
   /**
    * Maximum number of steps the agent should take to process the request.
    */
   max_steps?: number;
 
+  /**
+   * The messages to be sent to the agent.
+   */
+  messages?: Array<AgentsAPI.MessageCreate | ApprovalCreate> | null;
+
   /**
    * Flag to determine if individual tokens should be streamed, rather than streaming
-   * per step.
+   * per step (only used when streaming=true).
    */
   stream_tokens?: boolean;
 
+  /**
+   * If True, returns a streaming response (Server-Sent Events). If False (default),
+   * returns a complete response.
+   */
+  streaming?: boolean;
+
   /**
    * @deprecated Whether the server should parse specific tool call arguments
    * (default `send_message`) as `AssistantMessage` objects. Still supported for
@@ -1834,12 +2253,54 @@ export interface MessageStreamParams {
   use_assistant_message?: boolean;
 }
 
+export namespace MessageStreamParams {
+  /**
+   * The style of reasoning content returned by the OpenAI Responses API
+   */
+  export interface SummarizedReasoningContent {
+    /**
+     * The unique identifier for this reasoning step.
+     */
+    id: string;
+
+    /**
+     * Summaries of the reasoning content.
+     */
+    summary: Array<SummarizedReasoningContent.Summary>;
+
+    /**
+     * The encrypted reasoning content.
+     */
+    encrypted_content?: string;
+
+    /**
+     * Indicates this is a summarized reasoning step.
+     */
+    type?: 'summarized_reasoning';
+  }
+
+  export namespace SummarizedReasoningContent {
+    export interface Summary {
+      /**
+       * The index of the summary part.
+       */
+      index: number;
+
+      /**
+       * The text of the summary part.
+       */
+      text: string;
+    }
+  }
+}
+
 export declare namespace Messages {
   export {
     type ApprovalCreate as ApprovalCreate,
     type ApprovalRequestMessage as ApprovalRequestMessage,
     type ApprovalResponseMessage as ApprovalResponseMessage,
     type AssistantMessage as AssistantMessage,
+    type EventMessage as EventMessage,
     type HiddenReasoningMessage as HiddenReasoningMessage,
     type ImageContent as ImageContent,
     type JobStatus as JobStatus,
@@ -1859,6 +2320,7 @@ export declare namespace Messages {
     type ReasoningMessage as ReasoningMessage,
     type RedactedReasoningContent as RedactedReasoningContent,
     type Run as Run,
+    type SummaryMessage as SummaryMessage,
     type SystemMessage as SystemMessage,
     type TextContent as TextContent,
     type ToolCall as ToolCall,
@@ -1880,6 +2342,8 @@ export declare namespace Messages {
     type MessageModifyParams as MessageModifyParams,
     type MessageResetParams as MessageResetParams,
     type MessageSendParams as MessageSendParams,
+    type MessageSendParamsNonStreaming as MessageSendParamsNonStreaming,
+    type MessageSendParamsStreaming as MessageSendParamsStreaming,
     type MessageSendAsyncParams as MessageSendAsyncParams,
     type MessageStreamParams as MessageStreamParams,
   };