GitHub 上 Agent 相关的开源项目越来越多框架、编排层、工具调用协议几乎每个月都有新进展。但如果你常逛开发者讨论区会发现一个被反复提起的痛点上下文。有人问“为什么 Agent 跑着跑着上下文就超了”有人问“自动总结已经开了怎么还是提示超限”还有人问“新开一个会话Agent 怎么什么都不记得了”。这些问题的背后其实指向同一个本质我们把 Agent 的执行上下文当成了一个黑盒只看到消息在进出看不到里面到底发生了什么。这篇文章不聊模型选型也不聊具体 prompt 技巧而是聚焦“上下文”本身。我会先拆解 Agent 执行上下文的组成和失控原因再给出一个可运行的 Python 示例演示如何通过预算管理、压缩策略和状态快照把上下文从黑盒变成白盒。无论你是在开发自己的 Agent 框架还是在给业务系统接入 Agent这篇文章的内容都可以直接落地。1. 背景Agent 的上下文为什么成了“黑盒”1.1 一个典型的 Agent 执行场景先把场景画出来。假设我们写了一个电商数据分析 Agent它的执行循环通常是这样的用户提出一个任务例如“分析近 30 天订单趋势”。Agent 把系统提示词、历史对话、工具定义一起发给大模型。模型决定调用某个工具比如查询订单表、调用统计接口。工具返回结果Agent 把结果追加到消息列表里。带着新的历史模型继续推理直到给出最终答案。从流程上看每一步都很自然。但如果你追问一句第 10 轮的时候到底有多少条消息被发给了模型哪些旧消息已经在悄悄丢失工具返回的 30 行明细占了多少 token很多团队是答不上来的。这不是开发者不细心而是大部分 Agent 框架默认不会把这些信息暴露出来消息列表就像是一个只进不出的黑盒。1.2 上下文黑盒的三种表现结合开源项目 issue 和团队踩坑的经验上下文黑盒通常表现为三种形态。第一种是“长度黑盒”。你不知道当前消息列表累计了多少 token也不知道每次请求实际发出去的内容有多大。很多框架只在模型报错的时候才告诉你“上下文超限”平时没有任何预警。第二种是“内容黑盒”。当上下文接近上限时一些框架会自动做总结或截断。问题是总结掉了哪些内容、截断了哪些字段开发者完全看不到。模型可能已经丢掉关键约束但对外表现只是“回答质量变差”。第三种是“生命周期黑盒”。会话什么时候开始、什么时候结束、哪些上下文跨会话保留这些规则常常藏在框架内部。于是就会出现“新开会话后 Agent 什么都不记得”的尴尬情况。1.3 为什么必须把上下文“白盒化”把上下文变成白盒本质上是把“不可观测的隐式输入”变成“可观测的显式数据”。这样做有三个直接收益。从调试角度看上下文一旦可见定位问题就快很多。模型回答奇怪、工具调用重复、结果前后矛盾多半都能在上下文快照里找到线索。从成本角度看token 就是钱。长上下文不仅慢而且贵。能清楚看到每次请求用了多少 token才能有效控制预算。从稳定性角度看Agent 生产化的最大障碍是“不可控”。上下文决定了 Agent 的长期记忆和短期行为如果这块处于黑盒状态任何上层优化都建立在沙地上。2. 核心概念Agent、Harness 与上下文工程2.1 Agent 和 Harness 到底有什么区别最近社区里讨论“harness 和 agent 区别”比较多。简单理解Agent 是“大脑 手脚”的设计理念模型负责推理规划工具负责执行动作而 Harness 是承载 Agent 运行的“外壳”负责管理循环、上下文、工具调用的生命周期。可以类比Harness 是应用服务器Agent 是运行在里面的业务逻辑。GitHub 上很多热门的执行框架本质上都在做 Harness 的事。比如社区里讨论度比较高的 DeepSeek Harness关注的就是长对话压缩与执行链路管理Claude Code 在长会话里提供的压缩交互也是把上下文管理显式化的一次尝试。这些项目的共同点是让开发者对“上下文如何被使用”这件事有更多掌控权而不是把一切交给模型的隐式状态。2.2 执行上下文里到底有什么一个 Agent 的执行上下文远不止“聊天记录”四个字。它可以拆成几个部分系统提示词定义角色、目标和输出约束通常放在消息列表最前面优先级最高。对话历史用户和助手的历史交互是上下文里最容易膨胀的部分。工具定义与工具结果模型在推理过程中会看到一批工具 schema以及每次调用后的返回内容。工具结果往往体积很大且包含大量噪声。中间推理轨迹如果采用了思维链等方案模型每一步思考过程也会写入上下文。持久化记忆跨会话保留的用户偏好、项目约定、关键事实通常来自数据库或向量检索。理解这些组成部分才能知道上下文超限时应该优化哪一块。大多数时候需要动的不是系统提示词而是工具结果和历史对话。2.3 上下文窗口不是越大越好最近大家经常讨论“60K 上下文能干什么”“1M 上下文怎么用”。模型厂商把上下文窗口越做越大这当然是好事但我们要清醒一点大窗口不等于好效果。一方面窗口变大意味着单次请求的输入可能非常多延迟和成本都会上升。另一方面模型对长上下文的注意力并不均匀长篇内容中间位置的细节容易被忽略也就是常说的“中间丢失”现象。也就是说即使你的窗口没有报错模型也可能已经漏读了一些关键信息。与其盲目扩大窗口不如把真正重要的内容放到上下文靠前的位置并控制无关内容进入。2.4 上下文工程有哪些常用手段把上下文管理显式化目前主流的做法可以归纳为五类。预算管理为上下文设定 token 上限在接近上限前主动处理。截断移除最旧或最不重要的消息实现简单但容易丢失信息。总结压缩用一次额外模型调用把旧历史浓缩成摘要能保留语义但会损失细节。检索增强不把所有历史塞进上下文而是在需要时检索相关片段这是 RAG 的核心思路。结构化与观测把上下文按角色、按来源拆分并持续记录状态快照。这五类手段不是互斥的生产级系统通常会组合使用。后面的实战案例我会重点演示预算、总结压缩和观测这三件事。3. 环境准备与项目结构3.1 运行环境说明本文示例使用 Python 实现核心代码只依赖标准库不需要安装第三方包。版本方面建议使用 Python 3.10 及以上版本因为代码用到了dataclass、str枚举和类型注解等特性。操作系统不限Windows、macOS、Linux 都可以直接运行。需要注意示例里的 token 估算函数只是为了让演示可运行并不代表真实模型的 token 规则。生产环境建议使用模型供应商提供的 tokenizer或者直接读取每次请求返回的usage字段。这里的重点是上下文管理思路而不是精确计数。