> ## Documentation Index
> Fetch the complete documentation index at: https://docs.langchain.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Messages

Messages are the fundamental unit of context for models in LangChain. They represent the input and output of models, carrying both the content and metadata needed to represent the state of a conversation when interacting with an LLM.

Messages are objects that contain:

* <Icon icon="user" size={16} /> [**Role**](#message-types) - Identifies the message type (e.g. `system`, `user`)
* <Icon icon="folder" size={16} /> [**Content**](#message-content) - Represents the actual content of the message (like text, images, audio, documents, etc.)
* <Icon icon="tag" size={16} /> [**Metadata**](#message-metadata) - Optional fields such as response information, message IDs, and token usage

LangChain provides a standard message type that works across all model providers, ensuring consistent behavior regardless of the model being called.

## Basic usage

The simplest way to use messages is to create message objects and pass them to a model when [invoking](/oss/javascript/langchain/models#invocation).

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { initChatModel, HumanMessage, SystemMessage } from "langchain";

const model = await initChatModel("gpt-5-nano");

const systemMsg = new SystemMessage("You are a helpful assistant.");
const humanMsg = new HumanMessage("Hello, how are you?");

const messages = [systemMsg, humanMsg];
const response = await model.invoke(messages);  // Returns AIMessage
```

### Text prompts

Text prompts are strings - ideal for straightforward generation tasks where you don't need to retain conversation history.

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const response = await model.invoke("Write a haiku about spring");
```

**Use text prompts when:**

* You have a single, standalone request
* You don't need conversation history
* You want minimal code complexity

### Message prompts

Alternatively, you can pass in a list of messages to the model by providing a list of message objects.

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { SystemMessage, HumanMessage, AIMessage } from "langchain";

const messages = [
  new SystemMessage("You are a poetry expert"),
  new HumanMessage("Write a haiku about spring"),
  new AIMessage("Cherry blossoms bloom..."),
];
const response = await model.invoke(messages);
```

**Use message prompts when:**

* Managing multi-turn conversations
* Working with multimodal content (images, audio, files)
* Including system instructions

### Dictionary format

You can also specify messages directly in OpenAI chat completions format.

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const messages = [
  { role: "system", content: "You are a poetry expert" },
  { role: "user", content: "Write a haiku about spring" },
  { role: "assistant", content: "Cherry blossoms bloom..." },
];
const response = await model.invoke(messages);
```

## Message types

* <Icon icon="settings" size={16} /> [System message](#system-message) - Tells the model how to behave and provide context for interactions
* <Icon icon="user" size={16} /> [Human message](#human-message) - Represents user input and interactions with the model
* <Icon icon="robot" size={16} /> [AI message](#ai-message) - Responses generated by the model, including text content, tool calls, and metadata
* <Icon icon="tool" size={16} /> [Tool message](#tool-message) - Represents the outputs of [tool calls](/oss/javascript/langchain/models#tool-calling)

### System message

A [`SystemMessage`](https://reference.langchain.com/javascript/langchain-core/messages/SystemMessage) represent an initial set of instructions that primes the model's behavior. You can use a system message to set the tone, define the model's role, and establish guidelines for responses.

```typescript Basic instructions theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { SystemMessage, HumanMessage, AIMessage } from "langchain";

const systemMsg = new SystemMessage("You are a helpful coding assistant.");

const messages = [
  systemMsg,
  new HumanMessage("How do I create a REST API?"),
];
const response = await model.invoke(messages);
```

```typescript Detailed persona theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { SystemMessage, HumanMessage } from "langchain";

const systemMsg = new SystemMessage(`
You are a senior TypeScript developer with expertise in web frameworks.
Always provide code examples and explain your reasoning.
Be concise but thorough in your explanations.
`);

const messages = [
  systemMsg,
  new HumanMessage("How do I create a REST API?"),
];
const response = await model.invoke(messages);
```

***

### Human message

A [`HumanMessage`](https://reference.langchain.com/javascript/langchain-core/messages/HumanMessage) represents user input and interactions. They can contain text, images, audio, files, and any other amount of multimodal [content](#message-content).

#### Text content

```typescript Message object theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const response = await model.invoke([
  new HumanMessage("What is machine learning?"),
]);
```

```typescript String shortcut theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const response = await model.invoke("What is machine learning?");
```

#### Message metadata

```typescript Add metadata theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const humanMsg = new HumanMessage({
  content: "Hello!",
  name: "alice",
  id: "msg_123",
});
```

<Note>
  The `name` field behavior varies by provider—some use it for user identification, others ignore it. To check, refer to the model provider's [reference](https://reference.langchain.com/python/integrations/).
</Note>

***

### AI message

An [`AIMessage`](https://reference.langchain.com/javascript/langchain-core/messages/AIMessage) represents the output of a model invocation. They can include multimodal data, tool calls, and provider-specific metadata that you can later access.

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const response = await model.invoke("Explain AI");
console.log(typeof response);  // AIMessage
```

[`AIMessage`](https://reference.langchain.com/javascript/langchain-core/messages/AIMessage) objects are returned by the model when calling it, which contains all of the associated metadata in the response.

Providers weigh/contextualize types of messages differently, which means it is sometimes helpful to manually create a new [`AIMessage`](https://reference.langchain.com/javascript/langchain-core/messages/AIMessage) object and insert it into the message history as if it came from the model.

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { AIMessage, SystemMessage, HumanMessage } from "langchain";

const aiMsg = new AIMessage("I'd be happy to help you with that question!");

const messages = [
  new SystemMessage("You are a helpful assistant"),
  new HumanMessage("Can you help me?"),
  aiMsg,  // Insert as if it came from the model
  new HumanMessage("Great! What's 2+2?")
]

const response = await model.invoke(messages);
```

<Accordion title="Attributes">
  <ParamField path="text" type="string">
    The text content of the message.
  </ParamField>

  <ParamField path="content" type="string | ContentBlock[]">
    The raw content of the message.
  </ParamField>

  <ParamField path="content_blocks" type="ContentBlock.Standard[]">
    The standardized content blocks of the message. (See [content](#message-content))
  </ParamField>

  <ParamField path="tool_calls" type="ToolCall[] | None">
    The tool calls made by the model.

    Empty if no tools are called.
  </ParamField>

  <ParamField path="id" type="string">
    A unique identifier for the message (either automatically generated by LangChain or returned in the provider response)
  </ParamField>

  <ParamField path="usage_metadata" type="UsageMetadata | None">
    The usage metadata of the message, which can contain token counts when available. See [`UsageMetadata`](https://reference.langchain.com/javascript/langchain-core/messages/UsageMetadata).
  </ParamField>

  <ParamField path="response_metadata" type="ResponseMetadata | None">
    The response metadata of the message.
  </ParamField>
</Accordion>

#### Tool calls

When models make [tool calls](/oss/javascript/langchain/models#tool-calling), they're included in the [`AIMessage`](https://reference.langchain.com/javascript/langchain-core/messages/AIMessage):

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const modelWithTools = model.bindTools([getWeather]);
const response = await modelWithTools.invoke("What's the weather in Paris?");

for (const toolCall of response.tool_calls) {
  console.log(`Tool: ${toolCall.name}`);
  console.log(`Args: ${toolCall.args}`);
  console.log(`ID: ${toolCall.id}`);
}
```

Other structured data, such as reasoning or citations, can also appear in message [content](/oss/javascript/langchain/messages#message-content).

#### Token usage

An [`AIMessage`](https://reference.langchain.com/javascript/langchain-core/messages/AIMessage) can hold token counts and other usage metadata in its [`usage_metadata`](https://reference.langchain.com/javascript/langchain-core/messages/UsageMetadata) field:

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { initChatModel } from "langchain";

const model = await initChatModel("gpt-5-nano");

const response = await model.invoke("Hello!");
console.log(response.usage_metadata);
```

```json theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "output_tokens": 304,
  "input_tokens": 8,
  "total_tokens": 312,
  "input_token_details": {
    "cache_read": 0
  },
  "output_token_details": {
    "reasoning": 256
  }
}
```

See [`UsageMetadata`](https://reference.langchain.com/javascript/langchain-core/messages/UsageMetadata) for details.

#### Streaming and chunks

During streaming, you'll receive [`AIMessageChunk`](https://reference.langchain.com/javascript/langchain-core/messages/AIMessageChunk) objects that can be combined into a full message object:

<CodeGroup>
  ```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  import { AIMessageChunk } from "langchain";

  let finalChunk: AIMessageChunk | undefined;
  for (const chunk of chunks) {
    finalChunk = finalChunk ? finalChunk.concat(chunk) : chunk;
  }
  ```
</CodeGroup>

<Note>
  Learn more:

  * [Streaming tokens from chat models](/oss/javascript/langchain/models#stream)
  * [Streaming tokens and/or steps from agents](/oss/javascript/langchain/streaming)
</Note>

***

### Tool message

For models that support [tool calling](/oss/javascript/langchain/models#tool-calling), AI messages can contain tool calls. Tool messages are used to pass the results of a single tool execution back to the model.

[Tools](/oss/javascript/langchain/tools) can generate [`ToolMessage`](https://reference.langchain.com/javascript/langchain-core/messages/ToolMessage) objects directly. Below, we show a simple example. Read more in the [tools guide](/oss/javascript/langchain/tools).

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { AIMessage, ToolMessage } from "langchain";

const aiMessage = new AIMessage({
  content: [],
  tool_calls: [{
    name: "get_weather",
    args: { location: "San Francisco" },
    id: "call_123"
  }]
});

const toolMessage = new ToolMessage({
  content: "Sunny, 72°F",
  tool_call_id: "call_123"
});

const messages = [
  new HumanMessage("What's the weather in San Francisco?"),
  aiMessage,  // Model's tool call
  toolMessage,  // Tool execution result
];

const response = await model.invoke(messages);  // Model processes the result
```

<Accordion title="Attributes">
  <ParamField path="content" type="string" required>
    The stringified output of the tool call.
  </ParamField>

  <ParamField path="tool_call_id" type="string" required>
    The ID of the tool call that this message is responding to. Must match the ID of the tool call in the [`AIMessage`](https://reference.langchain.com/javascript/langchain-core/messages/AIMessage).
  </ParamField>

  <ParamField path="name" type="string" required>
    The name of the tool that was called.
  </ParamField>

  <ParamField path="artifact" type="dict">
    Additional data not sent to the model but can be accessed programmatically.
  </ParamField>
</Accordion>

<Note>
  The `artifact` field stores supplementary data that won't be sent to the model but can be accessed programmatically. This is useful for storing raw results, debugging information, or data for downstream processing without cluttering the model's context.

  <Accordion title="Example: Using artifact for retrieval metadata">
    For example, a [retrieval](/oss/javascript/langchain/retrieval) tool could retrieve a passage from a document for reference by a model. Where message `content` contains text that the model will reference, an `artifact` can contain document identifiers or other metadata that an application can use (e.g., to render a page). See example below:

    ```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    import { ToolMessage } from "langchain";

    // Artifact available downstream
    const artifact = { document_id: "doc_123", page: 0 };

    const toolMessage = new ToolMessage({
      content: "It was the best of times, it was the worst of times.",
      tool_call_id: "call_123",
      name: "search_books",
      artifact
    });
    ```

    See the [RAG tutorial](/oss/javascript/langchain/rag) for an end-to-end example of building retrieval [agents](/oss/javascript/langchain/agents) with LangChain.
  </Accordion>
</Note>

***

## Message content

You can think of a message's content as the payload of data that gets sent to the model. Messages have a `content` attribute that is loosely-typed, supporting strings and lists of untyped objects (e.g., dictionaries). This allows support for provider-native structures directly in LangChain chat models, such as [multimodal](#multimodal) content and other data.

Separately, LangChain provides dedicated content types for text, reasoning, citations, multi-modal data, server-side tool calls, and other message content. See [content blocks](#standard-content-blocks) below.

LangChain chat models accept message content in the `content` attribute.

This may contain either:

1. A string
2. A list of content blocks in a provider-native format
3. A list of [LangChain's standard content blocks](#standard-content-blocks)

See below for an example using [multimodal](#multimodal) inputs:

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { HumanMessage } from "langchain";

// String content
const humanMessage = new HumanMessage("Hello, how are you?");

// Provider-native format (e.g., OpenAI)
const humanMessage = new HumanMessage({
  content: [
    { type: "text", text: "Hello, how are you?" },
    {
      type: "image_url",
      image_url: { url: "https://example.com/image.jpg" },
    },
  ],
});

// List of standard content blocks
const humanMessage = new HumanMessage({
  contentBlocks: [
    { type: "text", text: "Hello, how are you?" },
    { type: "image", url: "https://example.com/image.jpg" },
  ],
});
```

### Standard content blocks

LangChain provides a standard representation for message content that works across providers.

Message objects implement a `contentBlocks` property that will lazily parse the `content` attribute into a standard, type-safe representation. For example, messages generated from [`ChatAnthropic`](/oss/javascript/integrations/chat/anthropic) or [`ChatOpenAI`](/oss/javascript/integrations/chat/openai) will include `thinking` or `reasoning` blocks in the format of the respective provider, but can be lazily parsed into a consistent [`ReasoningContentBlock`](#content-block-reference) representation:

<Tabs>
  <Tab title="Anthropic">
    ```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    import { AIMessage } from "@langchain/core/messages";

    const message = new AIMessage({
      content: [
        {
          "type": "thinking",
          "thinking": "...",
          "signature": "WaUjzkyp...",
        },
        {
          "type":"text",
          "text": "...",
          "id": "msg_abc123",
        },
      ],
      response_metadata: { model_provider: "anthropic" },
    });

    console.log(message.contentBlocks);
    ```
  </Tab>

  <Tab title="OpenAI">
    ```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    import { AIMessage } from "@langchain/core/messages";

    const message = new AIMessage({
      content: [
        {
          "type": "reasoning",
          "id": "rs_abc123",
          "summary": [
            {"type": "summary_text", "text": "summary 1"},
            {"type": "summary_text", "text": "summary 2"},
          ],
        },
        {"type": "text", "text": "..."},
      ],
      response_metadata: { model_provider: "openai" },
    });

    console.log(message.contentBlocks);
    ```
  </Tab>
</Tabs>

See the [integrations guides](/oss/javascript/integrations/providers/overview) to get started with the
inference provider of your choice.

<Note>
  **Serializing standard content**

  If an application outside of LangChain needs access to the standard content block
  representation, you can opt-in to storing content blocks in message content.

  To do this, you can set the `LC_OUTPUT_VERSION` environment variable to `v1`. Or,
  initialize any chat model with `outputVersion: "v1"`:

  ```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  import { initChatModel } from "langchain";

  const model = await initChatModel(
    "gpt-5-nano",
    { outputVersion: "v1" }
  );
  ```
</Note>

### Multimodal

**Multimodality** refers to the ability to work with data that comes in different
forms, such as text, audio, images, and video. LangChain includes standard types
for these data that can be used across providers.

[Chat models](/oss/javascript/langchain/models) can accept multimodal data as input and generate
it as output. Below we show short examples of input messages featuring multimodal data.

<Note>
  Extra keys can be included top-level in the content block or nested in `"extras": {"key": value}`.

  [OpenAI](/oss/javascript/integrations/chat/openai) and [AWS Bedrock Converse](/oss/javascript/integrations/chat/bedrock),
  for example, require a filename for PDFs. See the [provider page](/oss/javascript/integrations/providers/overview)
  for your chosen model for specifics.
</Note>

<CodeGroup>
  ```typescript Image input theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  // From URL
  const message = new HumanMessage({
    content: [
      { type: "text", text: "Describe the content of this image." },
      {
        type: "image",
        source_type: "url",
        url: "https://example.com/path/to/image.jpg"
      },
    ],
  });

  // From base64 data
  const message = new HumanMessage({
    content: [
      { type: "text", text: "Describe the content of this image." },
      {
        type: "image",
        source_type: "base64",
        data: "AAAAIGZ0eXBtcDQyAAAAAGlzb21tcDQyAAACAGlzb2...",
      },
    ],
  });

  // From provider-managed File ID
  const message = new HumanMessage({
    content: [
      { type: "text", text: "Describe the content of this image." },
      { type: "image", source_type: "id", id: "file-abc123" },
    ],
  });
  ```

  ```typescript PDF document input theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  // From URL
  const message = new HumanMessage({
    content: [
      { type: "text", text: "Describe the content of this document." },
      { type: "file", source_type: "url", url: "https://example.com/path/to/document.pdf", mime_type: "application/pdf" },
    ],
  });

  // From base64 data
  const message = new HumanMessage({
    content: [
      { type: "text", text: "Describe the content of this document." },
      {
        type: "file",
        source_type: "base64",
        data: "AAAAIGZ0eXBtcDQyAAAAAGlzb21tcDQyAAACAGlzb2...",
        mime_type: "application/pdf",
      },
    ],
  });

  // From provider-managed File ID
  const message = new HumanMessage({
    content: [
      { type: "text", text: "Describe the content of this document." },
      { type: "file", source_type: "id", id: "file-abc123" },
    ],
  });
  ```

  ```typescript Audio input theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  // From base64 data
  const message = new HumanMessage({
    content: [
      { type: "text", text: "Describe the content of this audio." },
      {
        type: "audio",
        source_type: "base64",
        data: "AAAAIGZ0eXBtcDQyAAAAAGlzb21tcDQyAAACAGlzb2...",
      },
    ],
  });

  // From provider-managed File ID
  const message = new HumanMessage({
    content: [
      { type: "text", text: "Describe the content of this audio." },
      { type: "audio", source_type: "id", id: "file-abc123" },
    ],
  });
  ```

  ```typescript Video input theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  // From base64 data
  const message = new HumanMessage({
    content: [
      { type: "text", text: "Describe the content of this video." },
      {
        type: "video",
        source_type: "base64",
        data: "AAAAIGZ0eXBtcDQyAAAAAGlzb21tcDQyAAACAGlzb2...",
      },
    ],
  });

  // From provider-managed File ID
  const message = new HumanMessage({
    content: [
      { type: "text", text: "Describe the content of this video." },
      { type: "video", source_type: "id", id: "file-abc123" },
    ],
  });
  ```
</CodeGroup>

<Warning>
  Not all models support all file types. Check the model provider's [reference](https://reference.langchain.com/python/integrations/) for supported formats and size limits.
</Warning>

### Content block reference

Content blocks are represented (either when creating a message or accessing the `contentBlocks` field) as a list of typed objects. Each item in the list must adhere to one of the following block types:

<AccordionGroup>
  <Accordion title="Core" icon="cube">
    <AccordionGroup>
      <Accordion title="ContentBlock.Text" icon="typography">
        **Purpose:** Standard text output

        <ParamField body="type" type="string" required>
          Always `"text"`
        </ParamField>

        <ParamField body="text" type="string" required>
          The text content
        </ParamField>

        <ParamField body="annotations" type="Citation[]">
          List of annotations for the text
        </ParamField>

        **Example:**

        ```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
        {
            type: "text",
            text: "Hello world",
            annotations: []
        }
        ```
      </Accordion>

      <Accordion title="ContentBlock.Reasoning" icon="brain">
        **Purpose:** Model reasoning steps

        <ParamField body="type" type="string" required>
          Always `"reasoning"`
        </ParamField>

        <ParamField body="reasoning" type="string" required>
          The reasoning content
        </ParamField>

        **Example:**

        ```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
        {
            type: "reasoning",
            reasoning: "The user is asking about..."
        }
        ```
      </Accordion>
    </AccordionGroup>
  </Accordion>

  <Accordion title="Multimodal" icon="photo">
    <AccordionGroup>
      <Accordion title="ContentBlock.Multimodal.Image" icon="photo">
        **Purpose:** Image data

        <ParamField body="type" type="string" required>
          Always `"image"`
        </ParamField>

        <ParamField body="url" type="string">
          URL pointing to the image location.
        </ParamField>

        <ParamField body="data" type="string">
          Base64-encoded image data.
        </ParamField>

        <ParamField body="fileId" type="string">
          Reference to the image in an external file storage system (e.g., OpenAI or Anthropic's Files API).
        </ParamField>

        <ParamField body="mimeType" type="string">
          Image [MIME type](https://www.iana.org/assignments/media-types/media-types.xhtml#image) (e.g., `image/jpeg`, `image/png`). Required for base64 data.
        </ParamField>
      </Accordion>

      <Accordion title="ContentBlock.Multimodal.Audio" icon="volume">
        **Purpose:** Audio data

        <ParamField body="type" type="string" required>
          Always `"audio"`
        </ParamField>

        <ParamField body="url" type="string">
          URL pointing to the audio location.
        </ParamField>

        <ParamField body="data" type="string">
          Base64-encoded audio data.
        </ParamField>

        <ParamField body="fileId" type="string">
          Reference to the audio file in an external file storage system (e.g., OpenAI or Anthropic's Files API).
        </ParamField>

        <ParamField body="mimeType" type="string">
          Audio [MIME type](https://www.iana.org/assignments/media-types/media-types.xhtml#audio) (e.g., `audio/mpeg`, `audio/wav`). Required for base64 data.
        </ParamField>
      </Accordion>

      <Accordion title="ContentBlock.Multimodal.Video" icon="video">
        **Purpose:** Video data

        <ParamField body="type" type="string" required>
          Always `"video"`
        </ParamField>

        <ParamField body="url" type="string">
          URL pointing to the video location.
        </ParamField>

        <ParamField body="data" type="string">
          Base64-encoded video data.
        </ParamField>

        <ParamField body="fileId" type="string">
          Reference to the video file in an external file storage system (e.g., OpenAI or Anthropic's Files API).
        </ParamField>

        <ParamField body="mimeType" type="string">
          Video [MIME type](https://www.iana.org/assignments/media-types/media-types.xhtml#video) (e.g., `video/mp4`, `video/webm`). Required for base64 data.
        </ParamField>
      </Accordion>

      <Accordion title="ContentBlock.Multimodal.File" icon="file">
        **Purpose:** Generic files (PDF, etc)

        <ParamField body="type" type="string" required>
          Always `"file"`
        </ParamField>

        <ParamField body="url" type="string">
          URL pointing to the file location.
        </ParamField>

        <ParamField body="data" type="string">
          Base64-encoded file data.
        </ParamField>

        <ParamField body="fileId" type="string">
          Reference to the file in an external file storage system (e.g., OpenAI or Anthropic's Files API).
        </ParamField>

        <ParamField body="mimeType" type="string">
          File [MIME type](https://www.iana.org/assignments/media-types/media-types.xhtml) (e.g., `application/pdf`). Required for base64 data.
        </ParamField>
      </Accordion>

      <Accordion title="ContentBlock.Multimodal.PlainText" icon="align-left">
        **Purpose:** Document text (`.txt`, `.md`)

        <ParamField body="type" type="string" required>
          Always `"text-plain"`
        </ParamField>

        <ParamField body="text" type="string" required>
          The text content
        </ParamField>

        <ParamField body="title" type="string">
          Title of the text content
        </ParamField>

        <ParamField body="mimeType" type="string">
          [MIME type](https://www.iana.org/assignments/media-types/media-types.xhtml) of the text (e.g., `text/plain`, `text/markdown`)
        </ParamField>
      </Accordion>
    </AccordionGroup>
  </Accordion>

  <Accordion title="Tool Calling" icon="tool">
    <AccordionGroup>
      <Accordion title="ContentBlock.Tools.ToolCall" icon="function">
        **Purpose:** Function calls

        <ParamField body="type" type="string" required>
          Always `"tool_call"`
        </ParamField>

        <ParamField body="name" type="string" required>
          Name of the tool to call
        </ParamField>

        <ParamField body="args" type="object" required>
          Arguments to pass to the tool
        </ParamField>

        <ParamField body="id" type="string" required>
          Unique identifier for this tool call
        </ParamField>

        **Example:**

        ```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
        {
            type: "tool_call",
            name: "search",
            args: { query: "weather" },
            id: "call_123"
        }
        ```
      </Accordion>

      <Accordion title="ContentBlock.Tools.ToolCallChunk" icon="puzzle">
        **Purpose:** Streaming tool fragments

        <ParamField body="type" type="string" required>
          Always `"tool_call_chunk"`
        </ParamField>

        <ParamField body="name" type="string">
          Name of the tool being called
        </ParamField>

        <ParamField body="args" type="string">
          Partial tool arguments (may be incomplete JSON)
        </ParamField>

        <ParamField body="id" type="string">
          Tool call identifier
        </ParamField>

        <ParamField body="index" type="number | string" required>
          Position of this chunk in the stream
        </ParamField>
      </Accordion>

      <Accordion title="ContentBlock.Tools.InvalidToolCall" icon="alert-triangle">
        **Purpose:** Malformed calls

        <ParamField body="type" type="string" required>
          Always `"invalid_tool_call"`
        </ParamField>

        <ParamField body="name" type="string">
          Name of the tool that failed to be called
        </ParamField>

        <ParamField body="args" type="string">
          Raw arguments that failed to parse
        </ParamField>

        <ParamField body="error" type="string" required>
          Description of what went wrong
        </ParamField>

        **Common errors:** Invalid JSON, missing required fields
      </Accordion>
    </AccordionGroup>
  </Accordion>

  <Accordion title="Server-Side Tool Execution" icon="server">
    <AccordionGroup>
      <Accordion title="ContentBlock.Tools.ServerToolCall" icon="tool">
        **Purpose:** Tool call that is executed server-side.

        <ParamField body="type" type="string" required>
          Always `"server_tool_call"`
        </ParamField>

        <ParamField body="id" type="string" required>
          An identifier associated with the tool call.
        </ParamField>

        <ParamField body="name" type="string" required>
          The name of the tool to be called.
        </ParamField>

        <ParamField body="args" type="string" required>
          Partial tool arguments (may be incomplete JSON)
        </ParamField>
      </Accordion>

      <Accordion title="ContentBlock.Tools.ServerToolCallChunk" icon="puzzle">
        **Purpose:** Streaming server-side tool call fragments

        <ParamField body="type" type="string" required>
          Always `"server_tool_call_chunk"`
        </ParamField>

        <ParamField body="id" type="string">
          An identifier associated with the tool call.
        </ParamField>

        <ParamField body="name" type="string">
          Name of the tool being called
        </ParamField>

        <ParamField body="args" type="string">
          Partial tool arguments (may be incomplete JSON)
        </ParamField>

        <ParamField body="index" type="number | string">
          Position of this chunk in the stream
        </ParamField>
      </Accordion>

      <Accordion title="ContentBlock.Tools.ServerToolResult" icon="package">
        **Purpose:** Search results

        <ParamField body="type" type="string" required>
          Always `"server_tool_result"`
        </ParamField>

        <ParamField body="tool_call_id" type="string" required>
          Identifier of the corresponding server tool call.
        </ParamField>

        <ParamField body="id" type="string">
          Identifier associated with the server tool result.
        </ParamField>

        <ParamField body="status" type="string" required>
          Execution status of the server-side tool. `"success"` or `"error"`.
        </ParamField>

        <ParamField body="output">
          Output of the executed tool.
        </ParamField>
      </Accordion>
    </AccordionGroup>
  </Accordion>

  <Accordion title="Provider-Specific Blocks" icon="plug">
    <Accordion title="ContentBlock.NonStandard" icon="asterisk">
      **Purpose:** Provider-specific escape hatch

      <ParamField body="type" type="string" required>
        Always `"non_standard"`
      </ParamField>

      <ParamField body="value" type="object" required>
        Provider-specific data structure
      </ParamField>

      **Usage:** For experimental or provider-unique features
    </Accordion>

    Additional provider-specific content types may be found within the [reference documentation](/oss/javascript/integrations/providers/overview) of each model provider.
  </Accordion>
</AccordionGroup>

Each of these content blocks mentioned above are individually addressable as types when importing the [`ContentBlock`](https://reference.langchain.com/javascript/langchain-core/messages/ContentBlock) type.

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { ContentBlock } from "langchain";

// Text block
const textBlock: ContentBlock.Text = {
    type: "text",
    text: "Hello world",
}

// Image block
const imageBlock: ContentBlock.Multimodal.Image = {
    type: "image",
    url: "https://example.com/image.png",
    mimeType: "image/png",
}
```

<Tip>
  View the canonical type definitions in the [API reference](https://reference.langchain.com/javascript/modules/_langchain_core.messages.html).
</Tip>

<Info>
  Content blocks were introduced as a new property on messages in LangChain v1 to standardize content formats across providers while maintaining backward compatibility with existing code.

  Content blocks are not a replacement for the [`content`](https://reference.langchain.com/javascript/langchain-core/messages/BaseMessage) property, but rather a new property that can be used to access the content of a message in a standardized format.
</Info>

## Use with chat models

[Chat models](/oss/javascript/langchain/models) accept a sequence of message objects as input and return an [`AIMessage`](https://reference.langchain.com/javascript/langchain-core/messages/AIMessage) as output. Interactions are often stateless, so that a simple conversational loop involves invoking a model with a growing list of messages.

Refer to the below guides to learn more:

* Built-in features for [persisting and managing conversation histories](/oss/javascript/langchain/short-term-memory)
* Strategies for managing context windows, including [trimming and summarizing messages](/oss/javascript/langchain/short-term-memory#common-patterns)

***

<div className="source-links">
  <Callout icon="terminal-2">
    [Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.
  </Callout>

  <Callout icon="edit">
    [Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/oss/langchain/messages.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
  </Callout>
</div>