Session 03: context engineering, part 1 — what does the LLM actually see?

在 Agent 开发中,我们经常会说“把上下文传给模型”。这句话包含有不少细节:程序需要决定发送哪些消息,工具定义放在哪里,历史记录保留多少,工具执行结果怎样放回对话,以及如何知道一次请求用了多少 Token。

Originally in ChineseThis article was written in Chinese. The body below is the Chinese original; the English translation is not available yet.

这一篇先把这些基础问题讲清楚。我们会用 Python 实现一个研究 AI Agent 技术的 Agent,让它搜索资料、分析证据,最后生成研究报告。本文重点放在 Context 的组成和构造上;上下文太长以后怎么裁剪、摘要和检索,会放到下一篇展开。

一、Context、Prompt 和 Message History

先把几个容易混在一起的词分开:

Prompt 通常指为了引导模型完成任务而提供的输入内容,可以包括系统指令、任务要求、示例和其他上下文。

Context 的范围更广一些,指模型在当前这次调用中能够使用的信息。Context 常常由多条消息、工具定义、当前任务状态以及其他请求参数共同构成,具体内容取决于所使用的模型接口。

Message History 是程序保存的对话消息记录。它通常包含用户说过的话、模型之前的回复,以及工具调用和工具返回结果。History 是 Context 的常见组成部分,但二者不是同一个概念:程序可以保存很长的历史,却只挑选其中一部分发送给模型;也可以在原有历史之外,额外加入检索到的资料到context。

例如,我们正在做一个研究 Agent,任务是研究 Context Engineering 并生成一份带有来源的报告。最初发送给模型的内容可以很简单:

python
messages = [
    {
        "role": "system",
        "content": (
            "你是一个 AI Agent 技术研究助手。"
            "研究时要区分事实、观点和推测;重要结论尽量附上来源。"
        ),
    },
    {
        "role": "user",
        "content": (
            "研究 Agent 的 Context Engineering,"
            "整理核心概念、常见工程问题和解决方案,最后生成研究报告。"
        ),
    },
]

这里的 messages 是程序准备发送给模型的消息列表。system 提供相对稳定的行为要求,user 给出当前任务。不同模型 API 对角色名称和请求结构可能有自己的约定,写代码时需要以实际使用的接口为准。其实这里可以做一个delegation层。

模型并不会自动读取程序里的其他变量、项目目录或数据库。除非程序把相关内容放进请求,或者通过模型可调用的工具让模型获得这些信息,否则这些内容就不属于当前调用的输入。

二、一次请求里究竟发送了什么

下面使用 OpenAI Python SDK 的 Chat Completions 接口演示消息传递。安装 SDK 并配置好 OPENAI_API_KEY 后,可以通过类似下面的代码发起请求:

python
from openai import OpenAI

client = OpenAI()

response = client.chat.completions.create(
    model="gpt-4.1-mini",
    messages=messages,
)

answer = response.choices[0].message
print(answer.content)
print(response.usage)

messages 是请求中的核心输入之一。模型收到消息后返回一个 assistant 消息,程序再从响应中读取内容。真实项目里还需要处理网络错误、超时、空响应和模型返回格式等情况,这里先聚焦于消息本身。

从程序的角度看,模型调用不是把整个 Python 程序交给模型执行,而是发送一份请求数据。模型只能根据这次请求中可用的信息生成结果,程序则负责保存消息、调用外部工具、控制执行流程,并决定下一次请求携带什么内容。

为了调试上下文,开发时可以把准备发送的消息打印出来。实际项目可能包含敏感信息,日志应根据需要做脱敏处理,不要不加区分地记录 API 密钥、个人数据或其他机密内容。

python
import json

def log_messages(messages):
    print(json.dumps(messages, ensure_ascii=False, indent=2))

log_messages(messages)

这份日志可以帮助我们检查消息是否按预期组织。例如,程序是否把上一次工具结果加入历史、是否重复塞入了同一段资料、是否把过时的任务说明继续发送给模型。这些问题单靠查看最终回答通常不容易定位。

三、Tool Definition、Tool Call 和 Tool Result

研究 Agent 需要搜索资料,但模型本身并不会因为收到“请搜索资料”这句话,就自动访问互联网。程序需要提供搜索工具,并负责真正执行搜索。

工具一般包含两部分:一份提供给模型的工具定义,以及一段由程序执行的函数。工具定义让模型知道工具的名称、用途和参数格式;函数实现负责完成实际工作。通常不会把整个函数源码发送给模型。

下面定义一个 search_sources 工具。为了让示例可以独立阅读,这里的搜索函数先返回模拟结果,实际项目中可以把函数体替换为搜索 API、网页检索程序或自己的资料库查询逻辑。

