ARTICLE · 1324112

看懂 AI Agent 的上下文工程:递到模型面前的信息,到底该怎么摆

发布时间：2026-11-07 06:08:44 最近访问：2026-11-07 06:08:45

上一篇讲了一个基本公式：Agent = 大模型 + 上下文 + 工具。

大模型是思考的大脑，工具是动手的手脚，而上下文就是它在每个决策点能看到的全部资料。这一篇接着聊上下文：每次调用模型时，框架到底往它面前递了什么信息、怎么摆，才能让模型看得清、记得住，又不会越堆越乱。

这套围绕上下文做设计和管理的工作，就叫上下文工程。它不是往提示词里多塞几句话那么简单，而是系统性地组织和提供模型完成任务所需的全部背景。

01上下文为什么决定 Agent 的能力上限

大模型在标准测试里成绩亮眼，一到实际业务场景却常常让人失望。原因并不神秘：执行具体任务需要通用模型根本不知道的背景信息，比如产品架构、业务规则和内部约定。

可以想象一位天才工程师刚加入团队：理

论功底深、编程能力强，但对产品架构、业务逻辑、技术债务和团队规范一无所知；

更糟的是，关键架构决策散落在不同老员工的记忆里，代码库也缺文档。

这样的人智力再高，也很难发挥出真正的价值。这正是当前 AI Agent 面临的处境。

以一个编程 Agent 为例，同样是"帮我修复这个 bug"，上下文质量直接决定任务能否完成。它有效工作的最低信息需求大致有三类：

实时代码上下文
：目录结构、模块职责、核心数据结构、代码规范。缺了这些，写出的代码可能语法正确，却与项目风格格格不入。
流程规范
：分支策略、提交规范、审查流程、部署管线要求。缺了这些，Agent 可能直接往主分支提交未经测试的代码。
环境信息
：开发配置、测试库连接、部署方式、密钥管理。缺了这些，本地跑通的修复到测试环境可能立刻崩溃。

需要注意边界：进入上下文的，是对环境的观察、描述或配置，而不是环境本身。

模型智力只是基础，上下文的质量才是 Agent 能力的关键。

一个中等能力的模型配上精心组织的上下文，往往能胜过一个顶级模型在信息匮乏下的盲目摸索。

这件事也不只是技术问题，还是组织问题。

多数团队的关键知识都是隐性的：架构决策只有老员工记得，业务规则靠口口相传，重要背景锁在私聊记录里。

团队本身就是一个信息黑洞，再好的 Agent 也无计可施。

Agent 就像一个永远的新员工：给足背景信息，它能干得很好；

什么都不告诉它，再聪明也是白搭。

所以构建 AI 原生团队，首先是一场文档化运动，而不只是部署新工具。

记住一句复述：决定 Agent 在业务里发挥价值的，往往不是模型参数量，而是它在每个决策点能拿到多丰富、多精准的上下文。

02一次 API 调用，上下文到底由什么组成

先记住一个前提：模型 API 本身是无状态的，它不会"记住"上一次对话。

每次调用时，都必须由框架重新构造足够的上下文。

最直接、无损的做法是带上此前的完整消息历史；生产系统也可以做摘要和压缩，但不能悄悄丢掉决定下一步行动所需的信息。

四种消息角色，加一个独立的工具清单

API 请求的核心是一个消息列表，每条消息都有角色标识，模型据此理解这条消息的含义和来源：

system（系统提示词）
：开发者编写的身份、行为规则和约束条件，模型视为最高优先级指令，通常只有一条，放在列表最前面。
user（用户消息）
：来自终端用户的输入，是 Agent 需要响应的请求。
assistant（助手消息）
：模型之前的回复，包括文本回复和工具调用请求。多轮对话中，之前的 assistant 消息会被放回列表，让模型"看到"自己说过什么。
tool（工具结果）
：框架执行工具后送回模型的结果，每条通过调用编号与对应的工具请求关联。

除此之外，工具定义作为请求的独立字段传入，并不是一种消息角色。

四种消息角色加工具清单字段，正好覆盖上下文的五个组成部分。

带工具调用的多轮循环：Agent 的核心运转方式

看一个稍完整的例子：用户问"温哥华现在几点、天气如何"。

