Session 03: context engineering, part 1 — what does the LLM actually see?
在 Agent 开发中,我们经常会说“把上下文传给模型”。这句话包含有不少细节:程序需要决定发送哪些消息,工具定义放在哪里,历史记录保留多少,工具执行结果怎样放回对话,以及如何知道一次请求用了多少 Token。
这一篇先把这些基础问题讲清楚。我们会用 Python 实现一个研究 AI Agent 技术的 Agent,让它搜索资料、分析证据,最后生成研究报告。本文重点放在 Context 的组成和构造上;上下文太长以后怎么裁剪、摘要和检索,会放到下一篇展开。
一、Context、Prompt 和 Message History
先把几个容易混在一起的词分开:
Prompt 通常指为了引导模型完成任务而提供的输入内容,可以包括系统指令、任务要求、示例和其他上下文。
Context 的范围更广一些,指模型在当前这次调用中能够使用的信息。Context 常常由多条消息、工具定义、当前任务状态以及其他请求参数共同构成,具体内容取决于所使用的模型接口。
Message History 是程序保存的对话消息记录。它通常包含用户说过的话、模型之前的回复,以及工具调用和工具返回结果。History 是 Context 的常见组成部分,但二者不是同一个概念:程序可以保存很长的历史,却只挑选其中一部分发送给模型;也可以在原有历史之外,额外加入检索到的资料到context。
例如,我们正在做一个研究 Agent,任务是研究 Context Engineering 并生成一份带有来源的报告。最初发送给模型的内容可以很简单:
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 后,可以通过类似下面的代码发起请求:
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 密钥、个人数据或其他机密内容。
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、网页检索程序或自己的资料库查询逻辑。
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 使用的工具定义格式:
tools = [
{
"type": "function",
"function": {
"name": "search_sources",
"description": (
"搜索 AI Agent 技术研究所需的资料。"
"返回资料标题、链接和摘要。"
),
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "需要搜索的主题或关键词",
}
},
"required": ["query"],
"additionalProperties": False,
},
},
}
]
工具定义是请求中的另一部分,不是普通对话消息。调用时,程序通过 tools 参数把定义交给模型:
response = client.chat.completions.create(
model="gpt-4.1-mini",
messages=messages,
tools=tools,
tool_choice="auto",
)
如果模型判断需要搜索,返回内容可能类似下面这样。具体字段和序列化格式会随接口而变化,下面展示的是便于理解的简化结构:
{
"role": "assistant",
"content": null,
"tool_calls": [
{
"id": "call_001",
"type": "function",
"function": {
"name": "search_sources",
"arguments": "{\"query\":\"Agent Context Engineering\"}"
}
}
]
}
这条消息表示模型提出了一个工具调用请求。它并没有执行搜索,也没有直接访问程序里的 search_sources 函数。程序需要读取工具名称和参数,检查参数是否有效,再决定调用哪个本地函数。
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 消息:
messages.append(response.choices[0].message)
messages.append({
"role": "tool",
"tool_call_id": tool_call.id,
"content": result,
})
此时消息历史中至少包含三类内容:最初的任务说明、模型发出的工具调用,以及程序返回的工具结果。下一次调用时,模型才能看到自己刚才要求执行什么,以及工具实际返回了什么。
一次工具交互可以简化成下面的过程:
程序 -> 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,并设置最大调用轮数,避免模型持续调用工具而不结束。
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 文件:
# source_evaluation
评估研究资料时:
1. 优先检查原始论文、官方文档和作者原文。
2. 记录标题、URL、发布日期和访问日期。
3. 区分资料中明确陈述的事实与作者的观点。
4. 不要仅凭搜索摘要作出关键结论。
5. 对互相矛盾的资料保留差异,不要强行合并成一个结论。
如果每次调用都把所有 Skill 的完整内容塞进请求,会增加输入长度,也会把当前任务暂时用不到的说明一起带上。
下面用普通 Python 演示这种加载过程。它只是一个简单的应用层设计示例,并不代表所有框架都按这种方式传递 Skill:
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 后,可以把内容放进下一次请求中的合适位置。例如,框架允许时,可以把它作为开发者指令的一部分;也可以按照框架的设计,通过其他消息或结构化字段传入。关键在于明确这段内容最终是否真的进入了模型请求,而不是只在程序本地读取了文件。
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:
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 可能连续搜索很多轮,单次请求的用量看起来不大,累积起来却可能明显增加成本。
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 干货。