什么是上下文工程？AI 智能体每次调用看到的全部内容

开始之前

示例需要 Python 3.10 或更新版本，执行 pip install openai-agents，并在终端里设置 OPENAI_API_KEY，这些都写在 Agents SDK 的 README 里。换成别的模型或 SDK，道理也一样。如果你还不熟悉上下文窗口，先读什么是上下文窗口，它演示了窗口怎样一轮一轮被填满。

这门课说的上下文，指模型在写下一条回复之前读到的那些 token。下面讲的，就是这些 token 是什么、由谁放进去。

跟着一个值，从你的代码走到模型

挑一条事实，看它一路走到哪里。在下面这个 Agents SDK 示例里，用户的名字和 ID 放在你代码持有的一个 Python 对象里。只有当模型调用一个返回名字的工具时，它才知道这个名字。

代码复制自 SDK 的上下文管理页面，只去掉了页面上的注释标记。print 下面那行注释，是文档给出的输出。

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 智能体页面里的这段代码，每次调用都会把用户名写进系统提示词，适合模型一直需要的事实，比如名字或今天的日期。它用的 UserContext 是你自己定义的类型，和上面的 UserInfo 一样。

Anthropic 的上下文工程指南按种类整理同样的内容：系统提示词、工具、示例和消息历史，再加上智能体在工作中取来的文件、工具结果和笔记。

下表把两种看法放在一起。

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,
)

还没人开口，工具定义就占满了窗口

每个工具的名称、描述和输入结构都会随请求一起发出去。Anthropic 在 2025 年 11 月 24 日发布的高级工具使用文章里，算了五个常见 MCP 服务器的账：58 个工具在对话开始之前，就占了大约 55K 个 token。单是 Jira 一个，就还要再加大约 17K。文章还说，在 Anthropic 内部，工具定义在优化之前一度达到 134K 个 token。

如果任务只涉及 GitHub，那些 Slack 工具就是模型读了却用不上的 21K 个 token。解决办法在这条学习路径的后面。AI 智能体的工具讲怎样用更少、更大的工具，按需载入上下文讲怎样等某一步用到时，才载入工具或文件。先从数清你今天发出了多少开始。

它和提示词工程有什么不同

提示词工程讲的是怎样写指令、怎样排顺序，主要写在系统提示词里。上下文工程包含这些，也包含请求里的其余部分，而且永远没有做完的时候。Anthropic 的指南说它是反复进行的：每次往模型里传东西，都要重新挑一次。

指南的工作原则，是只留下对目标结果有用的 token。落到系统提示词上，就是找准高度：具体到能引导模型，又不必为每种情况硬写 if-else 规则。落到示例上，几个多样、典型的例子，胜过一长串边缘情况。落到工具上，指南的标准说得很直白：如果一位人类工程师都说不准某个情况该用哪个工具，智能体也不会做得更好。

上下文一长，还会带来另一个问题。上下文越长，模型准确回忆其中信息的能力越弱，下一课上下文腐化会拿数据说明这一点。智能体记忆讲的压缩和笔记，能让长任务在窗口占满之后继续下去。可如果请求一开始就没挑好，这两样都帮不上忙。

Tobi Lütke、Andrej Karpathy 和 Dex Horthy 谈掌控上下文

这个说法是在 2025 年 6 月流行起来的。Shopify 首席执行官 Tobi Lütke 在 6 月 19 日写道，他更喜欢“上下文工程”这个词，而不是“提示词工程”，因为它更准确地说出了核心技能。

六天后，OpenAI 创始成员之一 Andrej Karpathy 表示赞同，还列出了上下文里装的东西：任务描述和说明、少样本示例、RAG、相关数据、工具、状态和历史，以及压缩。给得太少，模型缺少需要的信息；给得太多或者不相干，成本可能上升，表现反而下降。

HumanLayer 的 Dex Horthy 更早就在 GitHub 上的指南 12-factor agents 里讲过这个道理。按指南自己的说法，它比这个词流行早了大约两个月。第三条原则叫“掌控你的上下文窗口”，它说标准的消息格式并不是必须的。指南把整个运行过程装进一条用户消息，写成一串带标签的事件，这样已经解决的错误可以删掉，工具结果也可以剪到下一步需要的长度。Agents SDK 会替你组装消息；自己写循环的话，就可以走这条路。

2025 年 9 月 30 日，Anthropic 在 X 上推荐了它的指南，对象是熟悉提示词工程、正在搭建智能体的开发者。

X 官方嵌入卡片的截图，拍摄于 2026 年 11 月 5 日和 6 日，时间为 UTC。Anthropic 那张卡片省略了原帖结尾的链接。点击截图可到 X 上打开原帖。

常见错误

• 错误答案其实来自历史深处一个过时的工具结果，却一遍遍改写系统提示词。
• 把在任何地方用过的 MCP 服务器都接上，工具定义挤占了任务本身的空间。
• 以为代码知道的事，模型也知道。SDK 的 context 对象从来不会到达模型。
• 某一步只需要几行，却把整个文件或整个网页作为工具结果返回。
• 把更大的上下文窗口，当成可以多发内容的许可。

自己试一试

• 把 fetch_user_age 从 tools=[...] 里拿掉，再问同一个问题。名字现在还能从哪里来？
• 给智能体换上文档里的 dynamic_instructions，类型改成 UserInfo，不给任何工具，再问用户的名字。
• 把你自己的智能体一次请求里的每个部分都写下来，给每部分估一个 token 数，标出当前这一步用不上的内容。

常见问题

资料来源

1. Anthropic Engineering: Effective context engineering for AI agents (2026年11月6日 查阅)https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents
2. Anthropic Engineering: Introducing advanced tool use on the Claude Developer Platform (2026年11月6日 查阅)https://www.anthropic.com/engineering/advanced-tool-use
3. OpenAI API docs: Function calling (2026年11月6日 查阅)https://developers.openai.com/api/docs/guides/function-calling
4. OpenAI Agents SDK docs on GitHub: Context management (2026年11月6日 查阅)https://github.com/openai/openai-agents-python/blob/main/docs/context.md
5. OpenAI Agents SDK docs on GitHub: Agents (dynamic instructions) (2026年11月6日 查阅)https://github.com/openai/openai-agents-python/blob/main/docs/agents.md
6. GitHub: openai/openai-agents-python README (2026年11月6日 查阅)https://github.com/openai/openai-agents-python
7. GitHub: 12-factor agents, factor 3, own your context window (2026年11月6日 查阅)https://github.com/humanlayer/12-factor-agents/blob/main/content/factor-03-own-your-context-window.md
8. X: Tobi Lütke on the term context engineering (2026年11月6日 查阅)https://x.com/tobi/status/1935533422589399127
9. X: Andrej Karpathy on context engineering (2026年11月6日 查阅)https://x.com/karpathy/status/1937902205765607626
10. X: Anthropic shares its context engineering guide (2026年11月6日 查阅)https://x.com/AnthropicAI/status/1973098580060631341
11. YouTube (AI Engineer): 12-Factor Agents, Dex Horthy, HumanLayer (2026年11月6日 查阅)https://www.youtube.com/watch?v=8kMaTybvDUw