> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Roles and Messages
> Explains system, user, and assistant message roles, how message order and stateless API calls affect context, and best practices for preserving conversation history and enforcing assistant behavior.
When you send messages to an LLM API, the `messages` list carries the full conversation. That list supports three roles — `system`, `user`, and `assistant` — and their order determines the model's behavior and context. Understanding these roles is essential for predictable, repeatable responses from the API.
## Why roles matter
* The model reads the entire `messages` array in order and generates a reply based on that context.
* Every API call is stateless: there is no built-in memory between calls. To preserve context across turns you must re-send the prior messages in the next API request.
* The roles let you control persona, constraints, and conversational history.
## The `system` role — set behavior and constraints
The `system` message is a preface the user never sees. Use it to set tone, constraints, and rules the assistant should follow throughout the conversation (persona, formatting rules, or any background assumptions).
Example `system` message:
```json theme={null}
{
"role": "system",
"content": "You are a helpful assistant"
}
```
Another example to establish a persona and style:
```json theme={null}
{
"role": "system",
"content": "Senior engineer, code review. Be direct and critical."
}
```
System messages are very powerful and are the recommended place to encode policies, style guides, or any non-user-visible instructions the assistant must honor.
## The `assistant` role — include prior model replies
`assistant` messages are previous model outputs included back into the conversation history. Because each API call is independent, you must include earlier `assistant` responses in the `messages` list to maintain context and allow the model to resolve pronouns or references like “that city.”
Example of a short conversation history:
```json theme={null}
[
{ "role": "system", "content": "Be helpful" },
{ "role": "user", "content": "What is Python?" },
{ "role": "assistant", "content": "Python is a high-level, interpreted programming language known for its readability and broad ecosystem." }
]
```
If you want multi-turn behavior, include all previous turns (system, user, assistant) in the next API call so the model can refer back to them.
## The `user` role — the human side of the conversation
`user` messages represent the active inputs from the human. They are the most common role for new content. Example:
```json theme={null}
{ "role": "user", "content": "How do I connect a PostgreSQL database to my app?" }
```
## Quick reference table
| Role | Purpose | Typical use |
| - | - | - |
| `system` | Global behavior, persona, constraints, formatting rules | `{"role":"system","content":"You are a concise assistant."}` |
| `user` | Human's questions and inputs | `{"role":"user","content":"Write a SQL query to..."} ` |
| `assistant` | Model's previous replies included in history | `{"role":"assistant","content":"Here is the query..."} ` |
## Best practices and tips
Use the `system` message to encode non-user-visible policies (tone, safety, and formatting rules). Keep system prompts concise and deterministic: long, ambiguous system messages can produce inconsistent behavior.
* Always include the `system` message if you need consistent persona or constraints.
* For multi-turn flows, replay the full conversation history (previous `user` and `assistant` messages) back to the API.
* Prefer small, focused system instructions rather than very long scripts.
Do not place secrets (API keys, passwords, or PII) inside messages. Messages are used to generate responses and may be logged or inspected; keep sensitive data in secure storage.
## Example: building a multi-turn API payload
A typical request body for a follow-up question:
```json theme={null}
{
"model": "gpt-4o-mini",
"messages": [
{ "role": "system", "content": "You are a helpful assistant that explains code examples simply." },
{ "role": "user", "content": "Show a Python function to reverse a string." },
{ "role": "assistant", "content": "Sure — use slicing: `def reverse(s): return s[::-1]`" },
{ "role": "user", "content": "Now do the same but with a loop." }
]
}
```
Because the previous `assistant` reply is included, the model can take the follow-up into account and produce the requested variant.
## Links and references
* OpenAI API reference: [https://platform.openai.com/docs/api-reference](https://platform.openai.com/docs/api-reference)
* Conversation design guide: [https://developers.google.com/assistant/conversational](https://developers.google.com/assistant/conversational)
* Best practices for prompt design: [https://learn.microsoft.com/azure/ai-services/openai/concepts/prompt-engineering](https://learn.microsoft.com/azure/ai-services/openai/concepts/prompt-engineering)
Together, `system`, `user`, and `assistant` messages let you precisely control the assistant’s behavior and maintain conversational state across stateless API calls.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.