Messages API Reference

/**
 * Base message class
 */
class BaseMessage {
  content: string | ContentBlock[];
  additional_kwargs?: Record<string, any>;
  response_metadata?: Record<string, any>;

  constructor(content: string | ContentBlock[], kwargs?: Record<string, any>);
}

/**
 * AI/Assistant message
 */
class AIMessage extends BaseMessage {
  constructor(content: string | ContentBlock[], kwargs?: Record<string, any>);
}

/**
 * Human/User message
 */
class HumanMessage extends BaseMessage {
  constructor(content: string | ContentBlock[], kwargs?: Record<string, any>);
}

/**
 * System instructions message
 */
class SystemMessage extends BaseMessage {
  constructor(content: string, kwargs?: Record<string, any>);
}

/**
 * Tool result message
 */
class ToolMessage extends BaseMessage {
  tool_call_id: string;

  constructor(content: string, tool_call_id: string, kwargs?: Record<string, any>);
}

/**
 * Base message chunk for streaming
 */
class BaseMessageChunk extends BaseMessage {}

/**
 * AI message chunk
 */
class AIMessageChunk extends BaseMessageChunk {}

/**
 * Human message chunk
 */
class HumanMessageChunk extends BaseMessageChunk {}

/**
 * System message chunk
 */
class SystemMessageChunk extends BaseMessageChunk {}

/**
 * Tool message chunk
 */
class ToolMessageChunk extends BaseMessageChunk {
  tool_call_id: string;
}

/**
 * Content block types for multimodal content
 */
type ContentBlock =
  | string
  | { type: "text"; text: string }
  | { type: "image_url"; image_url: string | { url: string; detail?: string } }
  | { type: "image"; source: { type: "base64"; media_type: string; data: string } };

/**
 * Filter messages based on criteria
 */
function filterMessages(
  messages: BaseMessage[],
  options: FilterMessagesOptions
): BaseMessage[];

interface FilterMessagesOptions {
  /**
   * Include messages of these types
   */
  includeTypes?: Array<"human" | "ai" | "system" | "tool">;

  /**
   * Exclude messages of these types
   */
  excludeTypes?: Array<"human" | "ai" | "system" | "tool">;

  /**
   * Include only last N messages
   */
  last?: number;

  /**
   * Include only first N messages
   */
  first?: number;
}

/**
 * Trim messages to fit within token limit
 */
function trimMessages(
  messages: BaseMessage[],
  options: TrimMessagesOptions
): BaseMessage[];

interface TrimMessagesOptions {
  /**
   * Maximum number of tokens
   */
  maxTokens: number;

  /**
   * Token counter function
   */
  tokenCounter?: (messages: BaseMessage[]) => number;

  /**
   * Strategy for trimming
   * - "first": Keep first messages
   * - "last": Keep last messages (default)
   * - "middle": Keep first and last, remove middle
   */
  strategy?: "first" | "last" | "middle";

  /**
   * Minimum messages to keep
   */
  minMessages?: number;
}