模型自身知识答不出实时时间和天气，需要调用外部工具。

第 1 次调用：框架发送 system、user 和工具清单。模型判断需要工具，返回两个工具调用请求：查当前时间、查天气。

两者之间没有数据依赖，框架可以并行执行；

如果后一个工具的参数必须来自前一个的结果，就只能串行。

这里有个关键分工：模型负责决策——调用什么工具、传什么参数；

框架负责执行——实际调用接口、运行代码。模型只是发出请求，真正动手的是框架。

第 2 次调用：框架执行完两个工具，把完整对话历史连同工具结果一起再发给模型。三个细节：

第二次请求包含第一次的全部历史；

第一次的 assistant 消息被原样放回；

tool 消息靠调用编号对应到具体是哪一次调用。模型判断信息已经足够，就直接给出文本回复，循环结束；

如果用户追问，框架再把新消息追加到历史末尾，发起又一轮循环。

用代码实现，核心就是一个循环加一个判断：模型返回了工具调用，就执行工具并继续循环；没有工具调用，就输出结果并退出。整个过程中消息列表不断增长，框架的核心工作就是管理这个列表。后续所有上下文工程技术，本质上都是在优化这个列表的内容和结构。

从这个结构里可以看出两部分：上

半部分是系统提示词和工具定义，整轮对话保持不变，称为静态前缀；

下半部分是用户消息、模型回复和工具结果交替累积的对话历史，也就是第一章说的轨迹，随交互不断增长。一句话记住这个结构：前面不能动，后面可以压缩。

03前缀为什么不能乱动：KV Cache 与三条缓存规矩

模型每生成一个词，都要回头参考前文所有词的中间计算结果。

如果每轮都从头算一遍，开销会随上下文长度爆炸式增长。

KV Cache 的做法是：把前文的中间计算结果缓存下来，下一轮只计算新增的部分。前提是要复用的前缀保持不变——如果词序列从某个位置开始不同，首个不同的词及其后的缓存状态需要重新计算，此前的位置不受影响。

一行时间戳，怎么就让账单翻了倍

某团队的客服 Agent 每天处理十万次对话，原本运行正常。

一天工程师为了让 Agent"知道"当前时间，在系统提示词里加了一行实时时间戳。

第二天监控告警：所有对话的首词延迟从 0.5 秒涨到 3 到 5 秒，

月度推理账单几乎翻了一倍。代码看起来没问题，模型也没换，问题出在哪里？

答案就在前缀机制上：那行时间戳让每次请求的词序列从时间戳所在位置开始就不同，该位置及其后的缓存无法复用。系统提示词位于上下文前部，模型往往还要重新计算它之后的大部分输入。

开发者写下的一行看似无害的代码，可能让整条推理链路慢一个量级。

三条必须记住的规矩

跳过底层技术细节，先记住这三条实践结论：

系统提示词和工具定义一旦确定就不要改。
任何改动，哪怕多一个空格，都可能改变词序列，使首个不同词及其后的缓存无法复用；改动越靠前，延迟和成本的影响通常越大。
动态信息永远追加到末尾。
时间戳、用户状态这类会变化的内容，作为新消息追加到对话末尾，而不是去修改已有的系统提示词。
使用标准 API 格式，不要自行拼接消息。
结构化消息会被聊天模板翻译成模型训练时见过的固定词序列；自己用字符串拼出"USER: … ASSISTANT: …"，偏离了训练格式，会削弱模型的多步思考能力。

模板、缓存与常见错误

API 层面的结构化消息，需要经聊天模板转换成模型实际处理的线性词流。

可以把模板想象成信封格式：

消息是信的内容，模板规定怎么在信封上写明寄件人和收件人，用特殊标记划分每条消息的角色和边界；

不同模型家族格式不同，由服务端自动完成转换。绕过模板自行拼接，比如把工具结果当成普通用户消息传入，模板就可能把它误识别为新的用户查询，模型之前的思考过程被清掉——相当于算到一半，草稿纸被人收走。

还要区分两个容易混淆的概念：

KV Cache 是模型内部机制，在一次推理过程中缓存已算好的词的键值对；

Prompt Cache 是推理引擎的优化，在多次 API 请求之间复用相同前缀的计算结果。前者加速单次请求内的生成，后者减少跨请求的重复计算成本，缓存读取的成本远低于首次计算。

