Agent开发完全实战指南(四)上下文工程

还记得第 02 篇那个只增不减的 messages 数组吗?它是 Agent 的记忆,也是一颗定时炸弹。

对话越来越长,工具返回的日志越堆越多,这个数组迟早会超过模型的上下文窗口。到那天,你的 Agent 会遇到三件糟心事:要么接口直接报错 context length exceeded,要么响应越来越慢、越来越贵,要么模型开始"失忆"——把中间的关键信息看漏了。

2024 到 2025 年,业界形成一个共识:Context Engineering(上下文工程)正在取代 Prompt Engineering,成为 Agent 工程的核心能力。 这一篇就讲透它。

上下文工程的一句话概括:在有限的上下文窗口里,让每一步都放进"恰好正确"的信息——不多,不少。


一、先破除一个迷信:上下文不是越多越好

很多人觉得,模型上下文窗口现在动辄 128K、200K,"我全塞进去不就行了?"

错。塞得越满,往往效果越差。 有两个硬道理:

第一,成本和延迟随 token 线性增长。 每一轮都把几万 token 发给模型,又慢又烧钱。Agent 循环几十轮下来,账单和等待时间都很可怕。

第二,存在 "Lost in the Middle" 效应。 研究反复证明:当上下文很长时,模型对中间部分的信息注意力会明显下降,容易看漏。业界还有个更形象的词叫 context rot(上下文腐烂)——信息越堆越多,模型越容易迷失。

关键洞察:上下文窗口是 Agent 最宝贵的稀缺资源,要像管理内存一样精打细算,而不是当垃圾桶随便扔。更多上下文 ≠ 更好效果。


二、四板斧:管理上下文的四种基本操作

Anthropic 和 LangChain 把上下文工程提炼成四类操作,记住这四个词,你就有了完整的工具箱:

操作 一句话说清 典型手段
Write(写出去) 把暂时不用的信息存到上下文之外,需要时再取回 scratchpad、文件、外部存储、数据库
Select(选进来) 只把当前这一步真正需要的信息拉进上下文 按需读文件、RAG 检索、检索相关历史
Compress(压缩) 把长历史摘要/裁剪,保留结论、丢弃过程 摘要、裁剪、只留关键字段
Isolate(隔离) 用子 Agent / 独立上下文承载子任务,避免污染主上下文 多 Agent、sub-agent、独立会话

用一张图理解它们在 Agent 循环里的位置:

flowchart LR
    subgraph 上下文窗口["上下文窗口(稀缺资源)"]
        SYS[系统提示]
        RECENT[最近几轮对话]
    end
    EXT[(外部存储
文件/DB/向量库)] SUB[子 Agent
独立上下文] RECENT -->|Write 写出去| EXT EXT -->|Select 选进来| RECENT OLD[早期长历史] -->|Compress 压缩成摘要| RECENT RECENT -->|Isolate 派发脏活| SUB SUB -->|只回传结论| RECENT

这一篇我们重点实现 Compress(压缩)——它是最立竿见影、最该先做的一板斧。Select 留给第 05、06 篇(记忆和 RAG),Isolate 留给第 07 篇(多 Agent)。


三、动手前先想清楚:什么该留,什么该砍

压缩历史,本质是决定"哪些消息留在上下文里"。一个实用的优先级排序:

永远保留(动不得):

优先压缩/丢弃:

关键洞察:压缩不是无脑删最老的消息,而是"保护关键锚点(系统提示、原始任务、近期上下文),压缩中间的冗长过程"。

还有一个极其重要的技术约束:第 02 篇讲过,assistant 的 tool_calls 消息和对应的 role:tool 结果消息是成对的。裁剪时绝不能拆散它们——删了 assistant 的调用却留着 tool 结果(或反之),接口会直接报错。裁剪必须以"完整的轮"为单位。


四、动手:给 Agent 加上上下文管理

我们分三步:估算 token → 设定预算 → 超预算就压缩。为了让你能离线看清效果,本篇代码用一段构造好的长历史来演示压缩逻辑(不需要真的调 API)。

4.1 估算 token(够用就行,别追求精确)

精确算 token 要用模型对应的 tokenizer。但工程上,一个粗略估算通常够用来做预算判断:

// estimateTokens 粗略估算 token 数。
// 经验值:ASCII(英文/数字)约 4 字符/token,非 ASCII(中文等)约 1.5 字符/token。
// 生产环境应换成模型官方 tokenizer(如 tiktoken),或用接口返回的 usage 反推。
func estimateTokens(text string) int {
	ascii, wide := 0, 0
	for _, r := range text {
		if r > 127 {
			wide++ // 中文等多字节字符
		} else {
			ascii++ // ASCII 字符
		}
	}
	return ascii/4 + wide*2/3 + 1
}

// 估算整个消息列表的 token
func totalTokens(messages []Message) int {
	sum := 0
	for _, m := range messages {
		sum += estimateTokens(m.Content)
		for _, tc := range m.ToolCalls {
			sum += estimateTokens(tc.Function.Arguments) + estimateTokens(tc.Function.Name)
		}
	}
	return sum
}

提醒:len(text)/3 这类估算对中文误差不小,只能用来做"要不要触发压缩"的粗判断。要精确核算成本(第 09 篇),必须用官方 tokenizer 或接口返回的 usage。

4.2 压缩策略:保护锚点,裁剪中间

