What is HumanMessage?
HumanMessage is the message type that represents a user turn in a conversation. LangChain models do not accept bare strings directly in multi-turn contexts — they expect a list of typed message objects. HumanMessage, together with AIMessage and SystemMessage, forms the three-role conversation structure that mirrors the OpenAI chat completion API and is shared across all LangChain chat model providers.
The content field accepts either a plain string or a list for multimodal payloads. For vision models, pass a list of dicts: [{"type": "text", "text": "Describe this"}, {"type": "image_url", "image_url": {"url": "data:image/..."}}]. Additional metadata can be stored in additional_kwargs (provider-specific extras) or name (to label the human speaker in multi-agent setups). The id field uniquely identifies a message in a thread, which LangGraph uses for deduplication when replaying state.
When building conversation history manually, collect messages in a plain list and pass it to model.invoke(). For stateful chatbots, use InMemoryChatMessageHistory or a persistent store with RunnableWithMessageHistory — those classes manage appending HumanMessage and AIMessage pairs automatically. The trim_messages utility can prune long histories down to a token budget before passing them to the model.
When to Use
You're building conversational AI. Use HumanMessage to represent user input in message lists.
Use Cases
- • Chatbot user input
- • Multi-turn conversations
- • Conversation history
- • Q&A systems
- • Message composition
- • Chat state management
Key Features
- ✓ Message type
- ✓ Metadata support
- ✓ Multimodal content
- ✓ Pretty-print support
- ✓ History-friendly
- ✓ Type-safe
When NOT to Use
For single non-conversational LLM calls—just use a string.
Notes
content can be a list for multimodal input
When passing images or mixed content, set content to a list of dicts with "type" keys. Supported types depend on the provider — OpenAI accepts "image_url" and "image" (base64). Always check the provider docs; passing unsupported content types raises a validation error at the API level, not in Python.
additional_kwargs vs metadata
additional_kwargs is for provider-specific raw fields that LangChain does not model explicitly (e.g. a custom cache key). metadata is for your own tracking fields and is never sent to the LLM. Do not put display text or PII in metadata — it survives serialisation and may appear in logs.
Message identity in LangGraph state
LangGraph annotates the messages key with add_messages, which uses the id field to deduplicate. If you construct HumanMessage without an explicit id, one is generated. When replaying or patching graph state, supply the same id to update an existing message rather than appending a duplicate.
trim_messages keeps token budgets under control
Long histories bloat context and cost money. Use trim_messages(messages, max_tokens=2000, token_counter=model) before invoking. It preserves the system message and trims oldest turns first. Import from langchain_core.messages.
Import
from langchain_core.messages import HumanMessageConfiguration
| Parameter | Type | Default | Purpose |
|---|---|---|---|
| content | str|list | None | Message content (text or multimodal) |
Usage Examples
Basic Text Message
from langchain_core.messages import HumanMessage
msg = HumanMessage(content='Hello, how are you?')
result = model.invoke([msg])Multi-turn Conversation History
from langchain_core.messages import HumanMessage, SystemMessage
history = [
SystemMessage(content='You are a helpful assistant.'),
HumanMessage(content='What is the capital of France?'),
# AIMessage goes here after first response
HumanMessage(content='And what is its population?'),
]
response = model.invoke(history)Multimodal Image + Text
# Vision model — image + text in one message
msg = HumanMessage(content=[
{"type": "text", "text": "What do you see in this image?"},
{"type": "image_url", "image_url": {"url": image_url}},
])
result = vision_model.invoke([msg])Common Pitfalls
❌ model.invoke('Hello') # String instead of message
✅ model.invoke([HumanMessage(content='Hello')])
Related LangChain References
Browse the full LangChain API reference index to explore more classes, methods, and decorators, or start with the LangChain introduction tutorial for end-to-end context on building with HumanMessage and the wider framework.
HumanMessage FAQ
What is HumanMessage in LangChain?
Represent user input in conversations. HumanMessage is the message type that represents a user turn in a conversation. LangChain models do not accept bare strings directly in multi-turn contexts — they expect a list of typed message objects. HumanMessage, together with AIMessage and SystemMessage, forms the three-role conversation structure that mirrors the OpenAI chat completion API and is shared across all LangChain chat model providers. The content field accepts either a plain string or a list for multimodal p…
Which package provides HumanMessage?
DevShelfHub documents HumanMessage from the langchain-core package. Pin your installed LangChain version and match imports to the snippet on this page.
When should I use HumanMessage?
You're building conversational AI. Use HumanMessage to represent user input in message lists.
When should I avoid using HumanMessage?
For single non-conversational LLM calls—just use a string.
How do I import HumanMessage in Python?
from langchain_core.messages import HumanMessage
Where can I explore more LangChain API reference pages?
Open the LangChain API reference index on DevShelfHub to browse classes, methods, and decorators, each with runnable examples, parameters, common mistakes, and cross-links.