create_agent 函数的system_prompt高阶用法

一、system_prompt 格式（LangChain 1.0+ create_agent）

在新版 LangChain（1.0+）中，create_agent 的 system_prompt 支持两种类型：

1. 字符串（str）（最常用）
   原始文本，内部可自由换行、分段、写规则，LangChain 会自动包装成 SystemMessage。
2. SystemMessage 对象（高级）
   可直接传入 langchain_core.messages.SystemMessage，支持结构化 content_blocks（如文本+图片/文件块）。

函数签名（关键）

def create_agent(
    model: Union[str, BaseChatModel],
    tools: List[Tool],
    *,
    system_prompt: Optional[Union[str, SystemMessage]] = None,
    # ... 其他参数
)

• 必填：model、tools（空工具传 []，不能传 None）
• system_prompt：可选，默认空；每次调用模型时会固定插在消息列表最前面

二、基础格式规范（写好 system_prompt 的核心）

标准结构：角色定位 + 任务目标 + 工具说明 + 行为规则 + 输出格式 + 边界约束

1. 极简示例（入门）

from langchain.agents import create_agent
from langchain.chat_models import init_chat_model

llm = init_chat_model("openai:gpt-4o", temperature=0)

agent = create_agent(
    model=llm,
    tools=[],
    system_prompt="你是乐于助人的助手，回答简洁准确。"
)

2. 标准结构化模板（推荐）

SYSTEM_PROMPT = """
【角色】你是资深Python代码审查专家，拥有10年开源项目维护经验。
【任务】审查用户提供的代码，找出Bug、性能问题、安全隐患并给出修复建议。
【工具】你可使用以下工具：
1. run_code：执行代码片段，验证运行结果（参数：code: str）
2. search_docs：查询Python官方文档（参数：query: str）
【规则】
1. 必须先分析代码逻辑，再决定是否调用工具
2. 修复建议需给出完整可运行代码
3. 语气专业但易懂，避免过度技术术语
【输出格式】
- 问题概述：一句话总结主要问题
- 详细分析：分点列出Bug/性能/安全问题
- 修复方案：提供修正代码+解释
"""

三、高级示例（复杂场景）

示例1：多工具协同（天气+时间+节日查询）

from langchain.tools import tool

# 定义工具
@tool
def get_weather(city: str) -> str:
    """获取指定城市实时天气，参数：city（城市名，如"北京"）"""
    return f"{city} 今日晴，25℃，微风"

@tool
def get_current_time() -> str:
    """获取当前北京时间"""
    return "2026-05-09 16:30:00"

@tool
def get_holiday(holiday_name: str) -> str:
    """查询节日日期，支持：元旦、春节、劳动节、国庆节"""
    holidays = {"元旦":"1月1日", "春节":"农历正月初一", "劳动节":"5月1日", "国庆节":"10月1日"}
    return holidays.get(holiday_name, "暂不支持该节日")

# 系统提示词（高级：强规则+工具约束+输出结构化）
SYSTEM_PROMPT = """
【角色】全能生活助手，专注天气、时间、节日查询。
【可用工具】
- get_weather(city: str)：查天气，必须传入城市名
- get_current_time()：查当前时间，无参数
- get_holiday(holiday_name: str)：查节日，必须传入节日名
【强制规则】
1. 仅回答与天气/时间/节日相关问题，其他问题礼貌拒绝："抱歉，我仅能查询天气、时间、节日信息~"
2. 需调用工具时，**必须严格按工具参数要求传参**，不得编造参数
3. 工具返回结果后，**用自然语言整理，不返回原始工具数据**
4. 多工具请求（如"北京天气+现在时间"）需**依次调用所有必要工具**，再整合回答
【输出风格】简洁友好，1-2句话说清结果
"""

# 创建Agent
agent = create_agent(
    model=llm,
    tools=[get_weather, get_current_time, get_holiday],
    system_prompt=SYSTEM_PROMPT
)

示例2：结构化输出（强制JSON格式）

from langchain_core.messages import SystemMessage

# 用 SystemMessage 传入，支持更复杂结构
system_msg = SystemMessage(
    content="""
【角色】数据提取专家，从用户文本中提取个人信息。
【任务】提取姓名、年龄、城市、职业，输出**严格JSON格式**，无额外文字。
【规则】
1. 缺失字段值为 null
2. 年龄必须是数字，非数字则为 null
3. 输出示例：{"name":"张三","age":25,"city":"上海","job":"工程师"}
"""
)

