System Prompt 实战指南：Agent 开发中的角色设定、能力边界与限制条件设计

我在刚开始接触 AI Agent 开发时，最困惑的不是模型调参，而是 System Prompt 到底该怎么写。花了一周时间踩坑后，我发现一套可以直接复用的设计框架。今天把经验分享给你，帮你少走弯路。

本文使用 HolySheheep AI 作为演示平台，国内直连延迟<50ms，新用户注册即送免费额度，适合练手。

一、什么是 System Prompt？为什么它决定 Agent 的表现？

System Prompt（系统提示词）是给 AI 的“身份说明书”，在每次对话中优先级最高，决定了 AI 的角色定位、行为边界和输出风格。你可以把它理解为：

• 设定 AI 是“谁”（角色）
• 告诉 AI 能“做什么”和“不能做什么”（能力边界）
• 规定 AI “怎么说话”（输出格式）

我第一次写 System Prompt 时，只写了一句话：“你是一个助手”，结果 AI 什么都能聊，完全不可控。后来才明白，好的 System Prompt 必须包含角色、能力、限制三个维度。

二、三段式 System Prompt 设计框架

1. 角色设定（Role Definition）

明确告诉 AI 它扮演什么角色，这会影响它的知识背景和表达风格。

# 基础角色设定示例
SYSTEM_PROMPT = """
你是一名拥有10年经验的高级 Python 后端工程师，擅长 Django、FastAPI 框架。
你的说话风格专业但易懂，喜欢用代码示例解释概念。
"""

更具体的角色设定
SYSTEM_PROMPT = """
你是【代码审查助手】，一个专门帮助初级开发者提升代码质量的专业工具。
- 熟悉 PEP8 规范
- 了解中国互联网公司的代码风格偏好
- 善于发现潜在的 Bug 和性能问题
"""

2. 能力边界（Capability Boundaries）

明确 AI 能做什么、不能做什么，避免它“超纲发挥”。

SYSTEM_PROMPT = """
你是【电商客服助手】，你的能力边界如下：

✅ 你可以：
- 回答商品信息、库存、价格相关问题
- 处理退换货流程咨询
- 引导用户使用优惠券

❌ 你不能：
- 修改订单金额
- 泄露其他用户的订单信息
- 提供不在商品页范围内的信息
- 进行任何涉及资金的敏感操作
"""

3. 限制条件（Constraints）

设置硬性限制，确保 AI 输出安全、合规、可控。

SYSTEM_PROMPT = """
【重要限制】

1. 回答格式限制：
   - 所有回答必须使用 Markdown 格式
   - 代码块必须标注语言类型
   - 列表项不超过 5 条

2. 安全限制：
   - 遇到敏感词，自动替换为 ****
   - 不讨论政治、宗教等话题
   - 发现疑似诈骗内容，立即终止并提示用户

3. 交互限制：
   - 单次回复不超过 500 字
   - 如果无法回答，明确说“我不确定”而不是瞎编
"""

三、使用 HolySheheep API 调用 Agent（完整代码示例）

下面是我在项目中实际使用的代码，基于 HolySheheep AI 平台，价格透明且支持微信/支付宝充值：

import requests
import json

HolySheheep API 配置
API_KEY = "YOUR_HOLYSHEEP_API_KEY"  # 替换为你的实际 Key
BASE_URL = "https://api.holysheep.ai/v1"

定义完整的 System Prompt
system_prompt = """你是【技术文档助手】，专门帮助开发者撰写和优化技术文档。

【角色设定】
- 你是拥有 8 年技术写作经验的文档专家
- 熟悉各类 API 文档、README、开发指南的撰写规范
- 善于用通俗语言解释复杂技术概念

【能力边界】
✅ 可以：
- 帮助撰写 API 接口文档
- 提供代码示例和最佳实践
- 优化已有文档的结构和表达

❌ 不能：
- 编写完整的业务代码
- 提供非技术相关的写作帮助
- 生成涉及版权的内容

【输出格式】
- 使用 Markdown 格式输出
- 包含清晰的标题层级
- 代码块必须标注语言
"""

def chat_with_agent(user_message, model="gpt-4.1"):
    """调用 HolySheheep API 进行对话"""
    
    url = f"{BASE_URL}/chat/completions"
    
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    }
    
    payload = {
        "model": model,
        "messages": [
            {"role": "system", "content": system_prompt},
            {"role": "user", "content": user_message}
        ],
        "temperature": 0.7,
        "max_tokens": 1000
    }
    
    try:
        response = requests.post(url, headers=headers, json=payload, timeout=30)
        response.raise_for_status()
        
        result = response.json()
        return result["choices"][0]["message"]["content"]
    
    except requests.exceptions.Timeout:
        return "请求超时，请检查网络连接"
    except requests.exceptions.RequestException as e:
        return f"请求失败: {str(e)}"

使用示例
if __name__ == "__main__":
    user_input = "帮我写一个 Python 函数的文档字符串"
    response = chat_with_agent(user_input)
    print(response)

四、高级技巧：动态 System Prompt 与上下文管理

在实际项目中，我发现固定 System Prompt 往往不够用，需要根据场景动态调整。以下是我常用的三种模式：

模式一：基于用户输入切换角色

