> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/tech/en/advanced-genai-tech/system-prompt.md).

# System Prompts

Context the platform automatically appends to your system prompt before each Agent response (time, user name, location, language, contact and member attributes, knowledge base and skill guidance, etc.

Last updated: 2026-10-04

A system prompt is the set of rules you write for an Agent to follow in every response. For writing guidance, templates, and examples, see the [System Prompt Design Guide](https://docs.maiagent.ai/build/agent/system-prompt) in the user manual.

This page covers the other part: before each response, the platform automatically appends "current context" to the system prompt based on the Agent and conversation platform settings, and sends both to the model. The system regenerates this content for each response. You do not need to, and should not, hard-code it in the system prompt.

## How the System Prompt Sent to the Model Is Assembled <a href="#prompt-assembly" id="prompt-assembly"></a>

For each response, the platform assembles the following in order:

1. **The system prompt you wrote**. For group conversations, the platform's group conversation instructions come first, followed by your system prompt.
2. **Citation marker instructions**: When <mark style="color:blue;">Enable Inline Citations</mark> is enabled for the Agent, rules for inserting `[1][2]` citation markers in responses are appended.
3. **Context appended by the platform**: Time, user name, location, language, custom attributes, etc. See the [next section](#platform-context).
4. **Conditional notices**: For example, when the user specifies a skill or when the knowledge base is temporarily unavailable. See [Conditional Notices](#conditional-notices).

The appended content is used only for the current response and is not written back to the Agent's system prompt settings.

## Context Appended by the Platform <a href="#platform-context" id="platform-context"></a>

| Appended Content                                                                                                                                                              | When It Is Appended                                                                                                                                                                                                                                   | Where the Value Comes From                                                                                                                                                                                                                                                                                                                                                                     |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Current time**: Time zone, date and time, day of the week, week number, and UTC offset                                                                                      | <mark style="color:blue;">Use System Time in Responses</mark> is enabled on the conversation platform, and a time zone is available                                                                                                                   | `timezone` in message metadata; if absent, the conversation platform's <mark style="color:blue;">Time Zone</mark> setting is used. Nothing is appended if neither is available. For time zone sources on each platform, see [How the Time Zone Is Determined](https://docs.maiagent.ai/build/conversation-settings/platform-settings/function-settings#timezone-resolution) in the user manual |
| **User name**                                                                                                                                                                 | <mark style="color:blue;">Use Sender Name in Responses</mark> is enabled on the conversation platform, and a name is available                                                                                                                        | The contact's name; for organization members chatting in the admin console, the member's name                                                                                                                                                                                                                                                                                                  |
| **Current location**: Coordinates and accuracy (when provided)                                                                                                                | <mark style="color:blue;">Use Location Information in Responses</mark> is enabled on the conversation platform, and the message includes `latitude` and `longitude`                                                                                   | Web Chat includes location with the message after obtaining browser geolocation permission; API callers supply it in message metadata                                                                                                                                                                                                                                                          |
| **User language**: Asks the model to respond in this language when it cannot determine the user's preferred language                                                          | The message includes a language                                                                                                                                                                                                                       | For messages created through Web Chat and the API, the platform uses `language` in metadata, then the request's `Accept-Language`, and finally the platform's default language if neither is available                                                                                                                                                                                         |
| **Contact custom attributes**                                                                                                                                                 | The contact has custom attributes, or message metadata contains custom keys                                                                                                                                                                           | The contact's custom attributes plus the message's metadata (message values take precedence for matching keys). Reserved keys such as `timezone`, `latitude`, `longitude`, `accuracy`, `locale`, `language`, and `contact_name` are excluded. For how Web Chat injects page context, see [Injecting Page Context into Web Chat](/tech/en/serve/web-chat-sdk/web-chat-context-data.md)          |
| **Organization member attributes**                                                                                                                                            | The sender is an organization member with custom attributes configured                                                                                                                                                                                | The member's custom attributes within the organization. See [Personal Profile: Custom Attributes](https://docs.maiagent.ai/org/overview/custom-attributes) in the user manual                                                                                                                                                                                                                  |
| **Knowledge base guidance**: Asks the model to search the knowledge base before asking the user follow-up questions when the question might be answered by the knowledge base | Agent mode, with knowledge bases available for this conversation                                                                                                                                                                                      | The number of knowledge bases attached to the Agent                                                                                                                                                                                                                                                                                                                                            |
| **Greeting and greeting options**                                                                                                                                             | In normal mode, the greeting is appended when the conversation has one; when <mark style="color:blue;">Include Greeting Options in Agent Context</mark> is enabled in Web Chat, the greeting and numbered conversation starter questions are appended | The greeting and conversation starter questions actually sent in the conversation. See [Include Greeting Options in Agent Context](https://docs.maiagent.ai/build/conversation-settings/platform-settings/interaction-settings#include-greeting-in-context) in the user manual                                                                                                                 |
| **Attachment handling guidance**: Which tool to use to read attachments uploaded by the user                                                                                  | Agent mode                                                                                                                                                                                                                                            | Attachment tools enabled for the Agent                                                                                                                                                                                                                                                                                                                                                         |
| **Code Interpreter usage guidance**                                                                                                                                           | Agent mode, with Code Interpreter enabled for the Agent                                                                                                                                                                                               | The platform's built-in usage rules. See [Code Interpreter](https://docs.maiagent.ai/build/agent/code-interpreter) in the user manual                                                                                                                                                                                                                                                          |
| **Available skills list**: Each skill's name and when to use it                                                                                                               | Skills are bound to the Agent                                                                                                                                                                                                                         | Each skill's usage conditions (or its description if none are provided) are supplied to the model along with the skill expansion tool's description. The full instructions are loaded only when the model expands the skill. See [Skill Modules](/tech/en/advanced-genai-tech/skill.md)                                                                                                        |

Appended blocks begin with fixed English headings, such as `Current time information`, `Current user information`, `Current location`, `Contact custom attributes`, and `Organization member attributes`. You can reference these headings directly when asking the model to use this information in your system prompt. For example: "If Contact custom attributes contains productId, the user is browsing that product. Look up the product using this ID first."

{% hint style="info" %}
When using a model that supports prompt caching, time and location information that changes with each response is instead wrapped in a `<realtime_context>` block and placed after the last message. This prevents the preceding cache from being invalidated on every response. The content is the same as in the table above; only its placement differs.
{% endhint %}

## Conditional Notices <a href="#conditional-notices" id="conditional-notices"></a>

The following notices appear only in specific situations to prevent the model from inventing information when its capabilities are limited:

* **User specifies a skill or tool**: When the user specifies a skill or tool in the message, the model is instructed to use the specified item before answering.
* **User selects reference documents**: When reference documents are selected in MaiGPT, the model is instructed to search the selected knowledge bases first. Only if no answer is found should it use other tools or general knowledge, and it must explain that the selected documents do not contain the answer.
* **Knowledge bases temporarily unavailable**: When all knowledge base connections fail, the model is instructed to ask the user to try again later. It must not answer from memory when the content should come from the knowledge bases.
* **Reranker skipped due to insufficient quota**: When Reranker is enabled for the Agent but skipped because the organization has insufficient Credits, the model is told that the retrieved results may be ranked less accurately this time.
* **Member role disables some built-in features**: In MaiGPT, when a member's role lacks permission to use certain built-in features, the model is told which features are unavailable.

## Considerations When Writing a System Prompt <a href="#writing-implications" id="writing-implications"></a>

* **Do not hard-code dates or times in the system prompt.** If time is needed, enable <mark style="color:blue;">Use System Time in Responses</mark>. Hard-coded dates will conflict with the time appended by the system.
* **Do not write changing user data into the system prompt.** Let the appended context in the table above supply data such as names, locations, and membership tiers. The system prompt should only specify how to use that data when it is available.
* **Make sure you enable the settings on the conversation platform the user actually uses.** The time, name, and location toggles are configured separately for each conversation platform. For example, if the issue occurs on LINE, enable the toggles for the LINE platform.
* **Do not use the system prompt to control who can see which documents.** See the next section.

## Control Document Visibility with Query Metadata Rather Than the System Prompt <a href="#access-control-with-query-metadata" id="access-control-with-query-metadata"></a>

A system prompt can only influence how AI uses content that has already been retrieved; it cannot block retrieval itself. Even if the system prompt says "Regular customers must not refer to internal documents," those documents are still retrieved and sent into the LLM's context. The AI may still cite them, or prompt injection may induce it to disclose them.

To restrict which users can retrieve which documents, use [Query Metadata](/tech/en/identity-and-access/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan.md). Set retrievable knowledge bases, documents, and tag conditions on contacts, conversations, or messages. The system filters by these conditions during retrieval, so documents outside the permitted scope are neither retrieved nor sent to the LLM. For conditions such as access levels, label documents with knowledge base tags, then control access using tag conditions in Query Metadata.

{% hint style="warning" %}
Use system prompts to define tone, response workflows, and priorities. Any requirement that certain people must not see certain data must be handled through Query Metadata. For other safeguards enforced by the system, see [AI Safety Guardrails](/tech/en/advanced-genai-tech/guardrails.md).
{% endhint %}

## Related Resources <a href="#related-resources" id="related-resources"></a>

* [System Prompt Design Guide](https://docs.maiagent.ai/build/agent/system-prompt): Writing guidance, templates, and examples
* [Function Settings: AI Awareness Settings](https://docs.maiagent.ai/build/conversation-settings/platform-settings/function-settings#ai-awareness): Admin console steps for the time, name, and location toggles
* [Injecting Page Context into Web Chat](/tech/en/serve/web-chat-sdk/web-chat-context-data.md): Passing contact custom attributes from a web page
* [Query Metadata](https://docs.maiagent.ai/org/querymetadata): Restricting which documents users can retrieve


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/tech/en/advanced-genai-tech/system-prompt.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.