[BUG] chatbot里面无法动态管理prompt

[zhuxingsheng]

Is there an existing issue for this?

• I have searched the existing issues

Current Behavior

版本：1.1.0.0-RC2

项目使用实现chatbot，结合spring-ai-alibaba-admin动态管理prompt

依赖项：
spring-ai-alibaba-studio
spring-ai-alibaba-starter-config-nacos

`protected void registryPrompt(NacosOptions nacosOptions, ReactAgent reactAgent, ObservationMetadataAwareOptions observationMetadataAwareOptions, String promptKey) {

	Listener listener = new AbstractListener() {
		@Override
		public void receiveConfigInfo(String configInfo) {
			PromptVO promptVO = JSON.parseObject(configInfo, PromptVO.class);
			try {
				Map<String, String> metadata = getMetadata(promptVO);
				observationMetadataAwareOptions.getObservationMetadata().putAll(metadata);
				reactAgent.setInstruction(promptVO.getTemplate());
			}
			catch (Exception e) {
				throw new RuntimeException(e);
			}
		}
	};`

动态更新的instruction属性，但在ExecutionController.executeAgent 方法中，调用的是agent.stream方法，并没有使用到instruction属性

经 @Aias00 提醒，其实在AgentToSubCompiledGraphNodeAdapter中是有完整的instruction属性的使用的。但agent.stream中缺失了这段逻辑

Expected Behavior

No response

Steps To Reproduce

No response

Environment

Spring AI Alibaba version(s):

Debug logs

No response

Anything else?

No response

[Aias00]

ReactAgent 中 instruction 在 stream 调用时的生效分析

问题

创建一个 ReactAgent，调用 agent.stream() 的时候，instruction 会生效吗？如果会生效，指出什么时候生效的。

答案：会生效

instruction 在调用 agent.stream() 时会生效，并且在每次 LLM 节点执行时都会被添加到消息列表中。

生效时机和流程

1. stream 方法调用链

当你调用 agent.stream() 时，执行流程如下：

ReactAgent.stream()
  ↓
CompiledGraph.stream(inputs, config)  // 在 ReactAgent 中通过 compiledGraph.stream() 调用
  ↓
CompiledGraph.streamFromInitialNode(overAllState, config)
  ↓
GraphRunner.run(overAllState)  // 创建 GraphRunner 并执行
  ↓
执行各个节点，包括 AgentLlmNode

2. instruction 的生效位置

instruction 在 AgentLlmNode.apply() 方法中生效，具体代码位置：

文件: AgentLlmNode.java
行号: 181-186

if (StringUtils.hasLength(this.instruction)) {
    List<Message> messagesWithInstruction = new ArrayList<>();
    messagesWithInstruction.add(new UserMessage(this.instruction));
    messagesWithInstruction.addAll(messages);
    requestBuilder.messages(messagesWithInstruction);
}

3. 详细执行流程

步骤 1: 创建 ReactAgent 时设置 instruction

ReactAgent agent = ReactAgent.builder()
    .name("demoAgent")
    .model(chatModel)
    .instruction("地点为: {target_topic}")  // 设置 instruction
    .build();

在构建时，instruction 被传递给 AgentLlmNode：

• ReactAgent 构造函数中（第 118 行）：this.instruction = builder.instruction;
• 在 initGraph() 方法中创建 AgentLlmNode 时传入 instruction

步骤 2: 调用 stream 方法

Flux<NodeOutput> flux = agent.stream("上海,北京");

这会触发：

1. CompiledGraph.stream() 被调用
2. 创建初始状态 OverAllState
3. 启动 GraphRunner 执行图的各个节点

步骤 3: AgentLlmNode 执行时应用 instruction

每次 AgentLlmNode.apply(OverAllState state, RunnableConfig config) 被调用时：

1. 获取当前消息列表（第 140-150 行）

   List<Message> messages = new ArrayList<>();
   if (state.value("messages").isEmpty()) {
       // 处理初始输入
   } else {
       messages = (List<Message>) state.value("messages").get();
   }

2. 创建 ModelRequest（第 156-159 行）

   ModelRequest.Builder requestBuilder = ModelRequest.builder()
       .messages(messages)
       .options(chatOptions.copy())
       .context(config.metadata().orElse(new HashMap<>()));