工程实践里有几种典型错误：动态系统提示词（就是开头的时间戳故事）；

动态更新剩余次数、账户余额等用户配置，破坏缓存；工具定义按使用频率动态排序，让缓存从首个变动的工具起全部失效；

滑动窗口只留最近几条消息，既破坏前缀一致性，又会丢掉关键工具结果，模型容易陷入反复调用同一工具的循环；纯

文本格式化则是最具破坏性的模式之一，模型需要额外消耗注意力去推断角色边界，结果可能重复执行已完成的操作、忽略工具结果。在生产级系统里，缓存不只是性能优化手段，更是一条架构约束。

04系统提示词怎么写：给新员工的一份员工手册

提示工程的核心对象，就是那条 system 消息。它相当于 Agent 的员工手册，定义身份、行为规则、约束条件和工作流程。

有一条朴素的检验标准：一个聪明的新员工读完你的提示词还不知道该怎么做，Agent 也一样不知道。

一是语气与风格，也就是"人格"。可以要求回答简洁、控制在几行以内；任务无法完成时，用一两句话说清，不要陷入冗长的自我辩护。真正关键的约束用明确措辞强调，但过度使用会稀释效果，应留给最重要的规则。

二是结构化格式。模型对结构化输入相当敏感。标签名称本身就携带语义：一个工作目录标签，模型一眼就知道这是工作目录信息；换成纯文本"当前目录：…"，它还要额外思考冒号前后的关系。Markdown 负责层次可读，标签结构负责机器可解析的精确语义，两者配合，人读着清晰，模型理解也准确。

三是流程驱动，而不是规则堆砌。给新员工一份上百条零散规则的手册，没有流程图、没有优先级说明，最聪明的人也会困惑：

多条规则同时适用时怎么选？

规则没覆盖的情况怎么办？流程驱动的提示词像一份优秀的培训手册，给出清晰的标准操作流程：

任何时刻都知道自己处于哪个阶段、当前步骤的目标是什么、完成后进入哪一步；

遇到异常，按当前阶段确定处理方式，而不是遍历所有规则寻找匹配。

四是业务规则细化。这是最容易被忽视却最关键的环节，本质是产品设计问题。以一个帮用户打电话协商账单的 Agent 为例，团队设计了三种计费模式：按省钱比例提成、按服务收固定费用、困难任务预收款不退。规则一旦模糊，

比如"根据任务情况选择合适计费类型"，行为就极不稳定：退掉上个月买的衣服，算"省钱"还是"取回本属于他的钱"？取消订阅，算不算省钱？规则必须明确到可执行：提成仅限通过谈判降低现有账单，退款和取消服务绝不按提成；

金额粒度写死，"节省"只基于现有账单计算。背后的哲学是：模型的优势在于遵循复杂指令、从长上下文中提取信息，不应在业务规则制定上被赋予过多自由裁量权；清晰的操作框架解放它的认知资源。

五是少样本示例。当期望输出难以用规则精确描述时——特定风格的文案、报告格式、回复语气分寸——与其堆砌冗长定义，不如直接给两三个高质量的输入输出示例。模型凭上下文学习能力临时学会这些模式，效果往往胜过等量篇幅的抽象规则；反过来，模型本来就擅长、规则又容易说清的任务，示例只是浪费 token。

示例位于上下文靠前区域，确定后应保持字节级稳定；逐请求动态检索"最相关"的示例，等于每次改写前缀，缓存会持续失效。两三个覆盖边界情况的示例，胜过十个大同小异。

六是工具定义设计。工具清单是另一个静态组成部分，质量直接决定 Agent 使用工具的准确性。好的工具描述像操作手册：写清使用边界、给出具体参数示例、提示性能要点、说明工具之间的协作顺序。

一次消融实验说明了什么

在模拟航空客服和零售支持的测试框架上，研究者固定基线配置，逐个改动不同维度观察效果：语气风格（专业中立、夸张自信、轻松表情符号）显著改变表达方式，但对任务完成率影响相对有限，说明模型的风格适应能力很强；

信息组织上，保留全部规则内容、只打乱组织结构，后果是灾难性的，任务成功率下降超过 30%，Agent 经常违反关键业务规则——"先验证身份再处理退款"被拆散后，有时就会跳过身份验证直接退款；

