面向 Agent 的 Prompt Engineering

你给聊天机器人调 prompt 的那套手感,搬到 Agent 上经常翻车。给 Chatbot 加一句 "CRITICAL: 你必须用这个工具"很管用;在 Claude 4.6 上,这句话会让模型过度触发、见到工具就调。给 Chatbot 塞满 few-shot 边界案例能提准确率;给 Agent 塞一堆边界案例,它反而过拟合、丢了泛化。

Agent 的 prompt 不是写给人看的说明书,是配给模型的运行时环境。

一句话概括:面向 Agent 的 prompt engineering 已经从"找对措辞"演进成"配对上下文"——核心不是写更漂亮的咒语,而是在合适的"高度"给模型启发式而非硬规则,并用结构化输出把"能不能解析"这个 bug 类彻底消灭。

这篇讲两件事:一是 Agent 系统提示词怎么写(工具描述、指令高度、持久性、停止条件),二是结构化输出怎么落地(strict json_schema、约束解码、以及绕开"格式税"的字段排序技巧)。配可运行的 Go 代码,同一个任务用三种方式要 JSON,你能看清差别。


一、Agent prompt 和 Chatbot prompt 的根本差别

Anthropic 把这个演进概括为:prompt engineering → context engineering。区别在于问题从"用什么词"变成了"什么样的上下文配置最可能产生期望行为"。

对 Agent 来说,几条会反直觉的差异:

维度 Chatbot 做法 Agent 做法
指令粒度 具体措辞、明确话术 给启发式(heuristics),不写死 if/else
强调语气 "CRITICAL/MUST" 提合规 平实的 "Use this tool when..."(新模型对强命令会过度触发)
few-shot 覆盖各种边界 3–5 个多样的典型例子,不堆边界清单
指令位置 都塞 system 角色/持久行为进 system,任务+长数据进 user,query 放最后
成功标准 措辞好不好 有没有 eval 支撑

核心概念——"合适的高度"(right altitude):这是 Anthropic 的术语,指指令的抽象层级要卡在两个失败模式之间。

给原则,别给判断树。 这是最重要的一条心法。


二、工具描述:单点杠杆最高的地方

Agent 的行为质量,很大一块由工具描述决定,不是由主提示词决定。Anthropic 的实测:Claude 3.5 在 SWE-bench Verified 上刷到 SOTA,靠的正是对工具描述的精细打磨——"对工具描述的小改动能带来戏剧性的提升"。

一张 do/don't 表,条条来自 Anthropic 的《Writing effective tools for AI agents》:

Do Don't 为什么
造少量高价值工具(schedule_event) 把每个 API 端点 1:1 包成工具 工具重叠会制造"模糊的决策点"
按服务/资源命名(asana_search) 扁平的通用名 命名空间对工具选择评测有非平凡影响
返回语义字段(name、file_type) 返回 uuid、mime_type 把 UUID 解析成有意义的语言,显著减少幻觉
暴露 response_format 枚举(简/详) 永远返回全部 简洁模式实测只用约 1/3 token
错误信息写成可操作的修复提示 返回原始 traceback / 错误码 引导 Agent 自我纠正
像"跟新员工解释"那样描述参数 含糊的参数名 人都分不清,模型更分不清

一条检验铁律:如果一个人类工程师都说不清该用哪个工具,Agent 也说不清。工具描述就是 prompt engineering,把它当主提示词一样认真对待。


三、结构化输出:让"能不能解析"这个 bug 彻底消失

Agent 要把输出喂给下游代码时,你需要的是保证合法的结构化数据,不是一段可能夹带 ```json 围栏和解释的文本。

三个演进阶段

方式 机制 保证
JSON mode(旧) prompt 层要求 只保证语法合法的 JSON
Structured Outputs(2024.8) 约束解码:模型在解码层就吐不出违反 schema 的 token 精确匹配 schema(键、类型、required)
工具调用 strict 把 JSON 形状定义成工具的 input_schema 同上,且模型"边做事边给参数"

数字说话:旧的 gpt-4-0613 在复杂 schema 评测上合规率 <40%;开了 Structured Outputs 的 gpt-4o 是 100%。机制是约束解码——grammar 编译一次、服务端缓存,之后每 token 强制只在合法集合里采样。

Claude 侧:历史上走"强制工具调用"(tool_choice 指定一个工具,从 tool_use.input 读结构化对象),2025 年底也上了原生 Structured Outputs。注意 Claude 的 prefill 正在被弃用(4.6+ 对 prefill 最后一轮返回 400),老的"用 prefill 逼 JSON"要迁移到 Structured Outputs 或工具调用。

一条通用铁律:schema 里每个字段都写 description——schema 描述就是给模型的指令。 还有一句要刻在心里:结构化输出能消除"格式错误",但不能让"内容变对"。

代码:三种要 JSON 的方式

配套代码同一个任务(把客服工单抽取成结构化字段),跑三遍。裸提示词——能用,但输出常夹带围栏:

out, _ := callLLM(ChatRequest{Messages: []Message{
    {Role: "system", Content: "你是工单分类助手。把工单抽取成 JSON,含 priority、category、needs_human。"},
    {Role: "user", Content: ticket},
}})
// isValidJSON(out) 常为 false:模型爱加 ```json 围栏或一段解释,你得自己剥

strict json_schema——约束解码,100% 合法:

