Spring AI Alibaba 1.x 系列【76】上下文工程（Context Engineering）

1. 概述

1.1 为什么 Agent 会失败

构建Agent的难点在于使其足够可靠。虽然写一个Demo很容易，但要在生产环境中稳定运行并不简单。

Agent失败通常有两个原因：

大多数情况下是第二个原因——上下文工程不是附加功能，而是AI工程师的首要工作。Spring AI Alibaba的Hook和Interceptor抽象专门为此设计。

1.2 什么是上下文工程

上下文工程是以正确的格式提供正确的信息和工具，使LLM能够完成任务。

┌─────────────────────────────────────────────────────┐ │ 上下文工程 │ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌────────────┐ │ │ │ 模型上下文 │ │ 工具上下文 │ │ 生命周期 │ │ │ │ (瞬态) │ │ (持久) │ │ 上下文 │ │ │ │ │ │ │ │ (持久) │ │ │ │ · SystemPrompt│ │ · 读 State │ │ · 摘要 │ │ │ │ · Messages │ │ · 写 State │ │ · 护栏 │ │ │ │ · Tools │ │ · 读 Store │ │ · 日志 │ │ │ │ · Model │ │ · 写 Store │ │ │ │ │ │ · Response │ │ │ │ │ │ │ └──────────────┘ └──────────────┘ └────────────┘ │ └─────────────────────────────────────────────────────┘

2. Agent 循环与上下文类型

2.1 Agent 循环

┌──────────────────────────────────┐ │ Agent 循环 │ │ │ │ ┌─────────┐ ┌─────────┐ │ │ │ 模型调用 │ ──→ │ 工具执行 │ │ │ │ (Think) │ ←── │ (Act) │ │ │ └─────────┘ └─────────┘ │ │ │ │ │ │ └── 任务完成 → 退出 ─┘ │ └──────────────────────────────────┘

2.2 三种上下文类型

2.3 三种数据源

┌──────────────────────────────────────────────────┐ │ 数据源 │ │ │ │ 运行时上下文 State Store │ │ (静态配置) (短期记忆) (长期记忆) │ │ 会话范围 会话范围 跨会话 │ │ │ │ · 用户 ID · 当前消息 · 用户偏好 │ │ · API Key · 上传文件 · 历史数据 │ │ · 权限设置 · 认证状态 · 提取的 │ │ · 环境变量 · 工具结果 见解 │ │ · 数据库连接 │ └──────────────────────────────────────────────────┘

3. 模型上下文

控制每次模型调用中包含的内容——指令、可用工具、使用哪个模型以及输出格式。

3.1 系统提示（System Prompt）

3.1.1 基于状态的动态提示

根据对话长度自动调整指令风格：

classStateAwarePromptInterceptorextendsModelInterceptor{@OverridepublicModelResponseinterceptModel(ModelRequestrequest,ModelCallHandlerhandler){List<Message>messages=request.getMessages();StringbasePrompt="你是一个有用的助手。";if(messages.size()>10){basePrompt+="\n这是一个长对话 - 请尽量保持精准简捷。";}SystemMessageenhancedMessage=request.getSystemMessage()==null?newSystemMessage(basePrompt):newSystemMessage(request.getSystemMessage().getText()+"\n\n"+basePrompt);ModelRequestenhancedRequest=ModelRequest.builder(request).systemMessage(enhancedMessage).build();returnhandler.call(enhancedRequest);}}

3.1.2 基于存储的个性化提示

从长期记忆加载用户偏好，构建个性化System Prompt：