工具描述上，保留函数签名和参数定义、移除所有描述性文本，工具调用错误率增加 45%。对人类友好的信息组织方式，对模型同样友好。

提示注入：上下文层的核心威胁

提示工程做得再精细，如果外部输入能往上下文里塞进伪装成指令的文本，规则都可能被绕过。

提示注入的本质是：攻击者通过网页、邮件、文档等外部内容，把伪装成系统指令的文本混入上下文，劫持 Agent 行为。

Agent 比普通聊天机器人更危险：后者最坏情况是输出不当内容，而 Agent 拥有工具调用能力，被注入的指令可能导致删文件、发邮件、泄露隐私数据等不可逆操作。

上下文层防御的核心，是帮模型分清指令和数据：

用来源标记包裹外部内容，标明它来自不可信外部世界；

严格按角色体系传递信息，让模型依据训练建立的优先级区分可信指令与外部数据；

再配合输入清洗过滤常见注入短语，但这层容易被措辞变体绕过，只能作为辅助。

来源不明的第三方 Skill 也一样，安装前必须像审查将要执行的代码一样审查内容。需要清醒认识到：上下文层防御只是第一道防线，只能降低攻击成功率，做不到万无一失。

05知识不用一次塞满：Skills 的按需加载

随着 Agent 覆盖的场景越来越多，系统提示词会不断膨胀：

客服的退款规则、编程的代码规范、文档的格式要求……

全部塞进一个提示词，带来两个问题：

一是浪费 token，大部分内容与当前任务无关；

二是注意力被稀释，无关信息过多会摊薄模型对关键内容的关注。

自然的解决方向是：不把所有知识一次性塞给 Agent，而是按需加载。

Agent Skills 机制就是这一思路的工程化实现：

把能力模块化成独立、可按需加载的知识包，每个 Skill 本质是一套含专业领域指导的提示词集合，像专项任务的操作手册。

设计哲学是渐进式披露：先给目录摘要，需要时再加载完整内容。就像不会把公司所有部门的手册都堆到新员工桌上，而是先给一份总目录，需要哪本再去取。

（取证猎人：我们的战法skill也是如此设计）

三层加载结构

第一层：元数据目录。
每个 Skill 有名称和简短描述，目录在正文加载前对 Agent 可见，让它先判断当前任务是否需要这项能力。描述是路由决策的关键：要短，写法像路由条件而不是功能介绍，明确"何时使用"和"何时不使用"的边界。"何时该用我"比"我能做什么"重要得多。
第二层：核心流程。
Agent 判断需要某个 Skill 时，运行时才加载完整正文。触发有两种方式：用户显式输入斜杠命令，由本地拦截展开；模型读过目录后自己判断需要，再调用专用工具。正文里是处理这类任务的核心步骤。
第三层：细则子文档。
通过文件引用深入更详细的子文档、模板和脚本，Agent 根据具体需求选择性阅读。

一份实用的 Skill 通常包含四部分：

角色与读者（服务谁、面向什么任务、输出达到什么标准）；

核心原则（只保留三到五条最重要的判断，配上正例和反例）；

禁止清单（高频错误、越权动作和容易误解的表达，写清合法例外）；参

考资料（术语表、模板、范文和子文档，规则尽量写成"作用域 + 动作 + 例外 + 验证方式"）。Skill 还可以捆绑可执行脚本和模板文件，每个模块独立开发测试、单独版本控制，类似软件包管理系统的思路。

在 Skill 加通用执行器的模式下，工具数量始终很少，Skill 内容按需加载，不影响已缓存的前缀。有一个常见误解需要澄清："对缓存友好"并不是零成本，目录和完整正文首次进入请求时都要处理和计算，只有前缀保持稳定后，后续请求才能复用缓存。

06状态栏：让模型随时瞥一眼自己做到哪了

提示工程给出的是静态指令，而 Agent 执行过程中还需要动态感知自身状态和任务进展。框架把这些动态信息整理成结构化摘要注入上下文，这种机制就是 Agent 状态栏。

最好的类比是操作系统的状态栏。用手机时，屏幕顶部始终显示时间、电量、信号强度和通知数量——这些不是应用主界面内容，但你随时瞥一眼就能掌握设备当前状态。

