# 什么是上下文工程？AI 智能体每次调用看到的全部内容 > 上下文工程就是挑选模型每次调用看到的全部内容：系统提示词、工具定义、示例、消息历史、文件、工具结果和记忆。提示词工程写的是指令，只是其中一部分。在智能体里，这个挑选每一轮都要重做一次，目标是用最少、信息量最高的 token，换来你想要的结果。 Mindket 编辑部 · 发布于 2026-11-06 · 更新于 2026-11-06 · https://mindket.com/cn/learn/context-engineering/what-is-context-engineering ## 要点 - 动提示词之前，先把智能体一次调用发出的全部输入列出来，从系统提示词一直到最新的工具结果。 - 只有代码要用的数据，留在本地状态里，等某一步用得上，再把那条事实交给模型。 - 用 token 给工具列表算一笔账，因为每次请求都会带上它。 - 每一轮都有意识地重组请求，别让内容自己越堆越多。 ## 开始之前 示例需要 Python 3.10 或更新版本，执行 `pip install openai-agents`，并在终端里设置 `OPENAI_API_KEY`，这些都写在 [Agents SDK 的 README](https://github.com/openai/openai-agents-python) 里。换成别的模型或 SDK，道理也一样。如果你还不熟悉上下文窗口，先读[什么是上下文窗口](https://mindket.com/cn/learn/prompt-engineering/context-window)，它演示了窗口怎样一轮一轮被填满。 这门课说的上下文，指模型在写下一条回复之前读到的那些 token。下面讲的，就是这些 token 是什么、由谁放进去。 ## 跟着一个值，从你的代码走到模型 挑一条事实，看它一路走到哪里。在下面这个 Agents SDK 示例里，用户的名字和 ID 放在你代码持有的一个 Python 对象里。只有当模型调用一个返回名字的工具时，它才知道这个名字。 代码复制自 SDK 的[上下文管理页面](https://github.com/openai/openai-agents-python/blob/main/docs/context.md)，只去掉了页面上的注释标记。`print` 下面那行注释，是文档给出的输出。 ````python import asyncio from dataclasses import dataclass from agents import Agent, RunContextWrapper, Runner from agents.decorators import tool @dataclass class UserInfo: name: str uid: int @tool async def fetch_user_age(wrapper: RunContextWrapper[UserInfo]) -> str: """Fetch the age of the user. Call this function to get user's age information.""" return f"The user {wrapper.context.name} is 47 years old" async def main(): user_info = UserInfo(name="John", uid=123) agent = Agent[UserInfo]( name="Assistant", tools=[fetch_user_age], ) result = await Runner.run( starting_agent=agent, input="What is the age of the user?", context=user_info, ) print(result.final_output) # The user John is 47 years old. if __name__ == "__main__": asyncio.run(main()) ```` 1. 用 `pip install openai-agents` 安装 SDK，再导出 `OPENAI_API_KEY`。 2. 把示例存成 `context_demo.py`，运行 `python context_demo.py`。 3. 找到 `user_info`。它以 `context=` 的形式传给 `Runner.run`，文档写明这个对象不会发给大模型。你的工具、钩子和回调通过 `RunContextWrapper` 读取它。 4. 找到名字进入模型视野的地方。`fetch_user_age` 读取 `wrapper.context.name`，返回一句话，这个工具结果会加入历史，模型下一次调用时就会读到。 ## 每次调用，上下文里装着什么 SDK 文档用一句话讲清了规则：模型被调用时，它能看到的数据只有对话历史。一条事实要到达模型，只有四条路：写进智能体的指令，放进传给 `Runner.run` 的输入，作为函数工具的结果返回，或者通过检索和网页搜索取来。 指令可以是一个函数，而不只是一段字符串。SDK [智能体页面](https://github.com/openai/openai-agents-python/blob/main/docs/agents.md)里的这段代码，每次调用都会把用户名写进系统提示词，适合模型一直需要的事实，比如名字或今天的日期。它用的 `UserContext` 是你自己定义的类型，和上面的 `UserInfo` 一样。 Anthropic 的[上下文工程指南](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)按种类整理同样的内容：系统提示词、工具、示例和消息历史，再加上智能体在工作中取来的文件、工具结果和笔记。 下表把两种看法放在一起。 ````python from agents import Agent, RunContextWrapper def dynamic_instructions(context: RunContextWrapper[UserContext], agent: Agent[UserContext]) -> str: return f"The user's name is {context.context.name}. Help them with their questions." agent = Agent[UserContext]( name="Triage agent", instructions=dynamic_instructions, ) ```` | 上下文的组成部分 | 谁放进去 | 运行过程中怎样变化 | | --- | --- | --- | | 系统提示词（指令） | 你，用字符串或函数 | 固定不变，或者每次调用时用你的数据重建 | | 工具定义 | 你，以及你接入的每个 MCP 服务器 | 每次请求都会带上，用不用都一样 | | 示例 | 你，写在提示词里 | 固定不变，除非你按任务替换 | | 消息历史 | 用户和模型 | 每一轮多出一个回合 | | 工具结果、文件和搜索结果 | 模型调用你的工具时产生 | 增长最快，一旦加入就留在历史里 | | 记忆和笔记 | 智能体，通过文件或记忆工具 | 某一步需要时再读回来 | ## 还没人开口，工具定义就占满了窗口 每个工具的名称、描述和输入结构都会随请求一起发出去。Anthropic 在 2025 年 11 月 24 日发布的[高级工具使用文章](https://www.anthropic.com/engineering/advanced-tool-use)里，算了五个常见 MCP 服务器的账：58 个工具在对话开始之前，就占了大约 55K 个 token。单是 Jira 一个，就还要再加大约 17K。文章还说，在 Anthropic 内部，工具定义在优化之前一度达到 134K 个 token。 如果任务只涉及 GitHub，那些 Slack 工具就是模型读了却用不上的 21K 个 token。解决办法在这条学习路径的后面。[AI 智能体的工具](https://mindket.com/cn/learn/harness-engineering/tools-for-ai-agents)讲怎样用更少、更大的工具，[按需载入上下文](https://mindket.com/cn/learn/context-engineering/just-in-time-context)讲怎样等某一步用到时，才载入工具或文件。先从数清你今天发出了多少开始。 **每个 MCP 服务器的工具定义占用的 token** 近似值，单位是千个 token，按 Anthropic 文章给出的、发出任何消息之前的配置。 - GitHub（35 个工具）: 26K - Slack（11 个工具）: 21K - Sentry（5 个工具）: 3K - Grafana（5 个工具）: 3K - Splunk（2 个工具）: 2K 来源：[Anthropic Engineering: Introducing advanced tool use on the Claude Developer Platform](https://www.anthropic.com/engineering/advanced-tool-use) (2026-11-06 查阅) ## 它和提示词工程有什么不同 提示词工程讲的是怎样写指令、怎样排顺序，主要写在系统提示词里。上下文工程包含这些，也包含请求里的其余部分，而且永远没有做完的时候。Anthropic 的指南说它是反复进行的：每次往模型里传东西，都要重新挑一次。 指南的工作原则，是只留下对目标结果有用的 token。落到系统提示词上，就是找准高度：具体到能引导模型，又不必为每种情况硬写 if-else 规则。落到示例上，几个多样、典型的例子，胜过一长串边缘情况。落到工具上，指南的标准说得很直白：如果一位人类工程师都说不准某个情况该用哪个工具，智能体也不会做得更好。 上下文一长，还会带来另一个问题。上下文越长，模型准确回忆其中信息的能力越弱，下一课[上下文腐化](https://mindket.com/cn/learn/context-engineering/context-rot)会拿数据说明这一点。[智能体记忆](https://mindket.com/cn/learn/context-engineering/agent-memory)讲的压缩和笔记，能让长任务在窗口占满之后继续下去。可如果请求一开始就没挑好，这两样都帮不上忙。 ## Tobi Lütke、Andrej Karpathy 和 Dex Horthy 谈掌控上下文 这个说法是在 2025 年 6 月流行起来的。Shopify 首席执行官 Tobi Lütke 在 6 月 19 日[写道](https://x.com/tobi/status/1935533422589399127)，他更喜欢“上下文工程”这个词，而不是“提示词工程”，因为它更准确地说出了核心技能。 六天后，OpenAI 创始成员之一 Andrej Karpathy [表示赞同](https://x.com/karpathy/status/1937902205765607626)，还列出了上下文里装的东西：任务描述和说明、少样本示例、RAG、相关数据、工具、状态和历史，以及压缩。给得太少，模型缺少需要的信息；给得太多或者不相干，成本可能上升，表现反而下降。 HumanLayer 的 Dex Horthy 更早就在 GitHub 上的指南 [12-factor agents](https://github.com/humanlayer/12-factor-agents/blob/main/content/factor-03-own-your-context-window.md) 里讲过这个道理。按指南自己的说法，它比这个词流行早了大约两个月。第三条原则叫“掌控你的上下文窗口”，它说标准的消息格式并不是必须的。指南把整个运行过程装进一条用户消息，写成一串带标签的事件，这样已经解决的错误可以删掉，工具结果也可以剪到下一步需要的长度。Agents SDK 会替你组装消息；自己写循环的话，就可以走这条路。 2025 年 9 月 30 日，Anthropic [在 X 上推荐了它的指南](https://x.com/AnthropicAI/status/1973098580060631341)，对象是熟悉提示词工程、正在搭建智能体的开发者。 > 提供全部上下文、让大模型有可能解决这个任务的艺术 > > Tobi Lütke, Shopify 首席执行官，引文为译文, [X](https://x.com/tobi/status/1935533422589399127) (2026-11-06 查阅) [![Tobi Lütke（@tobi）2025 年 6 月 19 日在 X 上发帖：比起提示词工程，我真心更喜欢“上下文工程”这个说法。它更好地描述了核心技能：提供全部上下文、让大模型有可能解决这个任务的艺术。](https://mindket.com/blog/shots/x-tobi-context-engineering.webp?v=fd02dbb634a5)](https://x.com/tobi/status/1935533422589399127) Tobi Lütke 在 X 上，2025 年 6 月 19 日 [![Anthropic（@AnthropicAI）2025 年 9 月 30 日在 X 上发帖：Anthropic 工程博客新文章。大多数开发者都听说过提示词工程，但要让 AI 智能体发挥最大作用，你需要上下文工程。我们解释它是怎么回事。](https://mindket.com/blog/shots/x-anthropicai-context-engineering.webp?v=89912d75f228)](https://x.com/AnthropicAI/status/1973098580060631341) Anthropic 在 X 上，2025 年 9 月 30 日 [12-Factor Agents: Patterns of reliable LLM applications, Dex Horthy, HumanLayer](https://www.youtube.com/watch?v=8kMaTybvDUw) AI Engineer 的 YouTube 频道上，HumanLayer 的 Dex Horthy 做的演讲，标题是 12-Factor Agents: Patterns of reliable LLM applications。 > X 官方嵌入卡片的截图，拍摄于 2026 年 11 月 5 日和 6 日，时间为 UTC。Anthropic 那张卡片省略了原帖结尾的链接。点击截图可到 X 上打开原帖。 ## 常见错误 - 错误答案其实来自历史深处一个过时的工具结果，却一遍遍改写系统提示词。 - 把在任何地方用过的 MCP 服务器都接上，工具定义挤占了任务本身的空间。 - 以为代码知道的事，模型也知道。SDK 的 `context` 对象从来不会到达模型。 - 某一步只需要几行，却把整个文件或整个网页作为工具结果返回。 - 把更大的上下文窗口，当成可以多发内容的许可。 ## 自己试一试 - 把 `fetch_user_age` 从 `tools=[...]` 里拿掉，再问同一个问题。名字现在还能从哪里来？ - 给智能体换上文档里的 `dynamic_instructions`，类型改成 `UserInfo`，不给任何工具，再问用户的名字。 - 把你自己的智能体一次请求里的每个部分都写下来，给每部分估一个 token 数，标出当前这一步用不上的内容。 ## 自测一下 1. 在 Agents SDK 示例里，用户的名字是怎样到达模型的？ A. SDK 把 context 对象加进系统提示词 B. 模型从记忆里读取那个数据类 C. 通过模型调用的那个工具返回的结果 D. 通过 uid 字段 答案：C。 context 对象留在你的代码里，名字只以 fetch_user_age 返回的那句话进入历史。 2. 智能体上下文里的哪一部分，即使这一步用不上，也会随每次请求发出去？ A. 工具定义 B. 智能体打开过的一个文件 C. 最终答案 D. 本地的 context 对象 答案：A。 每个已接入工具的名称、描述和结构都会随每次调用发出，58 个工具就这样占了大约 55K 个 token。 3. 挑选上下文时，Anthropic 的指南让你以什么为目标？ A. 把窗口填满，反正都付了钱 B. 把每条规则都写进系统提示词 C. 每一轮都发送完整历史 D. 用最少、信息量最高的一组 token，让想要的结果最有可能出现 答案：D。 它的工作原则，是找出最少、信息量最高的一组 token，让你想要的结果最有可能出现。 4. 上下文工程和提示词工程有什么不同？ A. 它只适用于图片和音频 B. 它每次调用都重新挑选整个请求，而不只是指令 C. 它用示例取代系统提示词 D. 它需要更大的模型 答案：B。 提示词工程写的是指令，上下文工程则要在每次调用模型时，挑选模型看到的全部内容。 ## 常见问题 ### AI 里的上下文工程是什么？ 它是用模型做产品时，决定模型回答之前读到什么的那部分工作。拿客服智能体来说，就是决定每次调用放进哪些政策页面、哪些之前的消息和哪些账户字段，其余的统统留在外面。 ### 上下文工程只是提示词工程换了个名字吗？ 对单次聊天的提示词来说，两者大体重合，因为发出去的主要就是指令。可一个接连调用工具的智能体，输入大多来自工具结果和历史，这些不是哪个提示词模板管得住的。 ### RAG 算上下文工程吗？ 算，它是内容进来的一条路。检索会找出和查询匹配的文档，加进请求里。上下文工程还要决定它周围的指令、工具和历史，以及什么时候干脆不放检索到的文字。Mindket Learn 的 RAG 课程会带你搭出检索这一步。 ### 一个 AI 智能体该有多少个工具？ OpenAI 的函数调用指南给了一个软性数字：每一轮开始时，可用的函数最好少于 20 个。Anthropic 的指南提醒，工具太多、职责重叠，模型就难以选择；它的高级工具使用文章算出，58 个工具大约占 55K 个 token。让工具集小到一个人能为每一步挑出对的那个。 ## 资料来源 - [Anthropic Engineering: Effective context engineering for AI agents](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) (2026-11-06 查阅) - [Anthropic Engineering: Introducing advanced tool use on the Claude Developer Platform](https://www.anthropic.com/engineering/advanced-tool-use) (2026-11-06 查阅) - [OpenAI API docs: Function calling](https://developers.openai.com/api/docs/guides/function-calling) (2026-11-06 查阅) - [OpenAI Agents SDK docs on GitHub: Context management](https://github.com/openai/openai-agents-python/blob/main/docs/context.md) (2026-11-06 查阅) - [OpenAI Agents SDK docs on GitHub: Agents (dynamic instructions)](https://github.com/openai/openai-agents-python/blob/main/docs/agents.md) (2026-11-06 查阅) - [GitHub: openai/openai-agents-python README](https://github.com/openai/openai-agents-python) (2026-11-06 查阅) - [GitHub: 12-factor agents, factor 3, own your context window](https://github.com/humanlayer/12-factor-agents/blob/main/content/factor-03-own-your-context-window.md) (2026-11-06 查阅) - [X: Tobi Lütke on the term context engineering](https://x.com/tobi/status/1935533422589399127) (2026-11-06 查阅) - [X: Andrej Karpathy on context engineering](https://x.com/karpathy/status/1937902205765607626) (2026-11-06 查阅) - [X: Anthropic shares its context engineering guide](https://x.com/AnthropicAI/status/1973098580060631341) (2026-11-06 查阅) - [YouTube (AI Engineer): 12-Factor Agents, Dex Horthy, HumanLayer](https://www.youtube.com/watch?v=8kMaTybvDUw) (2026-11-06 查阅) [浏览 Agent Skills](https://mindket.com/cn/skills)