有一个几乎每个做过 Agent 的人都遇到过的现象。
第一次运行,它聪明得让你有点惊喜:需求说一半它就能补全,输出结构清楚,偶尔还能指出你没想到的问题。
到第十轮,它开始变笨。它会重复第 3 轮就给过的选题,会忘记你第 5 轮明确说过“不要写教程向”,会把一件早就做完的事再做一遍,还会引用一个它自己编造、你从没提过的事实。
你没换模型,没改代码,甚至没动 prompt。变的只有一样东西:它每次看到的上下文。
这句话听起来简单,但它是很多 Agent 项目真正的分水岭。新手阶段我们关心“怎么让它跑起来”,工程阶段我们关心“它在什么样的信息环境里思考”。前者靠 prompt,后者靠上下文工程。
阅读提示:本文是「Agent 工程进阶」系列的第 1 篇,面向已经跑通过一个 Agent、想把它做稳的读者。如果你还没做过第一个 Agent,建议先看新手系列的实战篇:用 Vibe Coding 做一个最小 Agent。如果你想要一张整体地图,可以先看第 0 篇从 Demo 到可交付:如何做一个 Agent 项目。
先看清:一次调用里到底装了什么
大多数人理解的上下文是“聊天记录”。这个理解不算错,但太窄了,窄到会误导你的优化方向。
更准确的定义是:上下文是模型在这一次调用里能看到的所有输入。 它至少包含六类东西。
- 系统指令:角色、边界、风格、输出要求。
- 工具定义:每个工具的名字、描述、参数 schema。
- 外部资料:检索回来的文档、读进来的文件内容、数据库查询结果。
- 历史消息:之前每一轮用户说了什么、助手答了什么。
- 工具返回值:每一步调用的原始结果,包括报错信息。
- 当前输入:这一轮用户真正想让它做的事。
注意第六类。在很多跑坏的 Agent 里,用户真正的需求只占上下文的百分之几,剩下全是“历史遗留物”。
这个区别为什么重要?因为模型只能在上下文里思考。它不是先理解你的项目再回答问题,它是在每次调用时,把眼前这一堆文字读完,然后预测下一个 token。你给它什么,它就只能在什么里面思考。上下文不是 Agent 的记事本,是它唯一的工作台。
所以当你觉得“模型变笨了”,更可能的真相是:工作台被堆满了,它要找的那把螺丝刀被压在了最底下。
长上下文不等于够用
一个很自然的想法是:那我用上下文窗口更大的模型不就行了?
不行。窗口变大只是让“能装的东西”变多,并没有让“装进去的东西”更有效。研究和实践都指向同一件事:长上下文不是均匀生效的,它有明显的失效模式。
第一个是中间丢失。模型对上下文开头和结尾的内容记得比较牢,中间部分容易被忽略。你把 20 份历史选题一股脑塞进去,最可能的结果是:前两份和后两份被考虑到,中间十六份等于没塞。
第二个是上下文干扰。信息太多时,模型会被无关内容带跑。一个典型表现是工具选择:你给了 15 个工具,它可能挑了一个名字看起来相关、但其实完全不对的。工具越多,这个概率越高。
第三个是上下文污染。这是最危险的一个。某一步模型产生了幻觉,或者某个工具返回了一句错误的话,这段内容就进入了上下文。接下来它会被当成既有事实反复引用,而且越引用越确信。我在选题助手上见过一次:第 3 轮它自己总结出“你之前写过一篇关于 MCP 的文章”,其实根本没有,但后面九轮它一直在用这个前提做去重,输出全部跑偏。
第四个是上下文冲突。新信息进来,和旧信息打架,但两边都还在上下文里。这时候模型不知道该信哪个,通常会随机选一个,或者试图“兼顾”,输出一个两头不讨好的折中结果。
这四个模式有个共同点:它们都不是模型能力问题,而是信息组织问题。 所以解法也不在换模型,在工程。
六种手法:写、选、压、隔、缓、验
我把上下文工程里真正能落地的动作归纳成六个字。它们不互斥,一个成熟的 Agent 通常会同时用到好几个。
写:能移出上下文的,就别塞进去
第一个动作不是“加东西”,而是“减东西”。
判断标准很简单:这段内容是不是每一轮都一样? 如果是,它就不该靠模型每轮重新读一遍。
常见的可迁移项:
- 输出格式模板。与其在 prompt 里写 200 字说明“请按这个 Markdown 结构输出”,不如让代码在拿到结果后按模板补齐。
- 业务规则和边界。能用条件判断拦截的,不要让模型“记得遵守”。
- 工具参数 schema。这部分由框架注入,你只要保证描述准确、不要重复写一遍。
- 固定的风格要求。可以做成后处理检查,也可以只在最后一轮格式化时注入。
有个很实用的自检:把你的系统提示词从头读一遍,划掉所有“这一轮不会改变”的段落,问自己这些能不能变成代码、配置或后处理。通常能划掉三分之一。
选:只把影响当前决策的东西放进来
检索不是越多越好,检索是越准越好。
塞进去 30 份历史选题,看起来“资料很全”,实际效果是:多了 30 份干扰项,而且真正相关的那两份可能正好落在中间被忽略。
一个更稳的筛选策略通常包含三个维度:
- 相关性:和当前这一步的目标是否有关。
- 时效性:越近的越优先,除非任务本身要求查历史。
- 去重度:和已经进上下文的内容是不是高度重复。
给数量设上限,比给相关性设阈值更重要。k=3 这种硬上限能救很多项目。
压:压缩不是删掉,是换一种密度
历史不能全留,也不能全删。正确做法是压缩:把低密度的原始过程,换成高密度的状态结论。
压之前先分清三类内容:
- 必须保留:用户的原始目标、中途补充的约束、已确认的事实、还没完成的待办、失败过的原因。
- 可以压缩:模型的中间推理、试探性的输出、工具的原始返回。
- 可以丢弃:已经完成且不再影响后续的步骤细节。
注意“失败过的原因”属于必须保留。很多 Agent 反复踩同一个坑,就是因为上一轮的失败被压缩掉了,它只剩结论没有教训。
实现上最常见的是滚动摘要:当历史超过阈值时,把较早的部分交给模型压成一份状态摘要,最近几轮保持原样。保留最近几轮很重要,因为最近的内容通常和当前决策关系最紧,而且压缩它收益最小、风险最大。
隔:把脏活隔离在子上下文里
有些任务天生会“弄脏”上下文,比如读十个文件、抓五页网页、跑一堆查询。这些内容体积大、噪声多,而且大多用一次就不需要了。
处理办法是隔离:开一个子任务去做,只让结论回传主上下文。
比如你要让 Agent 参考历史选题。不要把所有历史文件的全文读进主上下文,而是开一个子任务,让它读完十份文件后只返回:每份一句话摘要、是否与当前方向重复、最多两条可复用角度。三百字回传,替代三千字原文。
这个手法有两个额外好处:主上下文保持干净,而且子任务天然可以并行。
缓:让前缀稳定下来
这一条是纯省钱省时间的,但在长任务里收益巨大。
主流模型 API 都有 prompt caching:如果两次调用的前缀完全一致,这部分可以命中缓存,成本和延迟都会明显下降。前提是前缀必须稳定。
所以要建立一条顺序纪律:
- 系统指令放最前面,它最稳定。
- 工具定义紧跟其后,它也稳定。
- 摘要、检索结果这类半稳定的放中间。
- 最近几轮对话放后面。
- 当前用户输入放最后。
最忌讳的是把时间戳、随机数、每次变化的调试信息塞在开头。一个变动的开头会让后面所有内容都无法命中缓存。
验:把上下文当成可以检查的产物
这是最便宜、也最容易被跳过的一步:把真实的上下文 dump 出来看一遍。
我们调试代码会打日志,调试 Agent 却常常只看最终输出。但输出变差的原因往往不在 prompt 里,在上下文里。你不看上下文,就只能猜。
动手改一遍:把选题助手从第十二轮救回来
假设这样一个场景:新手系列第 4 篇做的博客选题助手,你已经按第 5 篇给它加了记忆、文件读写和历史记录。单轮用得挺好,但连续聊十几轮之后,它开始重复旧选题,而且越来越泛。
我们用上面六种手法走一遍。
第一步:先把上下文导出来看
# debug/dump_context.py
import json
import time
from pathlib import Path
def dump_context(messages, tag=""):
Path("debug").mkdir(exist_ok=True)
name = f"debug/context-{int(time.time())}{'-' + tag if tag else ''}.json"
Path(name).write_text(
json.dumps(messages, ensure_ascii=False, indent=2),
encoding="utf-8",
)
print(f"上下文已导出:{name}")
在你调用模型之前插一行 dump_context(messages),跑一次出问题的场景,然后看文件。
你大概会得到这样一份账单:
第 12 轮,合计 18,400 tokens
系统指令 1,200 6.5%
输出格式模板 900 4.9% <- 每轮都一样
工具定义 1,600 8.7%
历史消息 11,300 61.4% <- 问题在这
已完成任务的中间过程 6,800
工具的原始返回 3,100
历史选题文件 2,700 14.7%
当前输入 700 3.8%
看到这张表,问题就不用猜了:用户真正的需求占 3.8%,历史遗留物占了 76%。
第二步:压掉历史
SUMMARY_PROMPT = """请把下面这段对话压缩成一份状态摘要。
必须保留:
1. 用户最初的目标,以及后来补充过的约束。
2. 已经确认的事实,不要保留推测。
3. 已经完成的步骤和它们的结论。
4. 还没完成的待办。
5. 失败过的尝试和失败原因。
不要保留:
1. 模型的中间推理过程。
2. 工具的原始返回,只保留结论。
3. 已经被后续结论覆盖的旧判断。
输出不超过 400 字,用 Markdown 列表。
"""
def maybe_compress(history, threshold_tokens=6000):
if count_tokens(history) < threshold_tokens:
return history, None
older, recent = history[:-4], history[-4:]
summary = call_model(SUMMARY_PROMPT + "\n\n" + format_history(older))
compressed = recent + [
{"role": "system", "content": f"以下是之前对话的状态摘要:\n{summary}"}
]
return compressed, summary
这里保留了最近四轮原文。别小看这个细节:压缩最近内容省不了多少 token,却最容易丢掉正在推进的上下文。
第三步:把“全量历史”改成“选出来的历史”
def pick_history(topics, current_direction, k=3):
scored = []
for t in topics:
score = similarity(t["title"] + t["outline"], current_direction)
score += recency_bonus(t["created_at"])
if score > 0.2:
scored.append((score, t))
scored.sort(key=lambda x: x[0], reverse=True)
return [t for _, t in scored[:k]]
从“把 outputs/ 里三十份文件全读进来”,变成“最多三份,按相关性和新鲜度选”。十四百分比的历史占比能降到五个点以内。
第四步:把格式模板移出 prompt
原来 prompt 里那 900 token 的输出结构说明,删掉。改成拿到结果后由代码补齐固定字段,只在最后格式化时才把结构要求注入一次。
判断依据就是前面那条:每轮都一样的东西,不值得让模型每轮都读一遍。
第五步:把读文件的脏活隔离掉
SUB_TASK_PROMPT = """请阅读以下 {n} 份历史选题文件。
只返回:
1. 每份一句话摘要,不超过 30 字。
2. 它与当前方向「{direction}」是否重复,回答是或否。
3. 如果有可复用的角度,最多列 2 条。
不要返回原文。总长度不超过 300 字。
"""
主上下文拿到的是三百字结论,不是三千字原文。
第六步:把顺序理顺
messages = [
{"role": "system", "content": SYSTEM_PROMPT}, # 最稳定
{"role": "system", "content": TOOL_SCHEMAS}, # 最稳定
{"role": "system", "content": summary or ""}, # 半稳定
*recent_turns, # 变化
{"role": "user", "content": current_input}, # 最易变
]
稳定的在前,易变的在后。这样系统指令和工具定义可以稳定命中缓存。
改完之后的对比
| 指标 | 改造前 | 改造后 |
|---|---|---|
| 每轮 token | 18,400 | 6,200 |
| 历史占比 | 61% | 18% |
| 当前输入占比 | 3.8% | 11% |
| 第十二轮表现 | 重复旧选题、越来越泛 | 能指出哪些已写过并给新角度 |
| 缓存命中 | 几乎为 0 | 系统指令与工具定义稳定命中 |
最有意思的是最后两行。你并没有让它“变得更聪明”,你只是把它的工作台收拾干净了。
一份可以直接用的检查清单
做完之后,用这几条自查:
- 我能不能一句话说清当前上下文里都有什么?
- 有没有内容每一轮都一样,却一直在占位置?
- 历史消息里,有多少是已经完成、不会再影响后续的?
- 检索回来的资料有没有数量上限?
- 失败过的尝试,还留在上下文里吗?
- 大体积、一次性的脏活,有没有被隔离在子上下文里?
- 消息顺序是不是稳定的在前、易变的在后?
- 我最近一次完整看过真实上下文,是什么时候?
第八条最容易答不上来。补上它,很多说不清的问题会自己现形。
常见误区
第一个误区:换个大窗口模型就好了。 窗口变大只是提高上限,不会自动改善组织。该被忽略的中间内容,在一百万 token 里一样会被忽略。
第二个误区:什么都记下来最保险。 记录的成本不只是钱和延迟,还有注意力。每多一份无关资料,就多一份干扰项。上下文工程里,“不放进来”常常是比“放进来”更专业的判断。
第三个误区:压缩一次就够了。 压缩是持续动作,不是一次性清理。设一个阈值,让它在运行过程中自动触发,而不是等你发现变笨了再手动清一次。
第四个误区:只看最终输出。 输出是结果,上下文是原因。只看输出调试,等于只盯着体温计找病因。
为什么这是第一讲
你可能会问:进阶系列为什么从上下文开始,而不是从记忆、评估或多 Agent 开始?
因为后面这些主题,本质上都是上下文管理的不同形态。
记忆系统解决的是“哪些信息该跨会话进入上下文”;检索解决的是“哪些外部知识该在这一步进入上下文”;评估解决的是“上下文变了之后,效果有没有退化”;多 Agent 解决的是“怎么把上下文切开,让每个角色只看自己该看的部分”。
它们是同一个问题的不同切面:在有限的注意力里,放对东西。
想明白这件事,你会发现 Agent 工程里很多看起来高深的东西,都变得可以讨论了。
下一讲我们聊记忆系统——它是上下文在时间维度上的延伸,也是最容易被“存个文件就算做完”的一块。
本系列目录
这是「Agent 工程进阶」系列的第 1 篇。
- 第 0 篇(地图):从 Demo 到可交付:如何做一个 Agent 项目
- 第 1 篇:上下文工程:为什么你的 Agent 越聊越笨(当前篇)
- 第 2 篇:记忆系统:Agent 怎么记住该记的,忘掉该忘的
- 第 3 篇:工具设计深水区:粒度、错误语义、幂等与 MCP
- 第 4 篇:编排与多 Agent:什么时候该拆,什么时候千万别拆
- 第 5 篇:评估体系:怎么知道你的 Agent 变差了
- 第 6 篇:可靠性与成本:什么时候该重试,什么时候该放弃
- 第 7 篇:人机边界:什么时候该问人,什么时候该放心让它做
新手系列入口(偏入门,建议先跑通第一个 Agent):先听懂:AI、LLM、Prompt、Agent、RAG、Tool、Memory 到底是什么
