个人主页代码不加冰欢迎来访作者简介java后端学习者❄️个人专栏LeetCode刷题日记 苍穹外卖日记SSM框架深入JavaWeb✨命运的结局尽可永在不屈的挑战却不可须臾或缺前言大家好我是代码不加冰今天是0-1agent的源码的第二期我们接着上一期的内容继续学习。摘要本文深入分析了LangChain4j框架中的上下文工程实现机制重点探讨了AI Agent如何通过动态上下文管理实现智能交互。文章从四个维度展开1系统指令的动态组装通过反射和模板引擎实现运行时变量注入2滑动窗口管理采用智能淘汰策略确保系统提示词安全并处理工具调用结果的连锁依赖3工具循环机制实现ReAct架构下的上下文动态增长与Token优化4多Agent协作通过共享状态总线和智能摘要实现跨Agent上下文传递。文章揭示了上下文工程在提升Agent智能性、降低Token消耗方面的核心作用展示了生产级AI系统的精细设计考量。上下文工程在 AI Agent 的开发中上下文工程Context Engineering可以被比作 Agent 的工作内存因为大语言模型LLM本质上是无状态的——它不记得你一秒前说了什么。上下文工程的核心任务就是在 LLM 有限的 Token 窗口Context Window内动态、高效地组装、筛选和淘汰最相关的“角色设定”、“短期历史”、“长期记忆”和“外部环境状态”让 Agent 能够拥有连续、聪明的思考能力。Agent 上下文工程的四大支柱在设计一个 Agent 的上下文时我们通常在往它的 Context Window 里塞四种东西系统指令System Prompt / Persona定义 Agent 的角色、技能、不能触碰的红线以及如何使用工具的“说明书”。多轮对话记忆Chat Memory这是狭义上的记忆包含用户和 AI 之前的对话历史。外部知识RAG Context通过向量数据库Vector Store或搜索工具检索出来的实时、私域信息。工具执行状态Tool Execution StateAgent 调用函数Function Calling后的返回结果例如“执行命令查询天气结果北京 25°C”这也必须作为上下文喂回给大模型。源码分析在 langchain4j 中上下文工程贯穿了从单 AgentAiServices到多 AgentAgentic Framework的所有层次。下面按「组装 → 窗口管理 → 工具循环 → 多 Agent 上下文传递」四层来分析。一、Agent 上下文组装与演进在 LangChain4j 中DefaultAiServices是驱动 Agent 运转的核心中枢。要理解一个 Agent 是如何从“无状态”变得“有记忆、懂业务”最直接的方法就是看它是如何组装大模型上下文的。在传统的 LLM 开发中很多人习惯把 System Prompt 写死成一个固定的字符串。但在构建复杂的生产级 AI Agent 时系统指令往往也需要是动态的。LangChain4j 的这段源码完美展示了工程上是如何优雅地解决这个问题的。1.为什么系统指令需要动态组装在 Agent 的实际业务场景中系统指令即大模型的人设和运行规则经常需要塞入运行时才能确定的变量。例如权限控制“你是一个助手。当前登录用户的角色是{{role}}他只能查看{{department}}的数据。”环境感知“当前系统时间是{{currentTime}}当前服务器的运行环境是{{env}}。”如果每次都靠手动用String.format()或号去拼接字符串代码会变得极其臃肿且难以维护。2.源码是如何拆解的我们可以把源码中prepareSystemMessage()的执行过程拆解为四步第一步定位模板findSystemMessageTemplate框架首先去寻找你的 Prompt 模板。LangChain4j 支持三种极其灵活的模板来源直接注解读取SystemMessage(你是一个AI...)里的文本。外部文件如果配置了fromResource它会去类路径下读取.txt或.md的 Prompt 文件这便于 Prompt 的独立管理和版本控制。动态提供者如果配置了systemMessageProvider它甚至能根据当前的chatMemoryId动态返回不同的系统指令。第二步反射抓取变量findTemplateVariables这是最神奇的一步。当你调用接口方法并传入参数时底层的InternalReflectionVariableResolver会利用 Java 反射技术把方法入参的变量名或者被V(name)标注的别名和实际传入的值自动打包成一个MapString, Object。第三步渲染与缝合PromptTemplate.apply拿到“模板”和“运行时变量键值对”后框架在内部引入了模板引擎。它会扫描模板中所有的{{variable}}占位符并将第二步抓取到的真实业务数据无缝替换进去。第四步封装为大模型标准对象toSystemMessage最后渲染出来的纯文本字符串会被包装成dev.langchain4j.data.message.SystemMessage对象正式作为ChatMessage管线的第一块基石送入后续的滑动窗口和大模型请求中。3. 上下文核心组装DefaultAiServices.java 这是每次 Agent 发起 LLM 调用时的核心。其本质任务就是将零散的角色设定、历史记忆和当前问题动态组装成一个临时的ListChatMessage列表。// DefaultAiServices.java 核心片段演示 ListChatMessage messages new ArrayList(); if (context.hasChatMemory()) { // ① 将最新的 System Message 注入记忆窗口保持角色设定的时效性 systemMessage.ifPresent(chatMemory::add); // ② 拔出滑动窗口内沉淀的所有历史多轮对话 messages.addAll(chatMemory.messages()); // ③ 灵魂抉择用户原始问题 vs RAG 增强问题入库 if (context.storeRetrievedContentInChatMemory) { chatMemory.add(userMessage); // 存储带 RAG 知识库碎片的膨胀消息 } else { chatMemory.add(originalUserMessage); // 仅存储用户干净的原始提问 } // ④ 将包含当前 RAG 增强信息的最终消息追加到本次发送列表中 messages.add(userMessage); } else { // ⑤ 无记忆/无状态模式纯粹的 [System User] 一波流请求 systemMessage.ifPresent(messages::add); messages.add(userMessage); }为什么会有第 ③ 步的条件分支这是一个极佳的工程权衡Trade-off设计。如果将 RAG 检索出来的海量文本userMessage一起存入 Memory会导致后续对话的 Token 消耗呈指数级爆炸且极易冲垮模型的上下文窗口。LangChain4j 允许你通过storeRetrievedContentInChatMemory配置决定是要“更长效的记忆空间存原始消息”还是“更精准的历史关联存增强消息”4. 纵览全貌一条消息的生命周期在DefaultAiServices.invoke()方法中一条消息从被 Java 接口捕获到最终呈现在 LLM 面前会经历长达 7 个阶段的精细打磨。[Method Call] │ ▼ 1. SystemMessage 模板解析 ───► 支持 {{variable}} 动态渲染 │ ▼ 2. SystemMessageTransformer ─► 提供二次定制系统指令的钩子 │ ▼ 3. RAG 知识增强 ─────────────► 将嵌入式向量检索到的私域知识注入 UserMessage │ ▼ 4. Input Guardrails ─────────► 输入安全护栏检查拦截注入攻击或违规词 │ ▼ 5. 输出格式指令追加 ───────────► 自动强转并尾缀 You must answer in JSON 等强约束 │ ▼ 6. ChatMemory 历史拼接 ───────► 与滑动窗口内的多轮历史消息合流 │ ▼ 7. ChatRequestTransformer ───► 拦截并做最终结构变换可替换或重写整条 UserMessage │ ▼ [Send to LLM]5. 两个核心设计点A. 跨 Agent ChatRequestTransformer这是整条请求链路发往 LLM 之前的最后一个物理钩子。它赋予了开发者直接修改最终ChatRequest的最高权限。 在复杂的Multi-Agent 路由拓扑或编排架构中框架层正是利用这个钩子动态地在最后关头注入跨 Agent 的上下文、路由元数据或动态 Token 预算控制。它是让 Agent 具备高级动态自适应能力的关键底座。B. 反射解耦prepareSystemMessage()LangChain4j 没有采用笨重的拼接字符串方式来处理 System Message而是利用PromptTemplate配合一套自研的InternalReflectionVariableResolver内部反射变量解析器。 通过这套组合拳它天然支持在接口方法参数上使用V(variable_name)注解。运行时框架会自动利用反射抓取入参值并无缝塞进 System Prompt 的模板中。这不仅保证了代码的强类型安全还做到了业务逻辑与 Prompt 文本的优雅分离。二、Agent的窗口管理如果说DefaultAiServices是 Agent 执行任务的流水线那么ChatMemory就是这条流水线上赖以生存的“工作内存”。大模型的上下文窗口是有限的如何优雅地处理多轮对话的淘汰与更新1. 核心逻辑滑动窗口的进出MessageWindowChatMemory的核心工作原理非常直观它像一个固定长度的队列基于ChatMemoryStore持久化。当新消息进来时如果超过了最大容量限制maxMessages就会触发驱逐机制Eviction剔除老消息。它的核心入口是add(ChatMessage message)方法但真正体现框架设计功力的是它私有的容量保底方法ensureCapacity。private static void ensureCapacity(ListChatMessage messages, int maxMessages) { while (messages.size() maxMessages) { // ① 核心策略SystemMessage 豁免权 int messageToEvictIndex 0; if (messages.get(0) instanceof SystemMessage) { messageToEvictIndex 1; // 如果第 0 位是系统提示词跳过它删除第 1 位 } ChatMessage evictedMessage messages.remove(messageToEvictIndex); // ② 核心策略孤儿工具结果“连锁垃圾回收” if (evictedMessage instanceof AiMessage aiMessage aiMessage.hasToolExecutionRequests()) { while (messages.size() messageToEvictIndex messages.get(messageToEvictIndex) instanceof ToolExecutionResultMessage) { // 自动驱逐失去母体的 ToolExecutionResultMessage messages.remove(messageToEvictIndex); } } } }2. 源码中隐藏的两个设计如果仅仅是一个普通的滑动窗口用一个LinkedList限制大小就够了。但作为生产级的 Agent 框架LangChain4j 在这里默默为开发者填了两个大模型底层协议的深坑1. System Message系统提示词在大模型的世界里SystemMessage定义了 Agent 的人格和底线。如果多轮对话聊得太嗨导致SystemMessage因为太老而被滑出去了Agent 就会瞬间失忆、人设崩塌。源码中通过两个巧妙的设计确保了系统指令的绝对安全免淘汰机制在ensureCapacity驱逐消息时代码会首先检查messages.get(0) instanceof SystemMessage。如果是指针直接向后挪一位messageToEvictIndex 1系统提示词永远不会被滑动窗口淘汰。唯一性与置顶在add()方法中如果传入的是新的SystemMessage它会主动寻找并移除旧的SystemMessage确保全局只有一个系统提示词。同时如果开启了alwaysKeepSystemMessageFirst新系统消息会被强制插入到index 0的绝对 C 位。2. 避免 OpenAI 报错孤儿工具结果的连锁防崩机制这是最精彩的细节。在 Agent 触发 Tool Calling工具调用时对话交互的标配流程是AiMessage大模型说我要调用queryWeather工具ToolExecutionResultMessage本地代码执行完工具返回北京 25°C以 OpenAI 为代表的主流大模型厂商其 API 协议有严格的校验任何一条ToolExecutionResultMessage必须紧跟在包含其ToolExecutionRequest的AiMessage后面。试想一下如果滑动窗口触发淘汰恰好把第 1 步的AiMessage给删了但由于窗口容量刚好卡住第 2 步的ToolExecutionResultMessage还残留在列表里。这时候把上下文发给 OpenAIAPI 会直接抛出400 Bad Request崩掉LangChain4j 的解法当发现被驱逐的消息evictedMessage是一个包含了工具请求的AiMessage时它会立刻启动一个while循环把紧随其后的、所有沦为“孤儿”的ToolExecutionResultMessage一并强制连带删除。这个精细的协议对齐极大提升了 Agent 在高并发工具调用下的稳定性。3. 架构设计亮点动态视窗与存储解耦除了精细的语义处理该类的类结构设计也非常贴合高级生产环境maxMessagesProvider动态窗口支持 它的窗口大小不是写死的int而是一个FunctionObject, Integer。这意味着你可以传入一个动态提供者在运行时根据当前用户的 VIP 等级、Token 剩余量动态拉大或缩小该用户的滑动窗口大小。ChatMemoryStore状态存储抽象MessageWindowChatMemory自身不承载存储底座它只负责“策略算法”裁剪、对齐。真正的持久化通过store.updateMessages托付出去。默认是内存存储但可以无缝外接 Redis 或数据库完美契合云原生微服务的无状态要求。三、Agent的工具循环如果说ChatMemory只是为 Agent 提供了静态的工作内存那么ToolService中的这个while(true)循环则是区分普通 LLM 业务调用与真正智能 Agent 的分水岭。这就是业界著名的ReActReasoning Acting推理与行动架构在 Java 工程中的具象化实现。在这个循环中大模型的每一次“思考Thought”和“行动Action”都会导致上下文像滚雪球一样动态增长。1. 源码拆解Agent 的循环以下是ToolService.java内部核心推理循环的精简与抽象它完美展示了 Token 上下文是如何在运行时被动态揉进大模型大脑的// ToolService.java 核心推理循环伪代码 while (true) { // 熔断保护防止大模型陷入工具调用的死循环导致账单破产 if (roundTripsLeft-- 0) { throw runtime(Exceeded %s tool calling round trips, maxToolCallingRoundTrips); } AiMessage aiMessage chatResponse.aiMessage(); // ① 思维沉淀LLM 的“推理思考过程”或“工具请求”立刻写入上下文 if (chatMemory ! null) { chatMemory.add(aiMessage); } else { messages.add(aiMessage); } // ② 终点判断如果 LLM 认为无需再调用任何工具代表推理结束安全退出 if (!aiMessage.hasToolExecutionRequests()) { break; } // ③ 落地行动触发本地 Java 业务工具并发或顺序执行斩获外部结果 ListToolExecutionRequest requests aiMessage.toolExecutionRequests(); MapToolExecutionRequest, ToolExecutionResult toolResults execute(requests, toolServiceContext.toolExecutors(), invocationContext); // ④ 环境反馈将工具的执行结果事实作为新上下文再次喂给模型 for (ToolExecutionResultMessage resultMessage : resultMessages) { chatMemory.add(resultMessage); // 或 messages.add(resultMessage) } // ⑤ 动态进化基于本轮结果动态探索并“发现”新工具实现工具链的联动 toolServiceContext refreshDynamicProviders(toolServiceContext, messages, invocationContext); if (toolSearchService ! null) { toolServiceContext ToolSearchService.addFoundTools(toolServiceContext, toolResults.values()); } // ⑥ 乾坤大挪移重构 ChatRequest携带最新的工具 Spec 和膨胀后的上下文再次驱动 LLM parameters parameters.overrideWith( ChatRequestParameters.builder() .toolSpecifications(toolServiceContext.effectiveTools()) .build() ); ChatRequest chatRequest context.chatRequestTransformer.apply( ChatRequest.builder().messages(messages).parameters(parameters).build(), memoryId); // 重新发牌让 LLM 基于全新的“历史工具结果”进行下一轮推理 chatResponse chatModelInvoker.apply(chatRequest); }2. 动态上下文工程在这段 ReAct 循环中LangChain4j 引入了多项顶级工程设计以解决大模型在动态调用工具时的Token 焦虑、死循环风险与幻觉问题。我们将这些机制总结如下机制 / 策略核心作用架构师视角的深度解析maxToolCallingRoundTrips熔断保护防无限死循环防御性编程的底线。当大模型生成的工具参数错误导致本地报错它可能会执着地不断重试。该机制默认 100 轮建议生产环境调小硬性切断无限套娃保护钱包。ReturnBehavior.IMMEDIATE工具执行完毕后立即截断返回极其强悍的 Token 节流方案。有些工具如“发送邮件”执行完后业务不需要大模型继续对着邮件结果总结陈词。直接返回能硬生生掐断后续的上下文膨胀。动态ToolProvider运行时工具的“动态发现”打破静态工具池的限制。Agent 可以根据第一轮工具返回的权限、用户状态在第两轮动态加入原本 LLM 看不到的敏感工具实现渐进式权限感知。ToolSearchStrategy巨量工具池的 Token 优化器解决“工具爆炸”引发的 Token 灾难。如果你有 100 个工具全部塞给 Spec 会直接挤爆上下文。该策略只给模型暴露一个searchTools工具按需捞取按需暴露。ChatRequestTransformer每一轮次的终极拦截器跨轮次上下文整容。在每一次while循环重新调用 LLM 之前开发者都有机会利用这个拦截器去动态裁剪、压缩上一轮产生的冗余工具日志。HallucinatedToolNameStrategy幻觉工具名称的容错策略对抗大模型失控的防波堤。当 LLM 自作聪明发明了一个你本地根本不存在的工具函数时此策略负责优雅降级如反馈报错信息给模型引导其修正避免系统直接 Crash。四、多Agent的上下文传递在单 Agent 架构中上下文工程面对的只是“人与 AI”的单线上下文。但在复杂的Multi-Agent多智能体联合协作场景下核心痛点变成了Agent A 怎么知道 Agent B 刚才干了什么如果让开发者手动去写代码缝合不同 Agent 的输入输出代码很快会沦为灾难。LangChain4j 框架层给出了一套极其优雅的解法——利用AgenticScope作为共享状态总线配合Context.java实现无感的上下文隔空缝合。1. AgenticScope 共享状态空间多 Agent 协同的核心是引入一个独立于大模型之外的共享状态空间。在 LangChain4j 中这个底座被称为AgenticScope// AgenticScope 接口定义 public interface AgenticScope { void writeState(String key, Object value); // Agent A 写入阶段性成果 Object readState(String key); // Agent B 按需读取上下文 String contextAsConversation(String... agentNames); // 提取指定 Agent 集群的对话文本轨道 }设计模式共鸣这本质上是软件工程经典黑板模式的翻版。各个 Agent 之间互不认识解耦它们只跟AgenticScope打交道。Agent A 负责执行并把结构化结果通过outputKey砸进黑板Agent B 启动时直接从黑板上撕下这一页作为自己的输入。2. Context 注入 —隐式 Prompt光有黑板还不够怎么让大模型在感知到黑板内容的同时不污染用户原本的提问LangChain4j 实现了UserMessageTransformer其底层就是我们在上一篇文章中提到的ChatRequestTransformer终极拦截器。它在临发牌前的一瞬间对用户的请求进行了无感整容// Context.java:56-66 核心拦截逻辑 Override public String transformUserMessage(String userMessage, Object memoryId) { if (agenticScope null) { return userMessage; // 降级安全检查 } // 从黑板/状态机中提取当前多 Agent 协作的上下文信息 String agenticScopeContext contextProvider.apply(agenticScope); if (isNullOrBlank(agenticScopeContext)) { return userMessage; } // 关键魔法将跨 Agent 的协作上下文以自然语言前缀的形式悄悄织入 UserMessage return Considering this context \ agenticScopeContext \\n userMessage; }运行期效果透视当用户输入原始指令帮我分析销售数据时拦截器触发发往大模型的实际 Prompt 已经变成了Considering this contextAgentA_数据提取已从数据库成功拉取了2024年Q1-Q4的销售记录并生成了临时报表...帮我分析销售数据通过Considering this context...这句轻量级的 Prompt 强暗示无缝完成了跨 Agent 的上下文接力。3. 智能摘要压缩 —— 跨 Agent 的 Token新的危机如果协同的 Agent 数量多、对话时间长直接把其他 Agent 的全部历史完整塞进来大模型的 Context Window 会瞬间被挤爆。LangChain4j 采用了一套嵌套 Agent 压缩机制——Context.Summarizer// Context.java:70-75 摘要构造器 public Summarizer(AgenticScope agenticScope, ChatModel chatModel, String... agentNames) { super(agenticScope, c - { // 1. 先捞出指定那几个 Agent 的冗长对话历史 String context c.contextAsConversation(agentNames); // 2. 如果历史不为空在线套娃启动一个微型 LLM 专门对其进行高保真压缩 return context.isBlank() ? context : initSummarizer(chatModel).summarize(context).getSummary(); }); }好玩的是负责执行压缩的ContextSummarizer本身竟然也是一个声明式的AiService。它用极度精简的元指令Meta-Prompt完成了 Token 的瘦身// Context.java:15-22 专职压缩的微型 Agent public interface ContextSummarizer { UserMessage( Create a short summary of the following conversation between one or more AI agents and a user. Mention all the agents involved in the conversation. Do not provide any additional information, just the summary. The user conversation is: {{it}}. ) Summary summarize(String conversation); }这种用小模型/小 Prompt 做摘要整理降低后续成本rightarrow大模型做核心复杂推理”的阶梯式上下文配置是极其标准的大厂生产级高阶优化手段。4. AgentBuilder 的双模编排声明式 vs 强控制在最终的客户端调用侧AgentBuilder提供了两种截然不同的策略把上面的上下文机制挂载到 Agent 身上方式 1强控制函数式Imperativepublic B context(FunctionAgenticScope, String contextProvider)给予开发者最高控制权。你可以用 Java 代码自定义怎么去读AgenticScope自由组装成任何你想要的上下文格式。方式 2声明式编排Declarativepublic B summarizedContext(String... contextProvidingAgents)近乎零代码的极简编排。你只需要声明当前 Agent 需要参考 Agent_A 和 Agent_B 的成果。剩下的提取、套娃、调用小模型压缩、前缀织入用户消息全部由框架层自动在底层包办。当我们在最后一步调用.build()时框架会在幕后进行逻辑收拢// AgentBuilder.java:213-222 动态代理组装时 if (contextProvider ! null) { // 挂载函数式动态上下文生成器 aiServices.chatRequestTransformer( new Context.AgenticScopeContextGenerator(agenticScope, contextProvider)); } else { // 挂载智能摘要 Transformer aiServices.chatRequestTransformer( new Context.Summarizer(agenticScope, model, contextProvidingAgents)); }总结 上下文工程写到这里我们已经完整走过了 LangChain4j 上下文工程的全部生态位静态人设注入在DefaultAiServices中利用动态代理和反射在编译期将SystemMessage和运行时入参变量完美咬合。动态滑动窗口通过MessageWindow和TokenWindow建立数学防御防线在运行时利用 Token 计数器精准裁剪历史并连带清理“孤儿工具消息”对齐大模型厂商的底层协议。ReAct 推理引擎在ToolService的while(true)状态机中让上下文随着工具的“思考-行动-反馈”滚雪球式增长并利用熔断和动态 Tool 搜索控制 Token 灾难。多 Agent 跨拓扑共享利用AgenticScope黑板模式打破 Agent 之间的隔离利用隐式消息重构与套娃摘要技术实现了跨 Agent 的脑电波同步。可以说控制了上下文就控制了 Agent 的智商与账单。