Overview​

Messages are the unit of communication inchat models. They are used to represent the input and output of a chat model, as well as any additional context or metadata that may be associated with a conversation.

Each message has arole (e.g., "user", "assistant") andcontent (e.g., text, multimodal data) with additional metadata that varies depending on the chat model provider.

LangChain provides a unified message format that can be used across chat models, allowing users to work with different chat models without worrying about the specific details of the message format used by each model provider.

What is inside a message?​

A message typically consists of the following pieces of information:

• Role: The role of the message (e.g., "user", "assistant").
• Content: The content of the message (e.g., text, multimodal data).
• Additional metadata: id, name,token usage and other model-specific metadata.

Role​

Roles are used to distinguish between different types of messages in a conversation and help the chat model understand how to respond to a given sequence of messages.

Content​

The content of a message text or a list of dictionaries representingmultimodal data (e.g., images, audio, video). The exact format of the content can vary between different chat model providers.

Currently, most chat models support text as the primary content type, with some models also supporting multimodal data. However, support for multimodal data is still limited across most chat model providers.

For more information see:

• SystemMessage -- for content which should be passed to direct the conversation
• HumanMessage -- for content in the input from the user.
• AIMessage -- for content in the response from the model.
• Multimodality -- for more information on multimodal content.

Other Message Data​

Depending on the chat model provider, messages can include other data such as:

• ID: An optional unique identifier for the message.
• Name: An optionalname property which allows differentiate between different entities/speakers with the same role. Not all models support this!
• Metadata: Additional information about the message, such as timestamps, token usage, etc.
• Tool Calls: A request made by the model to call one or more tools> Seetool calling for more information.

Conversation Structure​

The sequence of messages into a chat model should follow a specific structure to ensure that the chat model can generate a valid response.

For example, a typical conversation structure might look like this:

1. User Message: "Hello, how are you?"
2. Assistant Message: "I'm doing well, thank you for asking."
3. User Message: "Can you tell me a joke?"
4. Assistant Message: "Sure! Why did the scarecrow win an award? Because he was outstanding in his field!"

Please read thechat history guide for more information on managing chat history and ensuring that the conversation structure is correct.

LangChain Messages​

LangChain provides a unified message format that can be used across all chat models, allowing users to work with different chat models without worrying about the specific details of the message format used by each model provider.

LangChain messages are Python objects that subclass from aBaseMessage.

The five main message types are:

• SystemMessage: corresponds tosystem role
• HumanMessage: corresponds touser role
• AIMessage: corresponds toassistant role
• AIMessageChunk: corresponds toassistant role, used forstreaming responses
• ToolMessage: corresponds totool role

Other important messages include:

• RemoveMessage -- does not correspond to any role. This is an abstraction, mostly used inLangGraph to manage chat history.
• LegacyFunctionMessage: corresponds to thefunction role in OpenAI'slegacy function-calling API.

You can find more information aboutmessages in theAPI Reference.

SystemMessage​

ASystemMessage is used to prime the behavior of the AI model and provide additional context, such as instructing the model to adopt a specific persona or setting the tone of the conversation (e.g., "This is a conversation about cooking").

Different chat providers may support system message in one of the following ways:

• Through a "system" message role: In this case, a system message is included as part of the message sequence with the role explicitly set as "system."
• Through a separate API parameter for system instructions: Instead of being included as a message, system instructions are passed via a dedicated API parameter.
• No support for system messages: Some models do not support system messages at all.

Most major chat model providers support system instructions via either a chat message or a separate API parameter. LangChain will automatically adapt based on the provider’s capabilities. If the provider supports a separate API parameter for system instructions, LangChain will extract the content of a system message and pass it through that parameter.

If no system message is supported by the provider, in most cases LangChain will attempt to incorporate the system message's content into a HumanMessage or raise an exception if that is not possible. However, this behavior is not yet consistently enforced across all implementations, and if using a less popular implementation of a chat model (e.g., an implementation from thelangchain-community package) it is recommended to check the specific documentation for that model.

HumanMessage​

TheHumanMessage corresponds to the"user" role. A human message represents input from a user interacting with the model.

Text Content​

Most chat models expect the user input to be in the form of text.

from langchain_core.messagesimport HumanMessage

model.invoke([HumanMessage(content="Hello, how are you?")])

model.invoke("Hello, how are you?")

Multi-modal Content​

Some chat models accept multimodal inputs, such as images, audio, video, or files like PDFs.

Please see themultimodality guide for more information.

AIMessage​

AIMessage is used to represent a message with the role"assistant". This is the response from the model, which can include text or a request to invoke tools. It could also include other media types like images, audio, or video -- though this is still uncommon at the moment.

from langchain_core.messagesimport HumanMessage
ai_message= model.invoke([HumanMessage("Tell me a joke")])
ai_message# <-- AIMessage

AnAIMessage has the following attributes. The attributes which arestandardized are the ones that LangChain attempts to standardize across different chat model providers.raw fields are specific to the model provider and may vary.

content​

Thecontent property of anAIMessage represents the response generated by the chat model.

The content is either:

• text -- the norm for virtually all chat models.
• Alist of dictionaries -- Each dictionary represents a content block and is associated with atype.
  • Used by Anthropic for surfacing agent thought process when doingtool calling.
  • Used by OpenAI for audio outputs. Please seemulti-modal content for more information.

AIMessageChunk​

It is common tostream responses for the chat model as they are being generated, so the user can see the response in real-time instead of waiting for the entire response to be generated before displaying it.

It is returned from thestream,astream andastream_events methods of the chat model.

For example,

for chunkin model.stream([HumanMessage("what color is the sky?")]):
print(chunk)

AIMessageChunk follows nearly the same structure asAIMessage, but uses a differentToolCallChunkto be able to stream tool calling in a standardized manner.

Aggregating​

AIMessageChunks support the+ operator to merge them into a singleAIMessage. This is useful when you want to display the final response to the user.

ai_message= chunk1+ chunk2+ chunk3+...

ToolMessage​

This represents a message with role "tool", which contains the result ofcalling a tool. In addition torole andcontent, this message has:

• atool_call_id field which conveys the id of the call to the tool that was called to produce this result.
• anartifact field which can be used to pass along arbitrary artifacts of the tool execution which are useful to track but which should not be sent to the model.

Please seetool calling for more information.

RemoveMessage​

This is a special message type that does not correspond to any roles. It is usedfor managing chat history inLangGraph.

Please see the following for more information on how to use theRemoveMessage:

• Memory conceptual guide
• How to delete messages

(Legacy) FunctionMessage​

This is a legacy message type, corresponding to OpenAI's legacy function-calling API.ToolMessage should be used instead to correspond to the updated tool-calling API.

OpenAI Format​

Inputs​

Chat models also accept OpenAI's format asinputs to chat models:

chat_model.invoke([
{
"role":"user",
"content":"Hello, how are you?",
},
{
"role":"assistant",
"content":"I'm doing well, thank you for asking.",
},
{
"role":"user",
"content":"Can you tell me a joke?",
}
])

Outputs​

At the moment, the output of the model will be in terms of LangChain messages, so you will need to convert the output to the OpenAI format if youneed OpenAI format for the output as well.

Theconvert_to_openai_messages utility function can be used to convert from LangChain messages to OpenAI format.