一、核心定位：上下文决定Agent能力上限

1. 基础定义
   上下文是每一轮调用LLM时模型所能读取的全部信息集合，包含系统指令、工具定义、对话历史、用户消息、工具返回结果；模型仅能依据上下文做出决策，类比为Agent的“视觉输入”。
   上下文工程并非简单堆砌提示词，而是一套系统性信息供给方案，属于Harness工程中「上下文与工具」模块的核心实现，解决：在有限上下文窗口内，给模型提供哪些信息、以何种结构提供。

2. 关键结论
   模型原生能力只是基础，上下文质量才是Agent真实能力的天花板。中等规格模型搭配精心组织的上下文，性能通常优于顶级模型在信息缺失条件下的表现。
   业务落地痛点：大量团队知识属于隐性知识（口头约定、私有架构、零散文档），如同信息黑洞；AI Agent类似永久新人，缺少完备背景信息就无法发挥价值。搭建AI原生团队的前置工作是业务知识文档化、结构化。

核心观点引用：人与大模型共同的约束都是Context；团队协作最大障碍是上下文不一致；AI难以完全替代人类的根本原因之一——AI无法共享人类所处真实环境的上下文。

3. 硬件约束：上下文窗口（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 两种交互模式

1. 单轮问答（无工具调用）
   消息结构：system + user → 模型直接返回assistant文本回复，适合简单问答场景。

2. 带工具调用的多轮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、上下文压缩优化的理论基础：

1. 静态前缀（全程保持不变）
   System Prompt + Tools定义。固定不变的前缀可以被推理框架缓存（KV Cache），大幅降低首token延迟（TTFT）。
2. 动态轨迹（持续增长）
   user/assistant/tool消息组成的对话历史。会话越长占用token越多，也是后续上下文裁剪、摘要压缩的优化对象。

重要现象（本地实验佐证）：修改System Prompt内容会破坏KV Cache缓存，推理需要重新计算全部前缀，响应延迟明显上升；保持前缀不变则缓存命中，推理加速。

四、实验2-1：本地LLM部署与工具调用核心结论

基于Qwen3-0.6B小模型本地部署实验，打破“必须超大参数模型才能实现工具调用”认知：

1. 模型规模不是唯一瓶颈
   0.6B超小参数量模型，依靠合理提示工程，可稳定完成工具调用、并行工具请求、多轮ReAct循环；端侧运行小型具备工具能力的Agent具备可行性。
2. 模型内部运行细节（API不可见）

• 支持CoT的模型会通过``标签输出内部思考过程，对Agent行为调试至关重要；
• 输出顺序：内部思考 → 文本回复 → 工具调用；流式架构可实现工具并行预执行；
• 无依赖关系的工具支持并行调用，由Agent框架并发执行，缩短整体耗时。

3. 工程观测要点
   可借助本地服务直观观测Token流、KV Cache对TTFT的影响，为线上上下文优化提供实验依据。

五、延伸技术路线（本章后续议题）

上下文分层架构衍生出一系列工程课题：

1. 利用静态前缀不变性优化KV Cache推理速度；
2. System Prompt规范化设计（提示工程）；
3. 提示注入防御；
4. 按需加载专业知识（Agent Skills）；
5. 动态注入运行状态；
6. 超长会话历史的智能压缩、截断策略。

六、实践启示（工程落地准则）

1. 开发Agent优先梳理任务所需三类上下文：业务代码/数据结构、流程规范、环境配置；缺少任意一类，Agent输出极易脱离真实工程环境；
2. 不要盲目追求更大参数模型，优先评估当前上下文信息是否完备、结构是否合理；
3. 会话设计上区分静态规则与动态会话历史，最大化利用KV Cache优化推理性能；
4. 长会话场景必须预留上下文治理方案（压缩、摘要、滑动窗口截断），避免持续token膨胀。