AI Agent / 系统课时
设计 Context Builder
设计 Context Builder
本篇解决智能体上下文如何统一组装的问题,最终实现一个可维护的上下文构建流程,把系统规则、任务目标、项目知识、历史状态和工具结果转换为模型可理解的输入。
学习目标
- 理解 Context Builder 在智能体运行链路中的职责
- 掌握多来源上下文的组合方式和优先级设计
- 能够实现一个基础的上下文构建模块
Context Builder 解决什么问题
智能体执行任务时,需要同时处理多种信息来源。如果每个模块直接拼接提示词,会导致上下文结构混乱、规则覆盖不可控,也难以调整不同任务需要的信息比例。
Context Builder 的职责是把离散信息转换为统一上下文对象,再生成最终发送给模型的输入。它不是简单字符串拼接,而是一个具有规则管理能力的数据组装层。

上下文数据的分层设计
一个常见设计方式是按照稳定程度划分上下文层级:
| 层级 | 内容 | 特点 |
|---|---|---|
| 系统层 | 角色规则、安全约束 | 最稳定,优先级最高 |
| 任务层 | 当前目标、输入参数 | 随任务变化 |
| 知识层 | 文档、代码、业务资料 | 按需加载 |
| 状态层 | 历史步骤、中间结果 | 持续更新 |
| 工具层 | API 返回、执行观察 | 临时信息 |
不同层级需要不同生命周期管理。系统规则通常长期存在,而工具观察结果只在当前执行阶段有效。
实现一个基础 Context Builder
实际项目中,可以先使用结构化对象保存上下文,再由渲染层生成模型输入。
python
from dataclasses import dataclass, field
@dataclass
class AgentContext:
system_rules: list[str] = field(default_factory=list)
task: str = ""
knowledge: list[str] = field(default_factory=list)
history: list[str] = field(default_factory=list)
observations: list[str] = field(default_factory=list)
class ContextBuilder:
def build(self, context: AgentContext) -> str:
sections = [
"系统规则:\n" + "\n".join(context.system_rules),
"任务目标:\n" + context.task,
"相关知识:\n" + "\n".join(context.knowledge),
"历史状态:\n" + "\n".join(context.history),
"工具观察:\n" + "\n".join(context.observations),
]
return "\n\n".join(sections)预期输出
text
系统规则:
遵守工具调用约束
任务目标:
完成代码检查
相关知识:
项目架构文档
历史状态:
已完成文件扫描
工具观察:
发现两个待修复问题设计时的关键边界
Context Builder 需要避免两个常见问题。第一,不应无限加入所有历史信息,否则模型注意力会被无关内容消耗。第二,不应让低优先级信息覆盖系统规则,否则可能产生不可预测行为。
实际系统通常会在 Builder 内增加排序、过滤、截断和权限检查,让进入模型的内容始终符合当前任务需求。
本课总结
- Context Builder 是智能体上下文管理的统一入口,不只是文本拼接工具。
- 不同上下文来源需要按照稳定性和优先级进行分层管理。
- 良好的上下文构建设计可以提升智能体执行稳定性。
下一课预告
下一课将介绍如何裁剪对话历史,在有限上下文窗口中保留真正有价值的信息。
按自己的节奏,确认真正理解。