python
def search_sources(query: str) -> str:
    """搜索与研究主题相关的资料。这里用模拟数据代替真实搜索服务。"""
    mock_results = [
        {
            "title": "Context Engineering Overview",
            "url": "https://example.com/context-engineering",
            "snippet": "Context engineering focuses on selecting and organizing information supplied to a model.",
        },
        {
            "title": "Long Context and Retrieval",
            "url": "https://example.com/long-context",
            "snippet": "Longer input can increase cost and latency, and relevant information may not be used consistently.",
        },
    ]
    return json.dumps(mock_results, ensure_ascii=False)

接着,把工具的名称、说明和参数 Schema 提供给模型。下面是 Chat Completions 使用的工具定义格式:

python
tools = [
    {
        "type": "function",
        "function": {
            "name": "search_sources",
            "description": (
                "搜索 AI Agent 技术研究所需的资料。"
                "返回资料标题、链接和摘要。"
            ),
            "parameters": {
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "需要搜索的主题或关键词",
                    }
                },
                "required": ["query"],
                "additionalProperties": False,
            },
        },
    }
]

工具定义是请求中的另一部分,不是普通对话消息。调用时,程序通过 tools 参数把定义交给模型:

python
response = client.chat.completions.create(
    model="gpt-4.1-mini",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

如果模型判断需要搜索,返回内容可能类似下面这样。具体字段和序列化格式会随接口而变化,下面展示的是便于理解的简化结构:

json
{
  "role": "assistant",
  "content": null,
  "tool_calls": [
    {
      "id": "call_001",
      "type": "function",
      "function": {
        "name": "search_sources",
        "arguments": "{\"query\":\"Agent Context Engineering\"}"
      }
    }
  ]
}

这条消息表示模型提出了一个工具调用请求。它并没有执行搜索,也没有直接访问程序里的 search_sources 函数。程序需要读取工具名称和参数,检查参数是否有效,再决定调用哪个本地函数。

python
import json

available_tools = {
    "search_sources": search_sources,
}

tool_call = response.choices[0].message.tool_calls[0]
tool_name = tool_call.function.name
tool_args = json.loads(tool_call.function.arguments)

if tool_name not in available_tools:
    raise ValueError(f"未知工具:{tool_name}")

result = available_tools[tool_name](**tool_args)

在真实应用中,不能只依赖模型给出的参数。程序还应检查参数类型、长度、权限和可访问范围,并为执行设置超时及错误处理。工具能做什么,最终由程序端的实现和权限控制决定,而不是由模型在描述中声称自己能做什么来决定。

工具执行完成后,程序需要把工具调用和执行结果都加入消息历史。使用 Chat Completions SDK 时,可以把模型返回的 assistant 消息追加到 messages,再追加对应的 tool 消息:

python
messages.append(response.choices[0].message)

messages.append({
    "role": "tool",
    "tool_call_id": tool_call.id,
    "content": result,
})

此时消息历史中至少包含三类内容:最初的任务说明、模型发出的工具调用,以及程序返回的工具结果。下一次调用时,模型才能看到自己刚才要求执行什么,以及工具实际返回了什么。

一次工具交互可以简化成下面的过程:

text
程序 -> LLM
  system:研究行为要求
  user:研究 Context Engineering

LLM -> 程序
  assistant:请求调用 search_sources,参数为 query="Agent Context Engineering"

程序内部
  执行 search_sources(query="Agent Context Engineering")

程序 -> LLM
  assistant:之前的工具调用消息
  tool:搜索结果

LLM -> 程序
  assistant:根据搜索结果继续分析,或提出下一次工具调用

工具调用消息和工具结果需要正确对应。尤其是一次响应中包含多个 tool calls 时,程序应逐一执行并用正确的 tool_call_id 关联结果。不同 API 对多工具调用的消息组织有具体要求,不能随意拼接消息后就假设模型一定能够继续处理。

四、完整一点的工具调用循环

前面的代码展示了关键步骤,下面把它们放进一个较完整的循环。这个版本只处理 search_sources,并设置最大调用轮数,避免模型持续调用工具而不结束。

python
import json
from openai import OpenAI

client = OpenAI()

def search_sources(query: str) -> str:
    # 示例数据;接入真实搜索服务时替换这里的实现
    return json.dumps(
        [
            {
                "title": "Context Engineering Overview",
                "url": "https://example.com/context-engineering",
                "snippet": f"与查询主题相关的资料摘要:{query}",
            }
        ],
        ensure_ascii=False,
    )

tool_functions = {
    "search_sources": search_sources,
}

tools = [
    {
        "type": "function",
        "function": {
            "name": "search_sources",
            "description": "搜索研究主题相关的资料",
            "parameters": {
                "type": "object",
                "properties": {"query": {"type": "string"}},
                "required": ["query"],
                "additionalProperties": False,
            },
        },
    }
]

messages = [
    {
        "role": "system",
        "content": "你是 AI Agent 技术研究助手,结论应尽量有来源支持。",
    },
    {
        "role": "user",
        "content": "研究 Context Engineering,整理核心概念和工程问题。",
    },
]

for _ in range(5):
    response = client.chat.completions.create(
        model="gpt-4.1-mini",
        messages=messages,
        tools=tools,
        tool_choice="auto",
    )

    assistant_message = response.choices[0].message
    messages.append(assistant_message)

    if not assistant_message.tool_calls:
        print(assistant_message.content)
        break

    for call in assistant_message.tool_calls:
        name = call.function.name
        args = json.loads(call.function.arguments)

        if name not in tool_functions:
            tool_result = f"工具执行失败:未知工具 {name}"
        else:
            try:
                tool_result = tool_functions[name](**args)
            except Exception as exc:
                tool_result = f"工具执行失败:{type(exc).__name__}: {exc}"

        messages.append({
            "role": "tool",
            "tool_call_id": call.id,
            "content": str(tool_result),
        })
else:
    print("达到最大工具调用轮数,停止执行。")

这个循环体现了 Agent 程序的基本职责:把任务和工具定义发给模型,读取模型的工具调用请求,在程序端执行工具,把结果放回消息历史,再发起下一次请求。模型负责根据现有信息决定下一步,程序负责执行和控制流程。

五、Skill 的内容怎样进入 Context

Tool 和 Skill 经常一起出现,但它们不是同一种东西。Tool 通常是模型可以请求程序执行的一个具体操作,例如搜索网页、读取文件或查询数据库。Skill 更接近一组可复用的工作说明、步骤、约束和相关资源,具体格式由使用的 Agent 框架或应用决定。

Skill 并没有统一的 API 传输规范。有的框架会先把可用 Skill 的名称和简短描述放进指令中,有的会提供一个查找或读取 Skill 的工具;当模型选择某个 Skill 后,程序再读取完整说明,并以框架支持的方式加入后续请求。不能把某一种框架的做法当成所有 Agent 的固定规则。

例如,研究 Agent 可以有一个“评估研究来源”的 Skill,里面规定如何检查来源可靠性、如何区分原始资料和二手文章,以及如何记录证据。程序可以把 Skill 保存为一个 Markdown 文件:

markdown
# source_evaluation

评估研究资料时:
1. 优先检查原始论文、官方文档和作者原文。
2. 记录标题、URL、发布日期和访问日期。
3. 区分资料中明确陈述的事实与作者的观点。
4. 不要仅凭搜索摘要作出关键结论。
5. 对互相矛盾的资料保留差异,不要强行合并成一个结论。

如果每次调用都把所有 Skill 的完整内容塞进请求,会增加输入长度,也会把当前任务暂时用不到的说明一起带上。

下面用普通 Python 演示这种加载过程。它只是一个简单的应用层设计示例,并不代表所有框架都按这种方式传递 Skill:

python
from pathlib import Path

SKILL_DIR = Path("skills")

def load_skill(skill_name: str) -> str:
    # 这里只允许读取 skills 目录下的 Markdown 文件
    if not skill_name.replace("_", "").isalnum():
        raise ValueError("非法的 Skill 名称")

    path = (SKILL_DIR / f"{skill_name}.md").resolve()
    root = SKILL_DIR.resolve()

    if root not in path.parents:
        raise ValueError("Skill 路径越界")

    if not path.exists():
        raise FileNotFoundError(f"没有找到 Skill:{skill_name}")

    return path.read_text(encoding="utf-8")

程序读取 Skill 后,可以把内容放进下一次请求中的合适位置。例如,框架允许时,可以把它作为开发者指令的一部分;也可以按照框架的设计,通过其他消息或结构化字段传入。关键在于明确这段内容最终是否真的进入了模型请求,而不是只在程序本地读取了文件。

python
skill_text = load_skill("source_evaluation")

messages = [
    {
        "role": "system",
        "content": "你是 AI Agent 技术研究助手。",
    },
    {
        "role": "developer",
        "content": f"执行研究时遵循以下来源评估规范:\n{skill_text}",
    },
    {
        "role": "user",
        "content": "评估已经找到的资料,并整理可信证据。",
    },
]

上面展示的是消息组织示例,是否支持 developer 角色、应当把 Skill 放在哪个位置,需要按实际 API 和框架确认。Skill 也可能包含不可信的外部资料或引用内容,因此应把规则说明与外部检索文本区分开,不能把网页中的指令直接当成高优先级的系统规则。

六、Token 用量怎样记录

Context 的长度通常以 Token 衡量。Token 不是简单的字符数或单词数;中文、英文、代码、标点和特殊格式的切分方式都可能不同,因此不能仅凭字符数量准确推算 Token。

一次模型调用的返回结果通常会包含用量信息。以 Chat Completions 为例,可以读取响应中的 usage:

python
response = client.chat.completions.create(
    model="gpt-4.1-mini",
    messages=messages,
)

usage = response.usage

if usage is not None:
    print("输入 Token:", usage.prompt_tokens)
    print("输出 Token:", usage.completion_tokens)
    print("总 Token:", usage.total_tokens)

不同模型和 API 返回的字段可能不同,有些接口还会提供缓存输入 Token、推理 Token 等额外统计。记录日志时应保存实际响应中的字段,不要假设所有模型都提供完全相同的用量信息。

工程上通常会同时记录每次调用的输入和输出用量,并按任务汇总。研究 Agent 可能连续搜索很多轮,单次请求的用量看起来不大,累积起来却可能明显增加成本。

python
def record_usage(response, usage_log: list[dict]) -> None:
    usage = getattr(response, "usage", None)
    if usage is None:
        return

    usage_log.append({
        "prompt_tokens": getattr(usage, "prompt_tokens", None),
        "completion_tokens": getattr(usage, "completion_tokens", None),
        "total_tokens": getattr(usage, "total_tokens", None),
    })

usage_log = []
# 每次调用拿到 response 后执行:
# record_usage(response, usage_log)

实际应用可以把这些数据写入日志、数据库或监控系统,再按模型价格估算成本,也可以在累计用量超过阈值时提示用户或停止任务。阈值应结合模型上下文窗口、输出预算、任务长度和成本要求设置,不存在适用于所有模型的统一百分比。

还要区分 Token 用量和上下文窗口。usage 反映的是某次请求的实际用量;上下文窗口则是模型对一次调用可处理内容的容量限制。程序在发起请求前,通常需要估算输入长度并为模型输出预留空间。模型、接口和推理模式不同,窗口计算方式也可能不同,不能只把输入 Token 数与窗口上限做简单比较就忽略输出预算。

七、长上下文会带来哪些工程问题

随着研究 Agent 不断搜索资料,消息历史会逐渐增长。如果每一轮都把之前所有消息、完整网页内容和工具结果重新发送,输入 Token 数量就会持续增加,成本和响应延迟也可能上升。很多 API 调用需要再次提交当前请求所需的消息,因此程序如何维护消息历史,会直接影响后续请求的规模。

长度还不是唯一问题。上下文即使没有超过模型的窗口,也不代表模型能够同样有效地利用每一段信息。研究和评测中观察到,相关信息放在长文本中的不同位置时,模型使用它们的效果可能存在差异;这类现象常被称为 “Lost in the Middle”。它并不意味着所有模型都固定地忽略中间内容,但提醒开发者不能把“模型能接收这么多 Token”直接等同于“模型能稳定利用所有内容”。

研究任务还容易出现信息干扰。早期搜索结果可能过时,多个来源可能互相矛盾,某个网页的摘要也可能遗漏关键限定条件。如果程序一直保留旧信息,却没有标记时间、来源和可信程度,模型可能把不同阶段的结论混在一起,最终生成看似连贯、实际证据不足的报告。

上下文超限还可能破坏工具调用流程。假设历史中有一条 assistant 消息请求执行工具,但对应的 tool result 在裁剪时被删除,或者只保留了工具结果却丢掉了调用消息,下一次请求就可能包含不完整的交互记录。消息历史不能简单地当成任意文本切片,裁剪时必须考虑消息之间的依赖关系,以及所用 API 对工具调用序列的要求。

外部资料还涉及信任边界。搜索到的网页可能包含错误信息,也可能故意写入“忽略之前的指令”之类的内容。程序应把这类文本当作待分析的数据,而不是新的系统指令;工具权限也应由程序控制,不能因为网页或模型提出要求,就自动执行高风险操作。

这些问题会在下一阶段集中出现:程序需要控制历史增长,同时保留研究任务真正需要的信息。常见做法包括删除无关历史、压缩较早的对话、把任务状态单独保存、按需检索相关资料,以及分层组织指令和证据。它们各有取舍,不能简单地认为某一种方法永远最好。

八、本篇代码和下一篇的范围

本篇实现了研究 Agent 的基础消息结构、工具定义与执行循环、Skill 文件读取示例,以及 Token 用量记录。

下一篇会继续使用这个 Agent,重点比较几种上下文管理方式:直接裁剪历史、摘要旧内容、维护结构化任务状态,以及把资料放在外部存储中并按需检索。我们会关注输入 Token 的变化、关键信息是否保留、研究结论是否受到影响,并进一步讨论 Prompt Caching、模型推理时的 KV Cache,以及在 LangGraph 中如何管理状态和上下文。

希望这篇文章能对你有所帮助。关注我,持续分享更多实用、好用的 AI 干货。

On this page