Agent 状态栏起的是完全相同的作用：它不是对话主体内容，而是框架在上下文末尾持续注入的状态摘要，比如"已打 3 次电话""当前时间 10:30""待办还剩 2 项"。

理论基础：检索很强，提炼缺位

状态栏之所以有效，源于注意力机制的一个特性：

上下文学习更像检索，而不是推理。可以把上下文窗口想象成一台只有一半的检索引擎。检索这一半非常强：注意力能从成千上万个词里把相关的原始记录捞出来；

但它缺了另一半——提炼层。上下文里的东西不会被自动数一遍、建个索引，也不会就地总结成一条结论。

任何"关于这些内容的结论"，模型每次要用，都得从原始记录里现算一遍，代价随堆积内容量一起上涨。

回到打电话的例子：规则要求每个商家不超过拨打 3 次。打满 3 次之后，Agent 经常数不清到底打了几次，又打出第 4 次，甚至陷入循环反复拨打同一个电话。

根源在于："已经打了几次"这个知识没有被自动提炼出来，而是以原始通话记录的形式分散在上下文表示中；

模型每次决策都要额外消耗思考去扫描统计，效率低且错误率高。如果在每次工具结果里直接标明累计呼叫次数，模型就能立即发现已经达限，不再继续呼叫。

这一机制的本质，是把分散在各处的隐式状态，提炼成可以直接使用的显式知识。

在长上下文场景中，早期设定的任务目标和关键约束，容易被后续大量工具结果淹没；模型会过度关注最近的内容，对中部信息产生注意力衰减。

状态栏把关键元信息结构化地放在上下文末尾，空间上更接近即将生成的新词，因而能获得更高的注意力权重。

构成、位置与维护注意

状态栏大致由三部分构成：

任务规划（待办列表，分解成清晰步骤放在轨迹末尾，提醒当前进展和后续目标，防止只顾局部子任务忘记原始诉求）；

事件侧信道信息（精确时间、地理位置、距上次回复的时间间隔等辅助元数据）；

环境当前状态摘要（系统时间、工作目录、异常提醒如"该工具已被重复调用 N 次"）。

状态栏在 API 层面实际作为一条 user 角色消息插入上下文末尾，而不是修改开头的 system 消息——原因正是缓存约束：修改 system 会破坏整个前缀缓存。这里要澄清：user 角色只是协议层面的技术槽位借用，内容来自框架自动生成，并非真实用户输入。

状态是会变的，更新有两种实现：

每轮替换，调用前移除上一轮状态、在末尾追加最新状态，保证永远只有一份最新状态；代价是旧状态位置之后的缓存失效，但状态位于末尾，失效范围通常只覆盖上次注入后新增的一轮消息。

持久追加，状态消息永久留在轨迹中，每轮只追加新状态；对缓存完全友好，代价是陈旧状态不断累积，要求模型自己关注最新一条。取舍要看轨迹长度、状态大小和更新频次。

维护状态栏有两点特别注意。

第一，尽量用代码维护；实在要用模型，也要逐条抽取、再由代码汇总，绝不要让它一次性批量统计。模型几乎无条件地相信状态栏——你写"打了 3 次"，它就当真 3 次，不会自己重算。

第二，谨慎删除原始上下文。状态栏是对原始上下文的有损投影，只提前算了"预想会被问到"的那些维度；只要有问题涉及状态栏未计算的维度，仅保留状态栏就会导致准确率断崖式下降。

07上下文做减法：压缩、分层与隔离

前面几节讲怎么往上下文里放内容，这一节方向相反：如何为上下文做减法——什么时候压缩、怎么压缩，以及为什么即使上下文没满也应该压缩。

三个压缩动机

一是长度约束和成本约束。

上下文窗口有限，工具调用结果动辄数万字符，几轮交互就可能撑满窗口，任务被迫中断；token 越多，API 成本越高，推理延迟也急剧上升。

二是提升思考质量。

即使窗口足够大，把所有原始信息堆在上下文里也不是最优选择：十几轮搜索的原始结果散落各处，模型每次决策都要在数万词中反复检索，注意力被分散，关键信息容易遗漏。先用一次模型调用把已有信息结构化总结成"目前已知 A、已知 B、还缺 C"，后续思考就可以直接使用这份精炼表示。