// CompactHistory 当历史超过 token 预算时进行压缩。
// 策略:保留第一条锚点消息(通常是 system 或原始任务)+ 最近 keepRecent 条,
// 中间部分用一条摘要消息替代。
// 简化说明:真实项目里若第一条之后紧跟 tool_calls/tool 对,裁剪时要以"完整的轮"
// 为单位、不能拆散它们;这里为聚焦核心逻辑做了简化。
func CompactHistory(messages []Message, budget, keepRecent int) []Message {
	if totalTokens(messages) <= budget {
		return messages // 没超预算,原样返回
	}
	if len(messages) <= keepRecent+1 {
		return messages // 太短,没必要压缩
	}

	head := messages[:1]  // 锚点:第一条永远保留
	rest := messages[1:]
	if len(rest) <= keepRecent {
		return messages
	}

	dropped := rest[:len(rest)-keepRecent] // 中间被压缩的部分
	recent := rest[len(rest)-keepRecent:]  // 最近保留的部分

	// 把被丢弃的部分压成一条摘要(生产中应调用 LLM 生成更好的摘要,见 4.3)
	summary := Message{
		Role:    "system",
		Content: fmt.Sprintf("【历史摘要】此前进行了 %d 条交互(已省略细节以节省上下文)。", len(dropped)),
	}

	result := append([]Message{}, head...)
	result = append(result, summary)
	result = append(result, recent...)
	return result
}

4.3 更好的压缩:用 LLM 生成摘要

上面的摘要只是"占位"。生产级做法是让 LLM 把被丢弃的历史读一遍,提炼成一段"已确认的事实":

// SummarizeMessages 调用 LLM 把一段历史压缩成简短摘要
func SummarizeMessages(msgs []Message) (string, error) {
	var sb strings.Builder
	for _, m := range msgs {
		sb.WriteString(m.Role + ": " + m.Content + "\n")
	}
	prompt := []Message{
		{Role: "system", Content: "把下面的对话历史压缩成不超过 200 字的要点摘要,只保留结论和关键事实,丢弃寒暄和过程。"},
		{Role: "user", Content: sb.String()},
	}
	resp, err := callLLM(prompt) // 复用前几篇的 callLLM
	if err != nil {
		return "", err
	}
	return resp.Choices[0].Message.Content, nil
}

把 4.2 里的占位摘要换成这个调用,就得到了一个会"自动做会议纪要"的 Agent。

4.4 接进主循环

在每次调 LLM 之前,先压缩一次:

func runAgent(userInput string) (string, error) {
	messages := []Message{
		{Role: "system", Content: "你是一个乐于助人的助手。"},
		{Role: "user", Content: userInput},
	}

	const (
		budget     = 3000 // token 预算
		keepRecent = 6    // 至少保留最近 6 条
	)

	for i := 0; i < 20; i++ {
		messages = CompactHistory(messages, budget, keepRecent) // 关键:调用前先压缩

		resp, err := callLLM(messages)
		// ... 后续逻辑与第 03 篇相同
		_ = resp
		_ = err
		break // 示意
	}
	return "", nil
}

完整可运行示例见 code/04-context/,它构造了一段超长历史,打印压缩前后的 token 对比,让你直观看到上下文是怎么"瘦身"的。


五、决策指南:四板斧怎么选

你的处境 该用哪板斧
单个工具输出巨大(大日志、大文件) Write:存到文件/DB,上下文只放摘要+引用 ID
需要的信息在一个大知识库里 Select:用 RAG 检索最相关的片段(第 06 篇)
对话轮次太多、历史太长 Compress:摘要早期历史,保留近期(本篇)
有独立的、会产生大量中间过程的子任务 Isolate:派子 Agent 去做,只回传结论(第 07 篇)

一个务实的建议顺序:先做 Compress(最简单、收益最大)→ 再做 Write(大输出落盘)→ 需要外部知识时上 Select/RAG → 复杂任务再上 Isolate。


六、常见坑速查

坑 后果 正确做法
从不压缩历史 迟早撑爆窗口、越来越慢贵 设 token 预算,超了就压缩
裁剪时拆散 tool_calls 与 tool 结果 接口 400 报错 以"完整的轮"为单位裁剪
删掉了系统提示或原始任务 Agent 失忆/跑偏 永远保留关键锚点
用字符数当 token 数 预算判断失真 用官方 tokenizer 或接口 usage
无脑删最老消息 丢掉关键结论 压缩成摘要而非直接丢弃

七、小结与下一篇

我们现在解决了"单次会话内"的上下文膨胀。但还有个更大的问题:每开一个新会话,Agent 就把之前学到的一切忘得一干二净。 上次解决过的问题,这次又从零摸索。怎么让 Agent 跨会话地积累经验、越用越聪明?

下一篇预告——《记忆系统:让 Agent 越用越聪明》:我们会讲透短期记忆与长期记忆、情景/语义/程序性记忆的区别,并给 Agent 装上一个能跨会话检索历史经验的记忆模块。这是 Agent 从"金鱼记忆"进化到"越用越强"的关键。


参考资料

资料 来源
Effective context engineering for AI agents(Anthropic) anthropic.com/engineering/effective-context-engineering-for-ai-agents
Context Engineering for Agents(LangChain,四板斧框架) blog.langchain.com/context-engineering-for-agents
Lost in the Middle: How Language Models Use Long Contexts arxiv.org/abs/2307.03172
tiktoken(OpenAI 官方 tokenizer) github.com/openai/tiktoken