classPersonalizedPromptInterceptorextendsModelInterceptor{privatefinalUserPreferenceStorestore;@OverridepublicModelResponseinterceptModel(ModelRequestrequest,ModelCallHandlerhandler){StringuserId=request.getContext().get("user-id");// 从运行时上下文获取UserPreferencesprefs=store.getPreferences(userId);// 从 Store 加载偏好StringBuilderprompt=newStringBuilder("你是一个有用的助手。");if(prefs.getCommunicationStyle()!=null){prompt.append("\n沟通风格：").append(prefs.getCommunicationStyle());}if(prefs.getLanguage()!=null){prompt.append("\n使用语言：").append(prefs.getLanguage());}SystemMessageenhancedMessage=buildEnhancedMessage(request,prompt.toString());returnhandler.call(ModelRequest.builder(request).systemMessage(enhancedMessage).build());}}

调用时通过RunnableConfig传递用户 ID：

RunnableConfig.builder().metadata("user-id","user123").build()

3.2 消息历史（Messages）

3.2.1 消息过滤 —— 限制上下文长度

classMessageFilterInterceptorextendsModelInterceptor{privatefinalintmaxMessages;@OverridepublicModelResponseinterceptModel(ModelRequestrequest,ModelCallHandlerhandler){List<Message>messages=request.getMessages();if(messages.size()>maxMessages){// 保留 SystemMessage + 最近的消息List<Message>filtered=newArrayList<>();messages.stream().filter(m->minstanceofSystemMessage).findFirst().ifPresent(filtered::add);intstart=Math.max(0,messages.size()-maxMessages+1);filtered.addAll(messages.subList(start,messages.size()));messages=filtered;}returnhandler.call(ModelRequest.builder(request).messages(messages).build());}}

3.2.2 瞬态更新 VS 持久更新

3.3 工具选择（Tools）

按用户角色动态分配工具集：

classContextualToolInterceptorextendsModelInterceptor{privatefinalMap<String,List<ToolCallback>>roleBasedTools;@OverridepublicModelResponseinterceptModel(ModelRequestrequest,ModelCallHandlerhandler){StringuserRole=request.getContext().getOrDefault("user-role","user");List<ToolCallback>allowedTools=roleBasedTools.getOrDefault(userRole,List.of());returnhandler.call(ModelRequest.builder(request).dynamicToolCallbacks(allowedTools).build());}}// 配置Map<String,List<ToolCallback>>roleTools=Map.of("admin",List.of(readTool,writeTool,deleteTool),"user",List.of(readTool),"guest",List.of());ReactAgentagent=ReactAgent.builder().interceptors(newContextualToolInterceptor(roleTools)).build();

3.4 模型选择（Model）

根据任务复杂度动态切换模型——简单任务用小模型降成本，复杂任务用大模型保质量：

classDynamicModelInterceptorextendsModelInterceptor{privatefinalChatModelsimpleModel;privatefinalChatModelcomplexModel;@OverridepublicModelResponseinterceptModel(ModelRequestrequest,ModelCallHandlerhandler){booleanisComplex=analyzeComplexity(request.getMessages());ChatModelselectedModel=isComplex?complexModel:simpleModel;returnhandler.call(ModelRequest.builder(request).model(selectedModel).build());}privatebooleananalyzeComplexity(List<Message>messages){returnmessages.size()>5;// 长对话视为复杂任务}}

3.5 响应格式（Response Format）

在Agent创建时指定结构化输出：

ReactAgentagent=ReactAgent.builder().name("structured_agent").model(chatModel).outputType(MyResponseClass.class)// 或 .outputSchema(jsonSchema).build();

4. 工具上下文

控制工具对State（短期记忆）和Store（长期记忆）的读写权限。

4.1 工具中读取状态

classStatefulToolimplementsFunction<StatefulTool.Request,StatefulTool.Response>{publicrecordRequest(Stringquery){}publicrecordResponse(Stringresult){}@OverridepublicResponseapply(Requestrequest,ToolContexttoolContext){// 读取当前 Agent StateOverAllStatestate=(OverAllState)toolContext.getContext().get("state");Optional<Object>messages=state.value("messages");// 读取运行时配置RunnableConfigconfig=(RunnableConfig)toolContext.getContext().get("config");Optional<Object>userCtx=config.metadata("user_context_key");returnnewResponse(processWithContext(request.query(),messages,userCtx));}}

4.2 工具中修改状态

classStateModifyingToolimplementsFunction<StateModifyingTool.Request,StateModifyingTool.Response>{publicrecordRequest(Stringdata){}publicrecordResponse(Stringstatus){}@OverridepublicResponseapply(Requestrequest,ToolContexttoolContext){// extraState 中的值会被持久化到 State，后续 Loop 可见Map<String,Object>extraState=(Map<String,Object>)toolContext.getContext().get("extraState");Stringprocessed=process(request.data());extraState.put("processed_data",processed);// 持久化到 StatereturnnewResponse("数据已处理并保存到状态");}}

5. 生命周期上下文

使用Hook在Agent生命周期的关键节点执行操作。

5.1 Hook 位置

Spring AI Alibaba支持四个Hook位置：

BEFORE_AGENT AFTER_AGENT │ ▲ ▼ │ ┌──────────────────────────────────────────┴──┐ │ Agent 执行过程 │ │ │ │ ┌──────────┐ ┌──────────┐ │ │ │ 模型调用 │───→│ 工具执行 │───→ ... │ │ └──────────┘ └──────────┘ │ │ ▲ │ │ │ │ │ BEFORE_MODEL AFTER_MODEL │ └──────────────────────────────────────────────┘

5.2 日志 Hook

classLoggingHookextendsModelHook{@OverridepublicHookPosition[]getHookPositions(){returnnewHookPosition[]{HookPosition.BEFORE_MODEL,HookPosition.AFTER_MODEL};}@OverridepublicCompletableFuture<Map<String,Object>>beforeModel(OverAllStatestate,RunnableConfigconfig){List<?>messages=(List<?>)state.value("messages").orElse(List.of());System.out.println("[BEFORE_MODEL] 消息数: "+messages.size());returnCompletableFuture.completedFuture(Map.of());}@OverridepublicCompletableFuture<Map<String,Object>>afterModel(OverAllStatestate,RunnableConfigconfig){System.out.println("[AFTER_MODEL] 响应已生成");returnCompletableFuture.completedFuture(Map.of());}}

5.3 消息摘要 Hook

当对话过长时自动生成摘要，压缩上下文：

@HookPositions({HookPosition.BEFORE_MODEL})classSummarizationHookextendsMessagesModelHook{privatefinalChatModelsummarizationModel;privatefinalinttriggerLength;@OverridepublicAgentCommandbeforeModel(List<Message>previousMessages,RunnableConfigconfig){if(previousMessages.size()<=triggerLength){returnnewAgentCommand(previousMessages);// 未超阈值，不处理}// 1. 生成摘要Stringsummary=generateSummary(previousMessages);// 2. 保留 SystemMessage + 摘要 + 最近消息List<Message>newMessages=newArrayList<>();previousMessages.stream().filter(m->minstanceofSystemMessage).forEach(newMessages::add);newMessages.add(newUserMessage("【上下文摘要】之前的对话摘要："+summary));intrecentCount=Math.min(5,previousMessages.size());newMessages.addAll(previousMessages.subList(previousMessages.size()-recentCount,previousMessages.size()));returnnewAgentCommand(newMessages,UpdatePolicy.REPLACE);}}

6. 完整示例：综合上下文工程

将多种上下文工程手段组合到一个Agent中：

@ConfigurationpublicclassContextEngineeringConfig{@BeanpublicReactAgentcontextEngineeredAgent(ChatModelchatModel,ChatModelsummaryModel,UserPreferenceStorestore){returnReactAgent.builder().name("context_engineered_agent").model(chatModel).description("综合上下文工程示例").instruction("你是一个智能助手，会根据用户偏好调整回复风格。")// 个性化 System Prompt.interceptors(newPersonalizedPromptInterceptor(store),// 从 Store 加载偏好newMessageFilterInterceptor(20),// 限制消息数量newContextualToolInterceptor(getRoleTools()),// 按角色分配工具newAnswerValidationInterceptor()// 答案验证)// 生命周期 Hook.hooks(newSummarizationHook(summaryModel,15),// 长对话摘要newLoggingHook()// 日志).saver(newMemorySaver()).enableLogging(true).build();}}

7. Hook 与 Interceptor 选择指南

8. 瞬态 vs 持久 决策树

要修改的内容需要在后续的 Agent 推理轮次中可见吗？ │ ├── 否（只影响本次 LLM 调用）→ 使用 ModelInterceptor │ 示例：消息过滤、动态工具选择、动态 Prompt │ └── 是（需要持久保存）→ 使用 Hook + REPLACE 或 ToolContext 示例：对话摘要、工具写入状态