schema := map[string]any{
    "type": "object",
    "properties": map[string]any{
        "priority":    map[string]any{"type": "string", "enum": []string{"high", "medium", "low"}, "description": "紧急程度"},
        "category":    map[string]any{"type": "string", "description": "问题类别"},
        "needs_human": map[string]any{"type": "boolean", "description": "是否需要转人工"},
    },
    "required":             []string{"priority", "category", "needs_human"},
    "additionalProperties": false, // strict 模式必须显式关掉额外字段
}
callLLM(ChatRequest{
    Messages: msgs,
    ResponseFormat: &ResponseFormat{Type: "json_schema",
        JSONSchema: &JSONSchema{Name: "ticket_triage", Strict: true, Schema: schema}},
})

四、格式税:强制 schema 会不会让模型变笨?

这是结构化输出最容易踩、也最少人讲清的坑。

有研究支撑的结论:EMNLP 2024 的《Let Me Speak Freely?》发现,格式限制会降低推理质量,数学任务受损最重。但后续研究把损失拆开了——

说法 判定 修法
约束解码本身让模型变笨 基本是误解(影响很小) —
prompt 里那句"输出格式"的要求让模型变笨 是真的(主要成本) 先自由推理再格式化 / 重排 schema 让推理字段在前

根因很微妙:模型从左到右生成,如果 schema 把 answer 字段排在 reasoning 之前,就逼它先下结论再补理由——等于跳过了 CoT。

修法就是字段排序:把 reasoning 字段放在结论字段前面,schema 反而变成了 CoT 的强制执行器。

// 关键:reasoning 排在 priority/needs_human 之前。
// 字段顺序 = 思考顺序,先填结论会让它"没想清就下判断"。
schema := map[string]any{
    "type": "object",
    "properties": map[string]any{
        "reasoning":   map[string]any{"type": "string", "description": "先分析关键信号(紧急词、金额风险、情绪)"},
        "priority":    map[string]any{"type": "string", "enum": []string{"high", "medium", "low"}},
        "category":    map[string]any{"type": "string"},
        "needs_human": map[string]any{"type": "boolean"},
    },
    "required":             []string{"reasoning", "priority", "category", "needs_human"},
    "additionalProperties": false,
}

一句话记住格式税:让模型先想、再格式化——要么用 extended thinking 先自由推理,要么把 reasoning 字段排在结论前面。


五、两大厂 2026 的官方心法(可直接抄)

Anthropic(Claude 4.x):

OpenAI(GPT-5 / 推理模型):


六、一个可复用的 Agent 系统提示词骨架

综合两家心法,默认这么搭:

## 角色与背景        (1-2 句:Agent 是谁、领域上下文,卡在"合适的高度")

## 指令              (给启发式而非 if/else;顺序重要时才用编号步骤)
- 加动机:说清 WHY,不只是 WHAT
- 持久性:做到问题完全解决;不确定时做合理假设并记录
- 停止条件:什么时候该问用户(按工具设不确定性阈值)

## 工具指引          (少而不重叠的工具;命名空间;显式的 when-to-use)
- 独立任务并行调用,依赖任务顺序调用

## 上下文管理        (长任务时:上下文会自动压缩,别因 token 提前收工,记得存状态)

## 输出描述          (格式;说"要做什么"而非"别做什么";JSON 用 Structured Outputs / 工具 schema)

<examples>          (3-5 个多样的典型例子,放进标签里)

关键默认项:先推理后格式化(避开格式税)、用原生 Structured Outputs(strict:true)、语气平实(4.6+ 别滥用 CRITICAL/MUST)、审查指令矛盾、从最小 prompt 出发对着 eval 迭代。


七、常见失败与修法

失败 修法
Prompt injection(OWASP LLM #1,Agent 场景更危险:被污染的文档能改动作链) 指令层级只是第一层,要纵深防御:权限控制、plan-then-execute、执行隔离、注入检测分类器(详见第 10 篇)
指令自相矛盾 审查多方拼凑的长 prompt,定优先级 + 加例外条款
模型无视工具、只"建议" 明确用祈使句;但 4.6+ 要收敛 CRITICAL/MUST 免得反向过度触发
超长系统提示稀释注意力 "最小的高信号 token 集";长 prompt 还会让模型想得比你要的更频繁
过早终止 加持久性块;Claude 用上下文压缩提示防提前收工

八、2025–2026 真正变了什么


小结

面向 Agent 的 prompt engineering,本质是 context engineering:在"合适的高度"给模型启发式而非硬规则,把工具描述当成最高杠杆的主提示词来打磨,用 strict json_schema 把"能不能解析"变成不存在的问题,再用字段排序(reasoning 在前)绕开格式税。默认骨架照抄第六节,语气平实、审查矛盾、从最小 prompt 对着 eval 迭代。记住那句最省事的心法——先想清楚,再格式化。


参考资料

资料 来源
Effective context engineering for AI agents anthropic.com/engineering
Writing effective tools for AI agents anthropic.com/engineering
Claude 4 best practices / prompting platform.claude.com/docs
Introducing Structured Outputs in the API openai.com/index/introducing-structured-outputs-in-the-api
GPT-5 prompting guide developers.openai.com/cookbook
Let Me Speak Freely?(格式税) EMNLP 2024, aclanthology.org/2024.emnlp-industry.91
JSONSchemaBench arXiv:2501.10868
本篇配套代码 github.com/hua-ri/agent-learning /main/agent-prompting