模块3: 提示工程

提示是智能体的DNA。它定义了个性、能力、约束和决策风格。对于简单的聊天机器人，平庸的提示产生平庸的回答。对于智能体，平庸的提示产生错误的行动——而错误的行动会带来现实世界的后果。

想象一个管理数据库的智能体。如果系统提示没有明确禁止破坏性操作，智能体可能会认为 DROP TABLE users 是"清理"数据的合理方式。智能体的提示工程不是为了获得更好的文本——而是为了控制行为。

提示工程影响智能体行为的方方面面：

• 工具选择 — 调用哪个工具以及何时调用（错误的工具浪费时间和金钱）
• 多步骤推理 — 第一步的错误会在每个后续步骤中累积
• 安全边界 — 防止有害的、不可逆的或成本高昂的操作
• 输出格式 — 下游系统期望结构化数据，而非自由格式文本
• 成本效率 — 精心设计的提示减少不必要的工具调用和LLM迭代

每个有效的智能体提示都有四个组件，各自服务于不同目的。缺少任何一个都会导致可预见的失败模式。

以下是一个包含所有四个组件的完整示例：

system_prompt = """You are a financial research assistant specialising in
public company analysis.

CONTEXT:
- You have access to tools: search_sec_filings, get_stock_price, search_news.
- The user is a portfolio manager at an investment firm.
- Current date: 2026-03-28.

CONSTRAINTS:
- Never provide specific investment advice ("buy" / "sell" recommendations).
- Always cite your data sources with URLs or filing references.
- If data is older than 30 days, explicitly warn the user.
- If you are unsure, say so. Never fabricate financial data.

FORMAT:
- Use markdown for readability.
- Present numerical data in tables.
- End each response with a "Sources" section.
"""

角色声明

角色声明的作用不仅仅是设定人设。它激活了模型训练数据中特定领域的知识。"你是Python开发者"与"你是数据科学家"会产生不同的代码风格和库选择。请明确专业水平、领域和工作风格。

# Weak role statement
system_prompt = "You are a helpful assistant."

# Strong role statement
system_prompt = """You are a senior backend engineer specialising in Python
microservices. You follow PEP 8, write type hints, and prefer composition
over inheritance. You have deep experience with FastAPI, SQLAlchemy, and
PostgreSQL."""

系统提示是控制智能体行为最强大的杠杆。它随每次API调用一起发送，充当模型高优先级处理的持久指令集。对于智能体，系统提示必须远不止设定个性——它必须定义决策流程。

一个好的智能体系统提示需要回答以下问题：

• 身份：智能体是谁？它的专长是什么？
• 工具指导：何时使用每个工具？按什么顺序？
• 故障处理：当工具失败或返回意外结果时，智能体该怎么做？
• 语气和风格：智能体如何沟通？正式？随意？简洁？
• 升级：何时智能体应该停下来并请求用户帮助？

system_prompt = """You are a customer support agent for Acme Software.

IDENTITY:
- You are friendly, professional, and concise.
- You represent Acme Software and always act in the customer's best interest.

TOOLS (use in this priority order):
1. search_docs: Use FIRST for any product question. Always search before answering.
2. lookup_order: Use when the customer mentions an order number or shipping.
3. create_ticket: Use for bugs, feature requests, or issues you cannot resolve.

DECISION RULES:
- If search_docs returns no results, say "I don't have information on that"
  and offer to create a support ticket. NEVER guess at technical specifications.
- If the customer is frustrated, acknowledge their feelings before problem-solving.
- If you need information the customer hasn't provided, ask ONE clear question.

ESCALATION:
- Refund requests over $100: create a ticket tagged "manager-review".
- Security concerns: immediately create a ticket tagged "security-urgent".

FORMAT:
- Keep responses under 150 words unless the customer asks for details.
- Use bullet points for multi-step instructions.
"""

OpenAI vs Anthropic中的系统提示

两大供应商在API调用中处理系统提示的方式不同：

# OpenAI: system prompt is a message in the messages array
from openai import OpenAI
client = OpenAI()
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": system_prompt},   # <-- system message
        {"role": "user", "content": "How do I reset my password?"}
    ]
)

# Anthropic: system prompt is a separate parameter
import anthropic
client = anthropic.Anthropic()
message = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    system=system_prompt,                                # <-- separate param
    messages=[
        {"role": "user", "content": "How do I reset my password?"}
    ]
)

少样本提示提供期望的输入/输出行为示例。思维链（CoT）提示指导模型在给出最终答案之前逐步推理。这两种技术都能显著提高准确性，尤其是对于需要做出复杂决策的智能体。

少样本提示

与其描述你想要什么，不如展示给模型。这对于控制输出格式和决策模式特别有效：

