> 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/ai-agents/system-prompt.md).

# System Prompt

Last updated: 2025-11-14

## Overview

The system prompt defines an AI assistant's behavior and response style. A carefully designed system prompt enables an AI assistant to assume a specific role, follow specific rules, and answer questions in a way that meets your business needs.

Include the AI assistant's role description and instructions, including the rules and SOPs it should follow when responding. Think of these as rules that must be followed for every response. Include only the essentials, as an excessive number of instructions may overwhelm the AI and cause it to disregard some rules. Store large amounts of data, or data that only needs to be retrieved when a related question is asked, in the knowledge base.

## Metadata Processing

### What Is Metadata?

Metadata is additional information that describes knowledge base documents, such as:

* Document category
* Creation date
* Author information
* Permission labels
* Other custom attributes

In a RAG (retrieval-augmented generation) system, metadata plays an important role by helping the AI assistant filter and use knowledge base content more precisely.

### Optimized Metadata Exclusion Logic

The MaiAgent platform has optimized its metadata processing logic to ensure that the system handles metadata more accurately.

#### Improvements

**Removed duplicate exclusion logic**

In previous versions, the system might repeatedly check and exclude certain metadata keys, causing unnecessary performance overhead. The new version removes this duplicate logic to ensure:

* **Improved processing efficiency**: Reduces repeated checks
* **Clearer logic**: Prevents the same exclusion rules from running multiple times
* **Better maintainability**: Simplifies the code structure

**Scope of impact**

This optimization primarily affects the system's internal metadata processing. For users:

* ✅ Metadata filtering continues to work normally
* ✅ Retrieval performance is improved
* ✅ Answer accuracy remains consistent
* ✅ No changes to existing settings are required

### Using Metadata in System Prompts

#### Basic Usage

In a system prompt, you can instruct the AI assistant how to use metadata:

```
You are a professional customer service assistant. When answering questions:
1. Prioritize documents labeled as "official"
2. If no official document is found, refer to documents labeled as "community"
3. Always state the category of the information source in your answer
```

#### Advanced Metadata Usage

**Permission management**

```
Only use documents appropriate for the user's permission level:
- VIP customers: May reference all documents
- General customers: May only reference documents labeled "public"
- New customers: May only reference documents in the "basic" category
```

**Recency control**

```
Follow these rules when answering questions:
1. Prioritize documents updated within the last three months
2. If you use an older document, state in your answer that the latest information may need to be verified
3. Ignore documents labeled "archived"
```

**Multilingual support**

```
Select documents based on the user's language preference:
- Traditional Chinese users: Use documents with lang="zh-TW"
- English users: Use documents with lang="en"
- If the corresponding language is unavailable, use the default language and explain this
```

## Metadata Best Practices

### 1. Define a Clear Metadata Structure

Create a standardized metadata schema:

```json
{
  "category": "product-info",
  "language": "zh-TW",
  "access_level": "public",
  "last_updated": "2025-11-14",
  "status": "active"
}
```

### 2. Clearly Describe Metadata Usage Rules in the System Prompt

```
# Document Usage Rules

## Priority
1. status = "active" and access_level matches the user's permissions
2. category matches the question topic
3. last_updated is within the last six months

## Exclusion Rules
- Ignore documents where status = "draft"
- Ignore documents with an access_level higher than the user's permissions
```

### 3. Review Metadata Settings Regularly

* Confirm that metadata categories meet actual usage requirements
* Check for unused metadata keys
* Evaluate the impact of metadata on retrieval performance

## Technical Details

### Metadata Processing Flow

```
1. The user asks a question
   ↓
2. The system parses the question and extracts key information
   ↓
3. Candidate documents are filtered based on metadata
   ↓
4. The retrieval system finds the most relevant document excerpts
   ↓
5. The LLM generates an answer based on the system prompt and retrieval results
```

### Performance Considerations

* **Indexing**: Metadata is indexed when a file is uploaded
* **Query efficiency**: Simple metadata filtering usually completes within milliseconds
* **Complex queries**: Metadata filtering with multiple conditions may take longer

### System Limitations

* No more than 20 metadata keys are recommended for each document
* Use short strings or numbers for metadata values
* Avoid storing large amounts of text in metadata

## System Prompt Example

<mark style="color:orange;">You are a professional XXX AI assistant.</mark>

\ <mark style="color:blue;">You should (enhance responses):</mark>

1. <mark style="color:blue;">Provide clear, accurate, and helpful answers</mark>
2. <mark style="color:blue;">Maintain a friendly and professional conversational tone</mark>
3. <mark style="color:blue;">Answer in the user's language; use Traditional Chinese when answering in Chinese</mark>
4. <mark style="color:blue;">Avoid giving harmful or inappropriate advice</mark>
5. <mark style="color:blue;">Respect user privacy and do not disclose sensitive information</mark>
6. <mark style="color:blue;">Use correct Traditional Chinese in responses</mark>
7. <mark style="color:blue;">Adjust the level of detail based on the context</mark>
8. <mark style="color:blue;">Provide additional suggestions or related information when appropriate</mark>
9. <mark style="color:blue;">Before answering, confirm that the user has provided sufficiently clear information; answer only after it is clear</mark>
10. <mark style="color:blue;">Use examples when appropriate to explain complex concepts</mark>

<mark style="color:red;">You should not (response restrictions):</mark>

1. <mark style="color:red;">Spread misinformation or unverified claims</mark>
2. <mark style="color:red;">Make biased or discriminatory statements</mark>
3. <mark style="color:red;">Discuss illegal or inappropriate content</mark>
4. <mark style="color:red;">Pretend to be a real person</mark>
5. <mark style="color:red;">Exceed the AI assistant's capabilities</mark>
6. <mark style="color:red;">For questions outside the scope of the knowledge base, reply, "Sorry, I am currently unable to answer this question"</mark>

## System Prompt Template

```yaml
# Persona
(Describe the AI assistant's role)

# Context
(Describe the task background)

# Task
## Input
(Describe the data that will be provided)

## Output
(Describe the output, including its format or tone; you may also provide a Template)

<template>
...
</template>

# Instructions
(Describe the task steps)

1. ...
2. ...
3. ...
...

# Example
(Provide 1–3 output examples)

<example>
...
</example>

<example>
...
</example>

...

# Constraints
(Describe the output restrictions)

1. ...
2. ...
3. ...
...
```

## Related Resources

* [System Prompt Design Guide](https://docs.maiagent.ai/build/system-prompt)
* [Document Management: Tags and Metadata](https://docs.maiagent.ai/km/tags-and-metadata)
* [Query Metadata](https://docs.maiagent.ai/org/querymetadata)

{% hint style="info" %}
[AI System Prompt Generator](https://chat.maiagent.ai/web-chats/4b67b140-db5f-40dc-bce3-f2217e9574bd)
{% endhint %}


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.