Interface MessageStructure<TTools>

Example

// Basic message structure with just content blocks
interface SimpleMessageStructure extends MessageStructure {
  content: {
    human: ContentBlock.Text;
    // allows for text + reasoning blocks in ai messages
    ai: ContentBlock.Text | ContentBlock.Reasoning;
  }
}

// Message structure with tools and properties
interface AdvancedMessageStructure extends MessageStructure {
  tools: {
    calculator: MessageToolDefinition<
      { operation: string; numbers: number[] },
      number
    >;
  };
  content: {
    // allows for text + image blocks in human messages
    human: ContentBlock.Text | ContentBlock.Multimodal.Image;
    // only allows for text blocks in ai messages
    ai: ContentBlock.Text;
  };
  properties: {
    // pins properties to ai messages
    ai: {
      response_metadata: {
        confidence: number;
        model: string;
      };
    };
  }
}

// Using with $MergeMessageStructure to combine structures
// The resulting type when passed into BaseMessage will have a calculator tool,
// allow for text + image blocks in human messages,
// and text + reasoning blocks + additional arbitrary properties in ai messages.
type CombinedStructure = $MergeMessageStructure<
  SimpleMessageStructure,
  AdvancedMessageStructure
>;

// Using in a Message object
const message: Message<CombinedStructure> = {
  id: "msg-123",
  type: "human",
  content: [
    { type: "text", text: "Hello!" }
    { type: "image", mimeType: "image/jpeg", url: "https://example.com/image.jpg" }
    // this block will throw an error because it's not defined in the structure
    { type: "reasoning", reasoning: "The answer is 42" }
  ]
};
Copy