3. 添加 instruction（第 181-186 行）

   if (StringUtils.hasLength(this.instruction)) {
       List<Message> messagesWithInstruction = new ArrayList<>();
       messagesWithInstruction.add(new UserMessage(this.instruction));  // instruction 作为 UserMessage 添加到最前面
       messagesWithInstruction.addAll(messages);
       requestBuilder.messages(messagesWithInstruction);
   }

4. 执行模型调用（第 191-224 行）

   • 如果是 stream 模式（_stream_ 元数据为 true，默认为 true）
   • 调用 chatClient.stream().chatResponse() 进行流式调用
   • instruction 已经包含在发送给 LLM 的消息列表中

4. instruction 的模板渲染

如果 instruction 包含模板变量（如 {target_topic}），它会在 AgentLlmNode 中被渲染：

文件: AgentLlmNode.java
方法: renderTemplatedUserMessage()（第 389-425 行）

public void renderTemplatedUserMessage(List<Message> messages, Map<String, Object> params) {
    // 处理参数
    Map<String, Object> processedParams = new HashMap<>();
    // ... 参数处理逻辑
    
    // 渲染模板
    for (int i = messages.size() - 1; i >= 0; i--) {
        Message message = messages.get(i);
        if (message instanceof AgentInstructionMessage instructionMessage && !instructionMessage.isRendered()) {
            AgentInstructionMessage newMessage = instructionMessage.mutate()
                .text(renderPromptTemplate(instructionMessage.getText(), processedParams))
                .rendered(true)
                .build();
            messages.set(i, newMessage);
            break;
        }
    }
}

注意: 从代码来看，instruction 被添加为普通的 UserMessage，而不是 AgentInstructionMessage，因此模板渲染可能不会自动应用。如果需要模板渲染，可能需要使用其他方式传递参数。

关键代码位置总结

文件	方法/位置	作用
ReactAgent.java	构造函数（第 118 行）	保存 instruction
ReactAgent.java	initGraph()	将 instruction 传递给 AgentLlmNode
CompiledGraph.java	stream(Map<String, Object> inputs, RunnableConfig config) (第 493 行)	启动流式执行
AgentLlmNode.java	apply(OverAllState state, RunnableConfig config) (第 123 行)	节点执行入口
AgentLlmNode.java	第 181-186 行	instruction 生效的关键位置
AgentLlmNode.java	第 191-224 行	流式模型调用

测试验证

从测试代码 ReactAgentTest.java 可以看到多个使用 instruction 的例子：

@Test
public void testReactAgentWithTools() {
    var react = ReactAgent.builder()
        .name("demoReactAgent")
        .model(chatModel)
        .instruction("地点为: {target_topic}")  // 设置 instruction
        .tools(ToolCallbacks.from(new TestTools()))
        .systemPrompt("你是一个天气预报助手，帮我查看指定地点的天气预报")
        .build();

    String output = react.call("上海,北京").getText();
    // instruction 会在调用时生效
}

@Test
public void testReactAgentStreamingWithTools() {
    var react = ReactAgent.builder()
        .name("demoReactAgent")
        .model(chatModel)
        .instruction("地点为: {target_topic}")  // 设置 instruction
        .tools(ToolCallbacks.from(new TestTools()))
        .systemPrompt("你是一个天气预报助手")
        .build();

    Flux<NodeOutput> flux = react.stream("上海,北京");
    // instruction 在 stream 调用时同样会生效
}

结论

1. instruction 会在 agent.stream() 调用时生效
2. 生效时机: 在每次 AgentLlmNode.apply() 方法执行时，instruction 会被添加到发送给 LLM 的消息列表的最前面
3. 生效位置: AgentLlmNode.java 第 181-186 行
4. 作用方式: instruction 被转换为 UserMessage 并添加到消息列表的开头，然后一起发送给 LLM
5. 适用场景: 无论是 call() 还是 stream() 方法，instruction 都会以相同的方式生效

注意事项

• instruction 在每次 LLM 节点执行时都会被添加，包括多轮对话的每一轮
• instruction 会被添加到消息列表的最前面，优先级高于用户消息
• 如果需要使用模板变量（如 {target_topic}），需要确保在 state 中有对应的参数

[zhuxingsheng]

谢谢 @Aias00 ，之前一直没有看最新代码，发现在上周已经有最新的fix

#3974