What is SystemMessage?
SystemMessage represents the system turn in a chat conversation. It carries instructions that persist across the entire conversation—persona, behavioral constraints, output format requirements, or safety rules. The model treats the system message as a meta-instruction that shapes how it interprets and responds to all subsequent human messages.
SystemMessage must appear first in the messages list passed to a chat model. In LangChain, when you use ChatPromptTemplate.from_messages([("system", "..."), ("human", "...")]), the system string is automatically wrapped in a SystemMessage—you rarely need to instantiate SystemMessage directly unless you are building messages programmatically at runtime.
Different providers enforce different system message rules. OpenAI and Anthropic both support system messages but have different context limits and caching behaviors. Anthropic's system prompt caching makes long system messages cost-effective at scale. Gemini models use the system_instruction parameter under the hood rather than a message role. LangChain's chat model wrappers abstract these differences, but provider-specific token accounting may differ.
When to Use
You want to control model behavior. Use SystemMessage to set personality, guidelines, or context for all responses.
Use Cases
- • Set AI personality
- • Define behavior guidelines
- • Context setting
- • Role definition
- • Safety constraints
- • Style guidance
Key Features
- ✓ System instructions
- ✓ Message type
- ✓ Metadata support
- ✓ First in list
- ✓ Global scope
- ✓ Flexible content
When NOT to Use
For user input—use HumanMessage.
Notes
SystemMessage must be first in the list
The OpenAI API and most providers require the system message to appear before any user or assistant turns. Passing [HumanMessage(...), SystemMessage(...)] is silently reordered by some SDKs and rejected by others. Treat position 0 as a hard requirement.
Anthropic system prompt caching
When using Claude models, a SystemMessage with 1024+ tokens can be cached on Anthropic servers. Set additional_kwargs={"cache_control": {"type": "ephemeral"}} to enable it. Cached system prompts reduce cost by up to 90% for long instructions reused across many API calls.
Content can be a list for multimodal context
SystemMessage(content=[{"type": "text", "text": "You are a vision assistant"}, ...]) allows multimodal system instructions on models that support it (GPT-4V, Claude 3). String content is far more common and sufficient for text-only workflows.
Use ChatPromptTemplate for variable system prompts
If your system prompt contains variables (username, current date, document context), use ChatPromptTemplate.from_messages([("system", "You are {name}"), ("human", "{input}")]) instead of building SystemMessage objects manually—it integrates cleanly with LCEL.
Import
from langchain_core.messages import SystemMessageConfiguration
| Parameter | Type | Default | Purpose |
|---|---|---|---|
| content | str | None | System instructions |
Usage Examples
System Prompt
from langchain_core.messages import SystemMessage, HumanMessage
messages = [
SystemMessage(content='You are a helpful Python expert'),
HumanMessage(content='How do I sort a list?')
]
result = model.invoke(messages)System Message with Persona
from langchain_core.messages import SystemMessage
# Dynamic system prompt built at runtime
user_name = "Alice"
system = SystemMessage(
content=f"You are a personal assistant for {user_name}. "
"Be concise and friendly."
)
result = model.invoke([system, HumanMessage(content=question)])Dynamic System Message via ChatPromptTemplate
from langchain_core.prompts import ChatPromptTemplate
# Preferred for variable system prompts
prompt = ChatPromptTemplate.from_messages([
("system", "You are {role}. Language: {lang}."),
("human", "{question}")
])
chain = prompt | model | StrOutputParser()
result = chain.invoke({'role': 'chef', 'lang': 'French', 'question': 'Boeuf bourguignon?'})Common Pitfalls
❌ Put SystemMessage after HumanMessage
✅ SystemMessage should be first in the list
Alternatives
| Class | When to Use |
|---|---|
| ChatPromptTemplate | For templated system messages with variables |
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 SystemMessage and the wider framework.
SystemMessage FAQ
What is SystemMessage in LangChain?
Set system-level instructions for model behavior. SystemMessage represents the system turn in a chat conversation. It carries instructions that persist across the entire conversation—persona, behavioral constraints, output format requirements, or safety rules. The model treats the system message as a meta-instruction that shapes how it interprets and responds to all subsequent human messages. SystemMessage must appear first in the messages list passed to a chat model. In LangChain, when you use ChatPromptTemplate.from_messa…
Which package provides SystemMessage?
DevShelfHub documents SystemMessage from the langchain-core package. Pin your installed LangChain version and match imports to the snippet on this page.
When should I use SystemMessage?
You want to control model behavior. Use SystemMessage to set personality, guidelines, or context for all responses.
When should I avoid using SystemMessage?
For user input—use HumanMessage.
How do I import SystemMessage in Python?
from langchain_core.messages import SystemMessage
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.