system_prompt = """You are a data classification agent. Classify customer
messages into categories and extract key entities.

EXAMPLES:

Input: "My order #12345 hasn't arrived yet, it's been 2 weeks"
Output: {"category": "shipping_delay", "order_id": "12345",
         "urgency": "high", "action": "lookup_order"}

Input: "How do I change my subscription plan?"
Output: {"category": "account_management", "order_id": null,
         "urgency": "low", "action": "search_docs"}

Input: "Your app crashes every time I open the settings page"
Output: {"category": "bug_report", "order_id": null,
         "urgency": "medium", "action": "create_ticket"}
"""

思维链提示

CoT提示要求模型在行动之前"大声思考"。这对智能体至关重要，因为它使推理过程可见（且可调试）：

system_prompt = """You are a research assistant. When given a question,
reason through it step by step before taking any action.

REASONING PROCESS:
1. Identify what information you need to answer the question.
2. Determine which tools can provide that information.
3. Plan the order of tool calls (some may depend on earlier results).
4. Execute your plan, verifying each result before proceeding.
5. Synthesise the results into a clear answer.

IMPORTANT: Always show your reasoning in a <thinking> block before
taking action. This helps the user understand your approach.

Example reasoning:
<thinking>
The user wants to compare Q4 revenue for Apple and Microsoft.
I need: (1) Apple Q4 revenue, (2) Microsoft Q4 revenue.
I'll search SEC filings for both, then present a comparison table.
</thinking>
"""

少样本 + CoT的组合特别强大。提供包含推理过程的示例，模型将遵循相同的模式：

# Combining few-shot and chain-of-thought
messages = [
    {"role": "system", "content": "Solve math word problems step by step."},
    {"role": "user", "content": "A store has 50 apples. They sell 30% on Monday and 20% of the remainder on Tuesday. How many are left?"},
    {"role": "assistant", "content": """Step 1: Start with 50 apples.
Step 2: Monday sales = 50 * 0.30 = 15 apples sold. Remaining = 50 - 15 = 35.
Step 3: Tuesday sales = 35 * 0.20 = 7 apples sold. Remaining = 35 - 7 = 28.
Answer: 28 apples remain."""},
    {"role": "user", "content": "A factory produces 200 widgets per day..."}
]

在生产环境中，提示从来不是静态字符串。它们是在运行时用动态上下文填充的模板——用户名、当天日期、可用工具、检索到的文档等等。良好的模板设计使你的提示可维护且可测试。

使用Python f-string（简单场景）

def build_system_prompt(user_name: str, tools: list[str], date: str) -> str:
    tool_list = ", ".join(tools)
    return f"""You are a personal assistant for {user_name}.
Current date: {date}.
Available tools: {tool_list}.

RULES:
- Always greet {user_name} by name.
- Use tools when you need real-time information.
"""

使用string.Template（对用户输入更安全）

from string import Template

prompt_template = Template("""You are an assistant for $user_name.
Current date: $current_date
Available tools: $tool_list

RULES:
- Address the user by name.
- If a tool fails, explain the error and suggest an alternative.
""")

system_prompt = prompt_template.substitute(
    user_name="Alice",
    current_date="2026-03-28",
    tool_list="search_web, get_weather, send_email"
)

使用Jinja2（高级/生产级）

from jinja2 import Template

prompt_template = Template("""You are a support agent.

AVAILABLE TOOLS:
{% for tool in tools %}
- {{ tool.name }}: {{ tool.description }}
{% endfor %}

{% if user.is_premium %}
NOTE: This is a premium customer. Prioritise their request.
{% endif %}

RULES:
- Always search docs before answering.
- Maximum response length: {{ max_tokens }} tokens.
""")

system_prompt = prompt_template.render(
    tools=[
        {"name": "search_docs", "description": "Search knowledge base"},
        {"name": "create_ticket", "description": "Create support ticket"},
    ],
    user={"name": "Alice", "is_premium": True},
    max_tokens=500
)

即使经验丰富的工程师也会犯提示工程错误。以下是最常见的陷阱及其修复方法：

调试技术：提示日志

最有效的调试技术是记录每个提示和响应。当你的智能体行为异常时，你可以检查它看到了什么以及它做了什么决定：

import json
from datetime import datetime

def log_interaction(system_prompt, messages, response, log_file="agent_log.jsonl"):
    """Log every agent interaction for debugging."""
    entry = {
        "timestamp": datetime.now().isoformat(),
        "system_prompt": system_prompt,
        "messages": messages,
        "response": response,
    }
    with open(log_file, "a") as f:
        f.write(json.dumps(entry) + "\n")

# Usage: call after every API response
log_interaction(system_prompt, messages, response_text)

调试技术："解释你自己"测试

当智能体做出意外决定时，在系统提示中添加一条临时指令，要求它解释推理过程：

# Temporary debugging addition to system prompt
debug_instruction = """
DEBUG MODE: Before every action, explain:
1. What you understood the user to want
2. Which tools you considered and why you chose this one
3. What you expect the result to be
"""