Improve system prompt structure with XML-like blocks

[EmilyCheoh]

Addresses #8612

This PR improves the structure of the generated main agent system prompt by adding explicit section boundaries for different types of instructions.

Currently, multiple instruction sections are appended into the same system_prompt, including persona instructions, skills, runtime environment instructions, workspace extra prompts, knowledge base results, and tool-use instructions. Some sections already have headings, while others are appended directly.

This change wraps these sections in explicit XML-like blocks so the final system prompt is easier to read, inspect, and reason about. It also helps distinguish persona / role instructions from operational instructions such as tool-use and runtime environment rules.

Modifications / 改动点

• Added a helper function for wrapping system prompt sections with explicit block tags.

• Wrapped persona prompts in <persona_instructions>.

• Wrapped skills prompts in <available_skills>.

• Wrapped runtime environment prompts in <runtime_environment>.

• Wrapped workspace runtime rules in <workspace_runtime_rule>.

• Wrapped workspace extra prompts in <workspace_extra_prompt>.

• Wrapped knowledge base results in <related_knowledge_base_results>.

• Wrapped tool-use prompts in <tool_use_instructions>.

• Wrapped safety prompts in <safety_instructions>.

• Wrapped sandbox, live mode, and subagent routing prompts in their own explicit blocks.

• Preserved the original prompt content and existing runtime behavior.

• This is NOT a breaking change. / 这不是一个破坏性变更。

Screenshots or Test Results / 运行截图或测试结果

This PR only changes prompt formatting / section boundaries. It does not change tool registration, provider selection, conversation history handling, knowledge base retrieval behavior, sandbox/local runtime behavior, or agent runner logic.

Python syntax check passed:

python3 -m py_compile astrbot/core/agent/main_agent.py

Sample of new system format now:

<persona_instructions>
You are Noir, a black cyber-cat with blue eyes [...]
</persona_instructions>

<runtime_environment>
You have access to the host local environment and can execute shell commands and Python code. Current operating system: Linux. The runtime shell is Unix-like. Use POSIX-compatible shell commands.
</runtime_environment>

<workspace_runtime_rule>
Current workspace you can use: `/AstrBot/data/workspaces/placeholder`
Unless the user explicitly specifies a different directory, perform all file-related operations in this workspace.
</workspace_runtime_rule>

<tool_use_instructions>
When using tools: never return an empty response [...]
</tool_use_instructions>

---

Checklist / 检查清单

• 😊 If there are new features added in the PR, I have discussed it with the authors through issues/emails, etc.
  / 如果 PR 中有新加入的功能，已经通过 Issue / 邮件等方式和作者讨论过。

• 👀 My changes have been well-tested, and "Verification Steps" and "Screenshots" have been provided above.
  / 我的更改经过了良好的测试，并已在上方提供了“验证步骤”和“运行截图”。

• 🤓 I have ensured that no new dependencies are introduced, OR if new dependencies are introduced, they have been added to the appropriate locations in requirements.txt and pyproject.toml.
  / 我确保没有引入新依赖库，或者引入了新依赖库的同时将其添加到 requirements.txt 和 pyproject.toml 文件相应位置。

• 😮 My changes do not introduce malicious code.
  / 我的更改没有引入恶意代码。

Summary by Sourcery

Structure the main agent system prompt into clearly delimited XML-like sections to make different instruction types easier to read and reason about.

Enhancements:

• Introduce a helper to wrap system prompt fragments in named XML-like blocks for consistent section delimiting.
• Group persona, skills, runtime environment, workspace rules/extra prompts, sandbox/live mode guidance, subagent routing, and safety instructions into dedicated tagged sections in the system prompt.
• Encapsulate knowledge base results and tool-use guidance in explicit blocks without changing existing runtime behavior or tool wiring.

[sourcery-ai]

Hey - I've left some high level feedback:

• There are several repeated patterns like req.system_prompt = f"{req.system_prompt or ''}" followed by req.system_prompt += _wrap_system_block(...); consider adding a small helper to append wrapped blocks to the system prompt to avoid repetition and reduce chances of subtle inconsistencies.
• The tag names passed into _wrap_system_block are all inline string literals (e.g., "persona_instructions", "sandbox_mode_instructions"); centralizing them as constants or an enum-like structure would make it easier to keep them consistent and refactor in the future.
• In _apply_llm_safety_mode, the safety block is prepended with an extra "\n" before the existing system prompt, whereas other blocks are typically appended directly; it may be worth aligning this newline behavior with the rest of the block appends for consistent formatting.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- There are several repeated patterns like `req.system_prompt = f"{req.system_prompt or ''}"` followed by `req.system_prompt += _wrap_system_block(...)`; consider adding a small helper to append wrapped blocks to the system prompt to avoid repetition and reduce chances of subtle inconsistencies.
- The tag names passed into `_wrap_system_block` are all inline string literals (e.g., `"persona_instructions"`, `"sandbox_mode_instructions"`); centralizing them as constants or an enum-like structure would make it easier to keep them consistent and refactor in the future.
- In `_apply_llm_safety_mode`, the safety block is prepended with an extra `"\n"` before the existing system prompt, whereas other blocks are typically appended directly; it may be worth aligning this newline behavior with the rest of the block appends for consistent formatting.

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[gemini-code-assist]

Code Review

This pull request introduces a helper function _wrap_system_block to wrap system prompt fragments with XML-like boundaries, and refactors several locations in astrbot/core/astr_main_agent.py to use this helper. The review feedback highlights a potential TypeError when appending to req.system_prompt if it is None in build_main_agent. Additionally, the reviewer suggests simplifying several redundant double assignments where req.system_prompt is first set to a string representation of itself and then appended to, recommending a single-statement approach instead.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.