一、核心定位：上下文决定Agent能力上限
-
基础定义
上下文是每一轮调用LLM时模型所能读取的全部信息集合，包含系统指令、工具定义、对话历史、用户消息、工具返回结果 ；模型仅能依据上下文做出决策，类比为Agent的"视觉输入"。
上下文工程并非简单堆砌提示词，而是一套系统性信息供给方案 ，属于Harness工程中「上下文与工具」模块的核心实现，解决：在有限上下文窗口内，给模型提供哪些信息、以何种结构提供。
-
关键结论
模型原生能力只是基础，上下文质量才是Agent真实能力的天花板 。中等规格模型搭配精心组织的上下文，性能通常优于顶级模型在信息缺失条件下的表现。
业务落地痛点：大量团队知识属于隐性知识（口头约定、私有架构、零散文档），如同信息黑洞；AI Agent类似永久新人，缺少完备背景信息就无法发挥价值。搭建AI原生团队的前置工作是业务知识文档化、结构化。
核心观点引用：人与大模型共同的约束都是Context；团队协作最大障碍是上下文不一致；AI难以完全替代人类的根本原因之一------AI无法共享人类所处真实环境的上下文。
- 硬件约束：上下文窗口（Context Window）
所有输入内容序列化为Token送入Transformer处理，不同模型窗口容量存在上限（Qwen3 32K、Claude 200K、Gemini 2M tokens）。上下文窗口是稀缺资源，无差别灌入信息会引入噪声、触发截断，降低模型推理准确率。
二、API底层原理：Agent调用大模型标准结构
主流Chat Completions API（OpenAI、Anthropic、vLLM/Ollama兼容接口）以messages消息列表 作为上下文载体，API本身无状态，每一轮请求必须完整传入所需全部信息。
2.1 四大消息角色（role）
system：系统提示词。定义Agent身份、约束、全局规则，优先级最高，通常固定放置在消息头部；user：终端用户原始请求；assistant：模型输出内容，包含文本回复或工具调用请求tool_calls；tool：工具执行结果，依靠tool_call_id与模型发起的工具调用一一绑定。
补充：工具定义
tools独立于messages列表，单独传递，告知模型可用函数、参数规范。
2.2 两种交互模式
-
单轮问答（无工具调用）
消息结构：
system + user→ 模型直接返回assistant文本回复，适合简单问答场景。 -
带工具调用的多轮ReAct循环（Agent标准运行模式）
完整执行链路：
① 请求传入
system + user + tools，模型判断需要外部信息，返回携带tool_calls的assistant消息；② Agent框架而非模型 负责执行工具函数；
③ 将完整历史（原有全部messages）+
tool结果重新组装请求送入模型；④ 模型基于观测结果判断：继续调用工具，或生成最终文本回复终止循环。
消息列表messages持续追加迭代，完整保留交互轨迹，这就是ReAct（思考-行动-观测）在API层面的落地实现。
2.3 最简Python Agent核心循环逻辑
整体依靠while循环驱动，两条核心分支判断：
- 模型返回
tool_calls：执行工具，追加tool消息，继续循环调用LLM； - 无工具调用请求：输出最终答案，结束会话。
生产环境必须增加最大迭代次数限制，防止Agent陷入无限循环重复调用工具。
三、上下文分层架构：静态前缀 + 动态轨迹
所有请求上下文可以拆分为两层，该结构是KV Cache、上下文压缩优化的理论基础：
- 静态前缀（全程保持不变）
System Prompt + Tools定义。固定不变的前缀可以被推理框架缓存（KV Cache），大幅降低首token延迟（TTFT）。 - 动态轨迹（持续增长）
user/assistant/tool消息组成的对话历史。会话越长占用token越多，也是后续上下文裁剪、摘要压缩的优化对象。
重要现象（本地实验佐证）：修改System Prompt内容会破坏KV Cache缓存，推理需要重新计算全部前缀，响应延迟明显上升；保持前缀不变则缓存命中，推理加速。
四、实验2-1：本地LLM部署与工具调用核心结论
基于Qwen3-0.6B小模型本地部署实验，打破"必须超大参数模型才能实现工具调用"认知：
- 模型规模不是唯一瓶颈
0.6B超小参数量模型，依靠合理提示工程，可稳定完成工具调用、并行工具请求、多轮ReAct循环；端侧运行小型具备工具能力的Agent具备可行性。 - 模型内部运行细节（API不可见）
- 支持CoT的模型会通过``标签输出内部思考过程，对Agent行为调试至关重要；
- 输出顺序：内部思考 → 文本回复 → 工具调用；流式架构可实现工具并行预执行；
- 无依赖关系的工具支持并行调用，由Agent框架并发执行，缩短整体耗时。
- 工程观测要点
可借助本地服务直观观测Token流、KV Cache对TTFT的影响，为线上上下文优化提供实验依据。
五、延伸技术路线（本章后续议题）
上下文分层架构衍生出一系列工程课题：
- 利用静态前缀不变性优化KV Cache推理速度；
- System Prompt规范化设计（提示工程）；
- 提示注入防御；
- 按需加载专业知识（Agent Skills）；
- 动态注入运行状态；
- 超长会话历史的智能压缩、截断策略。
六、实践启示（工程落地准则）
- 开发Agent优先梳理任务所需三类上下文：业务代码/数据结构、流程规范、环境配置；缺少任意一类，Agent输出极易脱离真实工程环境；
- 不要盲目追求更大参数模型，优先评估当前上下文信息是否完备、结构是否合理；
- 会话设计上区分静态规则与动态会话历史，最大化利用KV Cache优化推理性能；
- 长会话场景必须预留上下文治理方案（压缩、摘要、滑动窗口截断），避免持续token膨胀。