三是缓解上下文焦虑。

模型认为窗口即将耗尽时，可能在任务尚未完成前提前收尾；在窗口尚未接近耗尽时就提前压缩，反而可能提升决策质量。

检索机制与宠物店的例子

状态栏是把算好的结论加进上下文，压缩则是把臃肿的原始记录换成算好的结论——两者是同一枚硬币的两面，都在给那台"只有一半"的检索引擎补上缺失的提炼层。区别只在于：状态栏多由代码每一步确定性地维护，压缩更多是用一次模型调用把大段原文蒸馏掉。

举个直观例子。上下文里记着一百个笼子的巡查记录，其中九十只是黑猫、十只是白猫。问"黑猫和白猫各有多少只"，

不带思维链的模型很难直接答对：查找是注意力的强项，统计归纳却要遍历全部记录并维护计数状态，

本质上是思考而非检索。启用思维链当然能数对，但每问一次就要从头数一遍；

如果提前做一次总结，在上下文里直接写入"黑猫 90 只，白猫 10 只"，模型立刻就能检索到这个结论。

这就是压缩的第二个价值：把需要思考才能得到的结论，变成可以直接检索的知识。

还要区分两种容易混淆的问题。

上下文溢出是"装不下了"；

上下文腐化是"装得下但找不到了"。

后者更隐蔽：Agent 表面上还在正常工作，只是决策质量悄然下降。无关内容一旦占到上下文大头，真正有用的部分就越来越难被注意到。由此得到一条设计原则：与其期望模型从冗长上下文中自动学习，不如主动、显式地进行知识提炼，为模型提供经过提炼的结构化知识。

压缩与缓存：看似矛盾，实则互补

压缩不是在单次 API 调用过程中修改上下文，而是在两次调用之间，由框架对消息列表做预处理：系统提示词和工具定义永远不动；

压缩对象是对话历史中的工具结果，用摘要替换原始输出时，替换位置之后的缓存失效，之前的缓存仍然有效。这是一个有意识的权衡：不压缩，上下文膨胀到超出窗口限制，任务直接失败；压缩后损失部分缓存，但长度可控、信息密度更高。最好在上下文接近阈值时批量压缩，而不是每轮都压。

生产环境通常把多种策略组合成分层机制：大体积工具结果存到磁盘，模型只看摘要预览；低价值噪声直接删除，不做摘要；

逐轮做结构化归档摘要，保留每轮独立记录的逻辑脉络；全量压缩作为最后手段，并配备连续失败熔断器，避免在反复压缩失败的会话上持续烧钱。压缩还有四条设计原则：信息价值非均匀分布，关键决策点高于支撑证据，更高于冗余噪声；

保证语义完整性，时间、主体名称这类关键信息不能压丢；

按任务类型保留对应侧重；负责压缩的模块本身要接近主模型能力，形成模型调用模型的递归架构。压缩最容易丢失的，是早期架构决策、约束背后的理由和失败路径。

隔离优于压缩：子 Agent 上下文隔离

压缩是信息进入上下文之后做减法；

一个更釜底抽薪的思路，是让大体积中间信息根本不进入主上下文。

主 Agent 把"在代码库中大范围搜索"这类会产生海量中间内容的任务，委派给一个独立的子 Agent；子 Agent 在自己的上下文里完成探索，只把几百 token 的结论性摘要回传给主 Agent。

同一个任务——"找到处理支付回调的函数"——主 Agent 亲自搜索，可能把十几个文件、数万 token 的原始代码纳入主上下文，其中绝大部分在找到目标后就沦为永久占据窗口的噪声；委派给搜索子 Agent，主上下文只增加两条消息：一条任务描述，一条结论，中间过程的数万 token 随子 Agent 的上下文一起被丢弃。

这本质上是用隔离代替压缩。压缩是有损的、需要额外模型调用的事后补救；隔离让噪声从一开始就与主上下文绝缘，主 Agent 的缓存前缀也完全不受影响。代价是子 Agent 看不到主 Agent 的完整上下文，任务描述必须自包含、目标明确——这又回到了本章的主题：上下文质量决定能力上限，对子 Agent 同样成立。