> 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/advanced-genai-tech/system-prompt.md).

# 角色指令

Agent 每次回覆前，平台會在您寫的角色指令後面自動附加哪些情境（時間、使用者名稱、位置、語系、聯絡人與成員屬性、知識庫與技能提示等），各由哪個設定控制，以及寫角色指令時該怎麼引用。寫法與範本見使用者手冊。

最後更新：2026-10-04

角色指令（System Prompt）是您寫給 Agent、每次回覆都要遵守的規則。怎麼寫、模板與範例，請看使用者手冊的[角色指令設計指南](https://docs.maiagent.ai/build/agent/system-prompt)。

本頁說明另一半：平台在每次回覆前，會依 Agent 與對話平台的設定，自動把一些「當下情境」接在角色指令後面，一起送給模型。這些內容由系統每次重新產生，不需要、也不應該寫死在角色指令裡。

## 送給模型的系統提示怎麼組成 <a href="#prompt-assembly" id="prompt-assembly"></a>

每次回覆時，平台依序組合：

1. **您寫的角色指令**。群組對話會先放平台的群組對話指令，再接您的角色指令。
2. **引用標記指示**：Agent 開啟 <mark style="color:blue;">啟用內嵌引用功能</mark> 時，附上在回覆中插入 `[1][2]` 引用標記的規則。
3. **平台附加的情境**：時間、使用者名稱、位置、語系、自訂屬性等，見[下一節](#platform-context)。
4. **依情況附加的提示**：例如使用者指定了技能、知識庫暫時無法使用，見[依情況附加的提示](#conditional-notices)。

附加的內容只在當次回覆使用，不會寫回 Agent 的角色指令設定。

## 平台附加的情境 <a href="#platform-context" id="platform-context"></a>

| 附加的內容                                   | 什麼時候附加                                                                                               | 值從哪裡來                                                                                                                                                                                                                             |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **目前時間**：時區、日期時間、星期、週次、UTC 偏移           | 對話平台開啟 <mark style="color:blue;">使用系統時間回答</mark>，且取得到時區                                              | 訊息 metadata 的 `timezone`；沒帶時用對話平台的 <mark style="color:blue;">時區</mark> 設定。兩者都沒有就不附加。各平台的時區來源見使用者手冊[時區怎麼決定](https://docs.maiagent.ai/build/conversation-settings/platform-settings/function-settings#timezone-resolution)          |
| **使用者名稱**                               | 對話平台開啟 <mark style="color:blue;">使用傳送者名稱回答</mark>，且有名稱                                               | 聯絡人名稱；組織成員在後台對話時為成員名稱                                                                                                                                                                                                             |
| **目前位置**：座標，以及精確度（有提供時）                 | 對話平台開啟 <mark style="color:blue;">使用位置資訊回答</mark>，且訊息帶有 `latitude`、`longitude`                        | Web Chat 取得瀏覽器定位授權後隨訊息帶入；API 由呼叫端放在訊息 metadata                                                                                                                                                                                    |
| **使用者語系**：請模型在無法判斷使用者偏好語言時，以這個語系回答      | 訊息帶有語系                                                                                               | Web Chat 與 API 建立的訊息，依序取 metadata 的 `language`、請求的 `Accept-Language`，再沒有就用平台預設語言                                                                                                                                                  |
| **聯絡人自訂屬性**                             | 聯絡人有自訂屬性，或訊息 metadata 帶有自訂的鍵                                                                         | 聯絡人的自訂屬性，加上該則訊息的 metadata（同名時以訊息為準）。`timezone`、`latitude`、`longitude`、`accuracy`、`locale`、`language`、`contact_name` 等保留鍵不列入。Web Chat 注入頁面 context 的方式見 [Web Chat 注入頁面 Context](/tech/serve/web-chat-sdk/web-chat-context-data.md) |
| **組織成員屬性**                              | 傳送者是組織成員，且成員設有自訂屬性                                                                                   | 成員在組織內的自訂屬性，見使用者手冊[個人資料：自訂屬性](https://docs.maiagent.ai/org/overview/custom-attributes)                                                                                                                                            |
| **知識庫提示**：請模型在問題可能由知識庫回答時，先搜尋知識庫再向使用者追問 | Agent 模式，且這次對話有可用的知識庫                                                                                | Agent 掛載的知識庫數量                                                                                                                                                                                                                    |
| **開場白與開場選項**                            | 一般模式下，對話有開場白時附上開場白；Web Chat 開啟 <mark style="color:blue;">開場白選項納入 Agent 上下文</mark> 時，附上開場白與編號後的對話開始問題 | 對話實際送出的開場白與對話開始問題，見使用者手冊[開場白選項納入 Agent 上下文](https://docs.maiagent.ai/build/conversation-settings/platform-settings/interaction-settings#include-greeting-in-context)                                                              |
| **附件處理指引**：使用者上傳附件時，該用哪個工具讀取            | Agent 模式                                                                                             | Agent 啟用的附件工具                                                                                                                                                                                                                     |
| **Code Interpreter 使用指引**               | Agent 模式，且 Agent 開啟 Code Interpreter                                                                 | 平台內建的使用規則，見使用者手冊 [Code Interpreter](https://docs.maiagent.ai/build/agent/code-interpreter)                                                                                                                                        |
| **可用技能清單**：每個技能的名稱與使用時機                 | Agent 綁定了技能                                                                                          | 技能的使用時機（沒填時用描述），隨技能展開工具的說明一起提供給模型；完整指令要等模型展開技能才載入，見 [Skill 技能模組](/tech/advanced-genai-tech/skill.md)                                                                                                                              |

附加的區塊以固定的英文標題開頭，例如 `Current time information`、`Current user information`、`Current location`、`Contact custom attributes`、`Organization member attributes`。在角色指令裡要求模型使用這些資訊時，可以直接引用這些標題，例如「Contact custom attributes 中有 productId 時，代表使用者正在瀏覽該商品，請先以這個 ID 查詢商品」。

{% hint style="info" %}
使用支援提示快取（prompt caching）的模型時，每次都會變動的時間與位置會改包在 `<realtime_context>` 區塊，放到最後一則訊息之後，避免每次回覆都讓前面的快取失效。內容與上表相同，只是位置不同。
{% endhint %}

## 依情況附加的提示 <a href="#conditional-notices" id="conditional-notices"></a>

以下提示只在特定情況出現，用來避免模型在能力受限時自行編造：

* **使用者指定技能或工具**：使用者在這則訊息指定了技能或工具時，要求模型先使用指定的項目再回答。
* **使用者選定參考文件**：在 MaiGPT 勾選參考文件時，要求模型先搜尋選定的知識庫，查不到才改用其他工具或一般知識，並說明選定的文件沒有答案。
* **知識庫暫時無法使用**：所有知識庫都連線失敗時，要求模型告知使用者稍後再試，不得憑記憶回答原本應來自知識庫的內容。
* **額度不足而略過 Reranker**：Agent 開啟 Reranker、但組織 Credits 不足而略過時，告知模型這次的檢索結果排序可能較不精準。
* **成員角色停用了部分內建功能**：MaiGPT 中，成員的角色沒有某些內建功能的使用權限時，告知模型哪些功能不可用。

## 寫角色指令時要注意 <a href="#writing-implications" id="writing-implications"></a>

* **不要在角色指令寫死日期或時間。** 需要時間就開 <mark style="color:blue;">使用系統時間回答</mark>；寫死的日期會和系統附加的時間互相矛盾。
* **不要把會變動的使用者資料寫進角色指令。** 名稱、所在位置、會員等級這類資料，交給上表的附加情境帶入；角色指令只寫「拿到這些資料時要怎麼用」。
* **確認開的是使用者實際在用的對話平台。** 時間、名稱、位置三個開關各對話平台分開設定，例如問題發生在 LINE，就要開 LINE 平台的開關。
* **不要用角色指令控管誰看得到哪些文件**，見下一節。

## 文件可見範圍用 Query Metadata 控管，不要寫在角色指令 <a href="#access-control-with-query-metadata" id="access-control-with-query-metadata"></a>

角色指令只能影響 AI 如何使用「已經檢索到」的內容，擋不住檢索本身。在角色指令寫「一般客戶不可參考內部文件」，這些文件仍會被檢索出來、送進 LLM 的上下文，AI 可能照樣引用，也可能被提示詞注入誘導說出來。

要限制「哪位使用者查得到哪些文件」，請使用 [Query Metadata（查詢元資料）](/tech/identity-and-access/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan.md)：在聯絡人、對話或訊息上設定可檢索的知識庫、文件與標籤條件，系統在檢索時就依條件篩選，範圍外的文件不會被撈出，也不會進入 LLM。存取等級這類條件，請以知識庫標籤標示文件，再用 Query Metadata 的標籤條件控管。

{% hint style="warning" %}
角色指令適合規範語氣、回答流程與優先順序；凡是「某些人不能看到某些資料」的需求，一律用 Query Metadata 處理。其他由系統強制執行的防護機制見 [AI 安全防護機制](/tech/advanced-genai-tech/guardrails.md)。
{% endhint %}

## 相關資源 <a href="#related-resources" id="related-resources"></a>

* [角色指令設計指南](https://docs.maiagent.ai/build/agent/system-prompt)：寫法、模板與範例
* [功能設定：AI 感知設定](https://docs.maiagent.ai/build/conversation-settings/platform-settings/function-settings#ai-awareness)：時間、名稱、位置三個開關的後台操作
* [Web Chat 注入頁面 Context](/tech/serve/web-chat-sdk/web-chat-context-data.md)：從網頁帶入聯絡人自訂屬性
* [查詢元資料](https://docs.maiagent.ai/org/querymetadata)：限制使用者可檢索的文件


---

# 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/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.