agent = create_agent(
    model=llm,
    tools=[],
    system_prompt=system_msg
)

# 调用测试
result = agent.invoke({"messages": [{"role": "user", "content": "我叫李四，住在广州，做老师"}]})
print(result["messages"][-1].content)
# 输出：{"name":"李四","age":null,"city":"广州","job":"老师"}

四、多轮对话示例（带记忆，支持上下文关联）

create_agent 默认支持多轮，只需在每次调用时传入完整历史消息列表。

示例：客服Agent（多轮上下文记忆）

from langchain.tools import tool
from langchain_core.messages import HumanMessage, AIMessage

# 工具：查询订单状态
@tool
def query_order_status(order_id: str) -> str:
    """查询订单状态，参数：order_id（订单号，如"ORD12345"）"""
    mock_data = {"ORD123": "已发货，顺丰SF987654321", "ORD456": "待付款", "ORD789": "已完成"}
    return mock_data.get(order_id, "订单不存在")

# 系统提示词（支持上下文理解）
SYSTEM_PROMPT = """
【角色】电商客服助手，友好专业，专注订单查询。
【工具】query_order_status(order_id: str)：查订单状态，需订单号
【多轮规则】
1. 记住用户历史对话，**上下文关联回答**（如用户先给订单号，后续直接问"进度"可直接查询）
2. 用户未提供订单号时，**礼貌追问订单号**
3. 仅处理订单相关问题，其他引导至人工客服
"""

# 创建Agent
agent = create_agent(
    model=llm,
    tools=[query_order_status],
    system_prompt=SYSTEM_PROMPT
)

# 多轮对话模拟
# 第一轮：用户打招呼
history = [{"role": "user", "content": "你好，帮我查下订单"}]
res1 = agent.invoke({"messages": history})
history.append({"role": "assistant", "content": res1["messages"][-1].content})
print("助手1：", res1["messages"][-1].content)  # 输出：你好！请提供你的订单号，我帮你查询~

# 第二轮：用户提供订单号
history.append({"role": "user", "content": "ORD123"})
res2 = agent.invoke({"messages": history})
history.append({"role": "assistant", "content": res2["messages"][-1].content})
print("助手2：", res2["messages"][-1].content)  # 输出：你的订单ORD123状态：已发货，顺丰SF987654321

# 第三轮：用户追问进度（上下文关联，无需重复订单号）
history.append({"role": "user", "content": "什么时候能到？"})
res3 = agent.invoke({"messages": history})
print("助手3：", res3["messages"][-1].content)  # 输出：顺丰快递一般2-3天送达，预计5月11日前收到~

五、常见FAQ（避坑必看）

Q1：system_prompt 可以动态变量吗？

✅ 可以。用字符串模板+partial 或直接格式化字符串：

from langchain_core.prompts import ChatPromptTemplate

# 动态模板
prompt_template = ChatPromptTemplate.from_messages([
    ("system", "你是{role}，擅长{skill}"),
    ("user", "{input}")
]).partial(role="翻译官", skill="中英互译")

# 传入 create_agent（需转为字符串）
system_prompt = prompt_template.format_messages(input="")[-1].content

Q2：为什么工具调用失败？（参数错误/不调用工具）

🔴 常见原因：

• system_prompt 未清晰说明工具参数：必须写清工具名、参数名、类型、用途
• tools 传了 None：空工具必须传 []
• 规则冲突：如"优先回答不调用工具"会导致工具不触发

✅ 修复：工具说明按工具名(参数: 类型)：用途格式写，规则明确"需工具时必须调用"。

Q3：多轮对话会遗忘上下文？

🔴 原因：每次调用未传入完整历史消息，只传当前用户消息。

✅ 解决：每次 invoke 时，messages 列表需包含：system_prompt（自动加）+ 所有历史 user/assistant 消息。

Q4：system_prompt 太长会被截断吗？

✅ 会。受模型上下文窗口限制（如GPT-4o约128k tokens）。

✅ 优化：

• 精简冗余描述，规则每条1句话
• 复杂规则拆为"核心规则（必写）+ 补充规则（可选）"
• 超长提示用langchain_core.prompts.SystemMessage分块传入

Q5：可以同时传 system_prompt 和旧版 prompt 参数吗？

❌ 绝对不行！create_agent 新版废弃旧版 prompt 参数，只能用 system_prompt，混用会报错。