@letta-ai/letta-client 1.2.0 → 1.3.2

package/src/resources/blocks/blocks.ts

@@ -394,8 +394,8 @@ export interface BlockListParams extends ArrayPageParams {
   connected_to_agents_count_lt?: number | null;
 
   /**
-   * Search blocks by description. If provided, returns blocks that match this
-   * description. This is a full-text search on block descriptions.
+   * Search blocks by description. If provided, returns blocks whose description
+   * matches the search query. This is a full-text search on block descriptions.
    */
   description_search?: string | null;
 
@@ -405,23 +405,23 @@ export interface BlockListParams extends ArrayPageParams {
   identifier_keys?: Array<string> | null;
 
   /**
-   * Search agents by identifier id
+   * The ID of the identity in the format 'identity-<uuid4>'
    */
   identity_id?: string | null;
 
   /**
-   * Labels to include (e.g. human, persona)
+   * Label to include (alphanumeric, hyphens, underscores only)
    */
   label?: string | null;
 
   /**
-   * Search blocks by label. If provided, returns blocks that match this label. This
-   * is a full-text search on labels.
+   * Search blocks by label. If provided, returns blocks whose label matches the
+   * search query. This is a full-text search on block labels.
    */
   label_search?: string | null;
 
   /**
-   * Name of the block
+   * Name filter (alphanumeric, spaces, hyphens, underscores)
    */
   name?: string | null;
 
@@ -436,7 +436,8 @@ export interface BlockListParams extends ArrayPageParams {
   templates_only?: boolean;
 
   /**
-   * Search blocks by value. If provided, returns blocks that match this value.
+   * Search blocks by value. If provided, returns blocks whose value matches the
+   * search query. This is a full-text search on block values.
    */
   value_search?: string | null;
 }

package/src/resources/identities/identities.ts

@@ -213,6 +213,10 @@ export interface IdentityListParams extends ArrayPageParams {
 
   name?: string | null;
 
+  /**
+   * @deprecated [DEPRECATED: Use X-Project-Id header instead] Filter identities by
+   * project ID
+   */
   project_id?: string | null;
 }
 

package/src/resources/index.ts

@@ -117,11 +117,9 @@ export {
   type CreateSseMcpServer,
   type CreateStdioMcpServer,
   type CreateStreamableHTTPMcpServer,
-  type McpToolExecuteRequest,
   type SseMcpServer,
   type StdioMcpServer,
   type StreamableHTTPMcpServer,
-  type ToolExecutionResult,
   type UpdateSseMcpServer,
   type UpdateStdioMcpServer,
   type UpdateStreamableHTTPMcpServer,
@@ -134,6 +132,15 @@ export {
   type McpServerUpdateParams,
   type McpServerRefreshParams,
 } from './mcp-servers/mcp-servers';
+export {
+  Messages,
+  type MessageSearchRequest,
+  type MessageSearchResult,
+  type MessageListResponse,
+  type MessageSearchResponse,
+  type MessageListParams,
+  type MessageSearchParams,
+} from './messages';
 export {
   Models,
   type EmbeddingConfig,
@@ -145,6 +152,7 @@ export {
   type ModelListResponse,
   type ModelListParams,
 } from './models/models';
+export { Passages, type Passage, type PassageSearchResponse, type PassageSearchParams } from './passages';
 export { Runs, type Job, type StopReasonType, type RunListParams } from './runs/runs';
 export {
   Steps,
@@ -154,7 +162,15 @@ export {
   type StepsArrayPage,
 } from './steps/steps';
 export { Tags, type TagListResponse, type TagListParams } from './tags';
-export { Templates } from './templates/templates';
+export {
+  Templates,
+  type TemplateCreateResponse,
+  type TemplateUpdateResponse,
+  type TemplateDeleteResponse,
+  type TemplateCreateParams,
+  type TemplateUpdateParams,
+  type TemplateDeleteParams,
+} from './templates/templates';
 export {
   Tools,
   type NpmRequirement,
@@ -162,12 +178,15 @@ export {
   type Tool,
   type ToolCreate,
   type ToolReturnMessage,
+  type ToolSearchRequest,
+  type ToolSearchResult,
   type ToolType,
   type ToolDeleteResponse,
-  type ToolUpsertBaseToolsResponse,
+  type ToolSearchResponse,
   type ToolCreateParams,
   type ToolUpdateParams,
   type ToolListParams,
+  type ToolSearchParams,
   type ToolUpsertParams,
   type ToolsArrayPage,
 } from './tools';

package/src/resources/mcp-servers/index.ts

@@ -5,11 +5,9 @@ export {
   type CreateSseMcpServer,
   type CreateStdioMcpServer,
   type CreateStreamableHTTPMcpServer,
-  type McpToolExecuteRequest,
   type SseMcpServer,
   type StdioMcpServer,
   type StreamableHTTPMcpServer,
-  type ToolExecutionResult,
   type UpdateSseMcpServer,
   type UpdateStdioMcpServer,
   type UpdateStreamableHTTPMcpServer,

package/src/resources/mcp-servers/mcp-servers.ts

@@ -1,7 +1,6 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 import { APIResource } from '../../core/resource';
-import * as AgentsAPI from '../agents/agents';
 import * as ToolsAPI from './tools';
 import { ToolListResponse, ToolRetrieveParams, ToolRunParams, Tools } from './tools';
 import { APIPromise } from '../../core/api-promise';
@@ -153,16 +152,6 @@ export interface CreateStreamableHTTPMcpServer {
   mcp_server_type?: 'streamable_http';
 }
 
-/**
- * Request to execute an MCP tool by IDs.
- */
-export interface McpToolExecuteRequest {
-  /**
-   * Arguments to pass to the MCP tool
-   */
-  args?: { [key: string]: unknown };
-}
-
 /**
  * An SSE MCP server
  */
@@ -269,40 +258,6 @@ export interface StreamableHTTPMcpServer {
   mcp_server_type?: 'streamable_http';
 }
 
-export interface ToolExecutionResult {
-  /**
-   * The status of the tool execution and return object
-   */
-  status: 'success' | 'error';
-
-  /**
-   * Representation of an agent's state. This is the state of the agent at a given
-   * time, and is persisted in the DB backend. The state has all the information
-   * needed to recreate a persisted agent.
-   */
-  agent_state?: AgentsAPI.AgentState | null;
-
-  /**
-   * The function return object
-   */
-  func_return?: unknown;
-
-  /**
-   * The fingerprint of the config for the sandbox
-   */
-  sandbox_config_fingerprint?: string | null;
-
-  /**
-   * Captured stderr from the function invocation
-   */
-  stderr?: Array<string> | null;
-
-  /**
-   * Captured stdout (prints, logs) from function invocation
-   */
-  stdout?: Array<string> | null;
-}
-
 /**
  * Update schema for SSE MCP server - all fields optional
  */
@@ -433,11 +388,9 @@ export declare namespace McpServers {
     type CreateSseMcpServer as CreateSseMcpServer,
     type CreateStdioMcpServer as CreateStdioMcpServer,
     type CreateStreamableHTTPMcpServer as CreateStreamableHTTPMcpServer,
-    type McpToolExecuteRequest as McpToolExecuteRequest,
     type SseMcpServer as SseMcpServer,
     type StdioMcpServer as StdioMcpServer,
     type StreamableHTTPMcpServer as StreamableHTTPMcpServer,
-    type ToolExecutionResult as ToolExecutionResult,
     type UpdateSseMcpServer as UpdateSseMcpServer,
     type UpdateStdioMcpServer as UpdateStdioMcpServer,
     type UpdateStreamableHTTPMcpServer as UpdateStreamableHTTPMcpServer,

package/src/resources/mcp-servers/tools.ts

@@ -2,7 +2,7 @@
 
 import { APIResource } from '../../core/resource';
 import * as ToolsAPI from '../tools';
-import * as McpServersAPI from './mcp-servers';
+import * as AgentsToolsAPI from '../agents/tools';
 import { APIPromise } from '../../core/api-promise';
 import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
@@ -26,14 +26,14 @@ export class Tools extends APIResource {
   /**
    * Execute a specific MCP tool
    *
-   * The request body should contain the tool arguments in the MCPToolExecuteRequest
+   * The request body should contain the tool arguments in the ToolExecuteRequest
    * format.
    */
   run(
     toolID: string,
     params: ToolRunParams,
     options?: RequestOptions,
-  ): APIPromise<McpServersAPI.ToolExecutionResult> {
+  ): APIPromise<AgentsToolsAPI.ToolExecutionResult> {
     const { mcp_server_id, ...body } = params;
     return this._client.post(path`/v1/mcp-servers/${mcp_server_id}/tools/${toolID}/run`, {
       body,
@@ -55,7 +55,7 @@ export interface ToolRunParams {
   mcp_server_id: string;
 
   /**
-   * Body param: Arguments to pass to the MCP tool
+   * Body param: Arguments to pass to the tool
    */
   args?: { [key: string]: unknown };
 }

package/src/resources/messages.ts

@@ -0,0 +1,165 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../core/resource';
+import * as ToolsAPI from './tools';
+import * as AgentsMessagesAPI from './agents/messages';
+import { APIPromise } from '../core/api-promise';
+import { RequestOptions } from '../internal/request-options';
+
+export class Messages extends APIResource {
+  /**
+   * List messages across all agents for the current user.
+   */
+  list(
+    query: MessageListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<MessageListResponse> {
+    return this._client.get('/v1/messages/', { query, ...options });
+  }
+
+  /**
+   * Search messages across the organization with optional agent filtering. Returns
+   * messages with FTS/vector ranks and total RRF score.
+   *
+   * This is a cloud-only feature.
+   */
+  search(body: MessageSearchParams, options?: RequestOptions): APIPromise<MessageSearchResponse> {
+    return this._client.post('/v1/messages/search', { body, ...options });
+  }
+}
+
+export interface MessageSearchRequest {
+  /**
+   * Text query for full-text search
+   */
+  query: string;
+
+  /**
+   * Filter messages created on or before this date
+   */
+  end_date?: string | null;
+
+  /**
+   * Maximum number of results to return
+   */
+  limit?: number;
+
+  /**
+   * Search mode to use
+   */
+  search_mode?: 'vector' | 'fts' | 'hybrid';
+
+  /**
+   * Filter messages created after this date
+   */
+  start_date?: string | null;
+}
+
+/**
+ * Result from a message search operation with scoring details.
+ */
+export interface MessageSearchResult {
+  /**
+   * The embedded content (LLM-friendly)
+   */
+  embedded_text: string;
+
+  /**
+   * The raw message object
+   */
+  message: AgentsMessagesAPI.InternalMessage;
+
+  /**
+   * Reciprocal Rank Fusion combined score
+   */
+  rrf_score: number;
+
+  /**
+   * Full-text search rank position if FTS was used
+   */
+  fts_rank?: number | null;
+
+  /**
+   * Vector search rank position if vector search was used
+   */
+  vector_rank?: number | null;
+}
+
+export type MessageListResponse = Array<AgentsMessagesAPI.Message>;
+
+export type MessageSearchResponse = Array<
+  | AgentsMessagesAPI.SystemMessage
+  | AgentsMessagesAPI.UserMessage
+  | AgentsMessagesAPI.ReasoningMessage
+  | AgentsMessagesAPI.HiddenReasoningMessage
+  | AgentsMessagesAPI.ToolCallMessage
+  | ToolsAPI.ToolReturnMessage
+  | AgentsMessagesAPI.AssistantMessage
+  | AgentsMessagesAPI.ApprovalRequestMessage
+  | AgentsMessagesAPI.ApprovalResponseMessage
+  | AgentsMessagesAPI.SummaryMessage
+  | AgentsMessagesAPI.EventMessage
+>;
+
+export interface MessageListParams {
+  /**
+   * Message ID cursor for pagination. Returns messages that come after this message
+   * ID in the specified sort order
+   */
+  after?: string | null;
+
+  /**
+   * Message ID cursor for pagination. Returns messages that come before this message
+   * ID in the specified sort order
+   */
+  before?: string | null;
+
+  /**
+   * Maximum number of messages to return
+   */
+  limit?: number | null;
+
+  /**
+   * Sort order for messages by creation time. 'asc' for oldest first, 'desc' for
+   * newest first
+   */
+  order?: 'asc' | 'desc';
+}
+
+export interface MessageSearchParams {
+  /**
+   * Text query for full-text search
+   */
+  query: string;
+
+  /**
+   * Filter messages created on or before this date
+   */
+  end_date?: string | null;
+
+  /**
+   * Maximum number of results to return
+   */
+  limit?: number;
+
+  /**
+   * Search mode to use
+   */
+  search_mode?: 'vector' | 'fts' | 'hybrid';
+
+  /**
+   * Filter messages created after this date
+   */
+  start_date?: string | null;
+}
+
+export declare namespace Messages {
+  export {
+    type MessageSearchRequest as MessageSearchRequest,
+    type MessageSearchResult as MessageSearchResult,
+    type MessageListResponse as MessageListResponse,
+    type MessageSearchResponse as MessageSearchResponse,
+    type MessageListParams as MessageListParams,
+    type MessageSearchParams as MessageSearchParams,
+  };
+}

package/src/resources/models/models.ts

@@ -1,6 +1,7 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 import { APIResource } from '../../core/resource';
+import * as AgentsAPI from '../agents/agents';
 import * as EmbeddingsAPI from './embeddings';
 import { EmbeddingListResponse, Embeddings } from './embeddings';
 import { APIPromise } from '../../core/api-promise';
@@ -326,6 +327,16 @@ export interface LlmConfig {
    */
   reasoning_effort?: 'none' | 'minimal' | 'low' | 'medium' | 'high' | null;
 
+  /**
+   * The response format for the model's output. Supports text, json_object, and
+   * json_schema (structured outputs). Can be set via model_settings.
+   */
+  response_format?:
+    | AgentsAPI.TextResponseFormat
+    | AgentsAPI.JsonSchemaResponseFormat
+    | AgentsAPI.JsonObjectResponseFormat
+    | null;
+
   /**
    * The temperature to use when generating text with the model. A higher temperature
    * will result in more random text.
@@ -481,6 +492,16 @@ export interface Model {
    */
   reasoning_effort?: 'none' | 'minimal' | 'low' | 'medium' | 'high' | null;
 
+  /**
+   * The response format for the model's output. Supports text, json_object, and
+   * json_schema (structured outputs). Can be set via model_settings.
+   */
+  response_format?:
+    | AgentsAPI.TextResponseFormat
+    | AgentsAPI.JsonSchemaResponseFormat
+    | AgentsAPI.JsonObjectResponseFormat
+    | null;
+
   /**
    * @deprecated Deprecated: The temperature to use when generating text with the
    * model.

package/src/resources/passages.ts

@@ -0,0 +1,182 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../core/resource';
+import * as PassagesAPI from './passages';
+import * as ModelsAPI from './models/models';
+import { APIPromise } from '../core/api-promise';
+import { RequestOptions } from '../internal/request-options';
+
+export class Passages extends APIResource {
+  /**
+   * Search passages across the organization with optional agent and archive
+   * filtering. Returns passages with relevance scores.
+   *
+   * This endpoint supports semantic search through passages:
+   *
+   * - If neither agent_id nor archive_id is provided, searches ALL passages in the
+   *   organization
+   * - If agent_id is provided, searches passages across all archives attached to
+   *   that agent
+   * - If archive_id is provided, searches passages within that specific archive
+   * - If both are provided, agent_id takes precedence
+   */
+  search(body: PassageSearchParams, options?: RequestOptions): APIPromise<PassageSearchResponse> {
+    return this._client.post('/v1/passages/search', { body, ...options });
+  }
+}
+
+/**
+ * Representation of a passage, which is stored in archival memory.
+ */
+export interface Passage {
+  /**
+   * The embedding of the passage.
+   */
+  embedding: Array<number> | null;
+
+  /**
+   * Configuration for embedding model connection and processing parameters.
+   */
+  embedding_config: ModelsAPI.EmbeddingConfig | null;
+
+  /**
+   * The text of the passage.
+   */
+  text: string;
+
+  /**
+   * The human-friendly ID of the Passage
+   */
+  id?: string;
+
+  /**
+   * The unique identifier of the archive containing this passage.
+   */
+  archive_id?: string | null;
+
+  /**
+   * The creation date of the passage.
+   */
+  created_at?: string;
+
+  /**
+   * The id of the user that made this object.
+   */
+  created_by_id?: string | null;
+
+  /**
+   * The unique identifier of the file associated with the passage.
+   */
+  file_id?: string | null;
+
+  /**
+   * The name of the file (only for source passages).
+   */
+  file_name?: string | null;
+
+  /**
+   * Whether this passage is deleted or not.
+   */
+  is_deleted?: boolean;
+
+  /**
+   * The id of the user that made this object.
+   */
+  last_updated_by_id?: string | null;
+
+  /**
+   * The metadata of the passage.
+   */
+  metadata?: { [key: string]: unknown } | null;
+
+  /**
+   * @deprecated Deprecated: Use `folder_id` field instead. The data source of the
+   * passage.
+   */
+  source_id?: string | null;
+
+  /**
+   * Tags associated with this passage.
+   */
+  tags?: Array<string> | null;
+
+  /**
+   * The timestamp when the object was last updated.
+   */
+  updated_at?: string | null;
+}
+
+export type PassageSearchResponse = Array<PassageSearchResponse.PassageSearchResponseItem>;
+
+export namespace PassageSearchResponse {
+  /**
+   * Result from a passage search operation with scoring details.
+   */
+  export interface PassageSearchResponseItem {
+    /**
+     * The passage object
+     */
+    passage: PassagesAPI.Passage;
+
+    /**
+     * Relevance score
+     */
+    score: number;
+
+    /**
+     * Additional metadata about the search result
+     */
+    metadata?: { [key: string]: unknown };
+  }
+}
+
+export interface PassageSearchParams {
+  /**
+   * Text query for semantic search
+   */
+  query: string;
+
+  /**
+   * Filter passages by agent ID
+   */
+  agent_id?: string | null;
+
+  /**
+   * Filter passages by archive ID
+   */
+  archive_id?: string | null;
+
+  /**
+   * Filter results to passages created before this datetime
+   */
+  end_date?: string | null;
+
+  /**
+   * Maximum number of results to return
+   */
+  limit?: number;
+
+  /**
+   * Filter results to passages created after this datetime
+   */
+  start_date?: string | null;
+
+  /**
+   * How to match tags - 'any' to match passages with any of the tags, 'all' to match
+   * only passages with all tags
+   */
+  tag_match_mode?: 'any' | 'all';
+
+  /**
+   * Optional list of tags to filter search results
+   */
+  tags?: Array<string> | null;
+}
+
+export declare namespace Passages {
+  export {
+    type Passage as Passage,
+    type PassageSearchResponse as PassageSearchResponse,
+    type PassageSearchParams as PassageSearchParams,
+  };
+}

package/src/resources/runs/usage.ts

@@ -28,11 +28,15 @@ export interface UsageRetrieveResponse {
 
 export namespace UsageRetrieveResponse {
   export interface CompletionTokensDetails {
-    reasoning_tokens?: number;
+    reasoning_tokens?: number | null;
   }
 
   export interface PromptTokensDetails {
-    cached_tokens?: number;
+    cache_creation_tokens?: number | null;
+
+    cache_read_tokens?: number | null;
+
+    cached_tokens?: number | null;
   }
 }
 

package/src/resources/steps/steps.ts

@@ -111,7 +111,7 @@ export interface Step {
   completion_tokens?: number | null;
 
   /**
-   * Metadata for the agent.
+   * Detailed completion token breakdown (e.g., reasoning_tokens).
    */
   completion_tokens_details?: { [key: string]: unknown } | null;
 
@@ -166,6 +166,12 @@ export interface Step {
    */
   prompt_tokens?: number | null;
 
+  /**
+   * Detailed prompt token breakdown (e.g., cached_tokens, cache_read_tokens,
+   * cache_creation_tokens).
+   */
+  prompt_tokens_details?: { [key: string]: unknown } | null;
+
   /**
    * The category of the provider used for this step.
    */

package/src/resources/templates/index.ts

@@ -1,4 +1,12 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 export { Agents, type AgentCreateResponse, type AgentCreateParams } from './agents';
-export { Templates } from './templates';
+export {
+  Templates,
+  type TemplateCreateResponse,
+  type TemplateUpdateResponse,
+  type TemplateDeleteResponse,
+  type TemplateCreateParams,
+  type TemplateUpdateParams,
+  type TemplateDeleteParams,
+} from './templates';