def get_dynamic_system_prompt(user_intent):
    """根据用户意图动态选择 System Prompt"""
    
    prompt_templates = {
        "code_review": """
        你是一名严格的代码审查员，专门做代码质量审计。
        发现问题时，必须给出具体代码修改建议。
        """,
        
        "tutorial": """
        你是一名耐心的技术导师，擅长循序渐进地教学。
        每讲一个概念后，主动确认学生是否理解。
        """,
        
        "debug": """
        你是一名经验丰富的 Debug 专家。
        遇到错误时，先定位问题根源，再给出解决方案。
        """
    }
    
    # 提取关键词判断意图
    if "review" in user_intent or "审查" in user_intent:
        return prompt_templates["code_review"]
    elif "怎么" in user_intent or "教程" in user_intent:
        return prompt_templates["tutorial"]
    else:
        return prompt_templates["debug"]

调用时
system_prompt = get_dynamic_system_prompt(user_message)

模式二：注入对话历史上下文

def build_contextual_system_prompt(conversation_history):
    """基于对话历史构建增强版 System Prompt"""
    
    base_prompt = """你是【智能助手】，请根据对话历史保持一致性。"""
    
    # 添加上下文摘要
    context_summary = f"""
    
    【对话历史摘要】
    - 用户之前询问了 {len(conversation_history)} 个问题
    - 当前对话主题：{conversation_history[-1]['topic'] if conversation_history else '新对话'}
    - 用户偏好：{conversation_history[-1].get('preference', '无特殊偏好') if conversation_history else '无特殊偏好'}
    """
    
    return base_prompt + context_summary

五、我的实战经验总结

我在使用 HolySheheep AI 开发客服机器人的过程中，总结出以下心得：

1. System Prompt 要“具体”不要“模糊”

我曾经写“尽量保持回答简洁”，结果 AI 时长时短。后来改成“回答必须控制在 100-200 字之间”，效果立竿见影。

2. 用示例教 AI 理解格式

文字描述不够直观时，我会直接给出输入-输出示例：

SYSTEM_PROMPT = """
当用户询问天气时，必须按以下格式回复：

示例：
用户：北京今天天气怎么样？
助手：🌤️ 北京今天晴，温度 15-25°C，适合出行。

【禁止】
- 只回复"天气不错"
- 使用非结构化文本
"""

3. 限制条件要“正向”表述

我发现用“应该/不应该”比“禁止/不允许”效果更好，AI 理解更准确，执行更稳定。

目前 HolySheheep 平台的 GPT-4.1 价格为 $8/MTok，Claude Sonnet 4.5 为 $15/MTok，DeepSeek V3.2 仅为 $0.42/MTok。用 System Prompt 调优好模型后，成本控制会明显改善。

常见报错排查

报错一：401 Authentication Error

# 错误信息
{"error": {"message": "Incorrect API key provided", "type": "invalid_request_error"}}

原因
API Key 填写错误或格式不对

解决方案
1. 检查 Key 是否包含前后空格
2. 确认使用的是 HolySheheep 的 Key，不是其他平台
3. 去 https://www.holysheep.ai/register 检查 Key 是否有效

正确格式：
API_KEY = "sk-holysheep-xxxxx"  # 不带引号空格

报错二：400 Invalid Request - Too Many Tokens

# 错误信息
{"error": {"message": "This model's maximum context length is 4096 tokens", "type": "invalid_request_error"}}

原因
System Prompt + 对话历史 + 本次输入 超过模型上下文限制

解决方案
1. 精简 System Prompt，删除冗余描述
2. 限制对话历史长度，只保留最近 5-10 轮
3. 使用 max_tokens 参数限制输出长度

推荐做法
payload = {
    "model": "gpt-4.1",
    "messages": [
        {"role": "system", "content": "精简版 System Prompt"},  # 控制在 500 字内
        {"role": "user", "content": user_message[-2000:]}  # 截取最近内容
    ],
    "max_tokens": 500  # 限制输出
}

报错三：503 Service Unavailable

# 错误信息
{"error": {"message": "The model is currently overloaded", "type": "server_error"}}

原因
HolySheheep 平台高负载或模型暂时不可用

解决方案
1. 等待 5-10 秒后重试
2. 切换到备用模型（DeepSeek V3.2）
3. 检查平台状态页 https://status.holysheep.ai

备用方案代码
def chat_with_fallback(user_message):
    models = ["gpt-4.1", "deepseek-v3.2"]  # 降级列表
    
    for model in models:
        try:
            return chat_with_agent(user_message, model=model)
        except Exception as e:
            if "overloaded" in str(e):
                continue
            raise
    return "所有模型暂时不可用，请稍后再试"

报错四：网络超时 Connection Timeout

# 错误信息
requests.exceptions.ReadTimeout: HTTPSConnectionPool ... Read timed out

原因
网络不稳定或请求过大

解决方案
1. 增加 timeout 参数
2. 优化 System Prompt，减少 token 数量
3. 使用国内优化的 HolySheheep 节点（延迟 <50ms）

response = requests.post(
    url, 
    headers=headers, 
    json=payload, 
    timeout=60  # 增加到 60 秒
)

六、快速开始清单

• ✅ 注册 HolySheheep AI 获取 API Key
• ✅ 使用 base_url: https://api.holysheep.ai/v1
• ✅ 按“角色-能力-限制”三段式结构编写 System Prompt
• ✅ 重要回复处添加输出格式示例
• ✅ 添加错误处理和超时配置
• ✅ 测试时先用 DeepSeek V3.2（$0.42/MTok）节省成本

System Prompt 的设计是一个迭代优化的过程。我的建议是：先写一版能用的，测试后再根据问题逐步调优。坚持这个方法，你也能快速构建出表现稳定的 AI Agent。

👉 免费注册 HolySheheep AI，获取首月赠额度