Skip to content

Commit b06a420

Browse files
authored
Merge pull request #73 from ikaitist/fix/35-skills-hitl-tool-callback
fix(agent): resolve dynamically disclosed skill tools after HITL resumption (#35)
2 parents 45e5332 + 9f30753 commit b06a420

4 files changed

Lines changed: 195 additions & 1 deletion

File tree

‎agentic-spring-ai-agent-framework/src/main/java/io/github/agentic/spring/ai/graph/agent/DefaultBuilder.java‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,8 @@
4545
import java.util.ArrayList;
4646
import java.util.Collections;
4747
import java.util.List;
48+
import java.util.Map;
49+
import java.util.concurrent.ConcurrentHashMap;
4850

4951
public class DefaultBuilder extends Builder {
5052

@@ -138,6 +140,12 @@ public ReactAgent build() {
138140
llmNodeBuilder.enableReasoningLog(true);
139141
}
140142

143+
// Shared in-memory registry for tool callbacks disclosed dynamically at model-call
144+
// time. AgentLlmNode fills it; AgentToolNode falls back to it when the config context
145+
// no longer carries the callbacks (e.g. after a Human-in-the-Loop resumption).
146+
Map<String, ToolCallback> dynamicToolCallbacksRegistry = new ConcurrentHashMap<>();
147+
llmNodeBuilder.dynamicToolCallbacksRegistry(dynamicToolCallbacksRegistry);
148+
141149
AgentLlmNode llmNode = llmNodeBuilder.build();
142150

143151
// Setup tool node with all available tools
@@ -147,7 +155,8 @@ public ReactAgent build() {
147155
.parallelToolExecution(this.parallelToolExecution)
148156
.maxParallelTools(this.maxParallelTools)
149157
.toolExecutionTimeout(this.toolExecutionTimeout)
150-
.wrapSyncToolsAsAsync(this.wrapSyncToolsAsAsync);
158+
.wrapSyncToolsAsAsync(this.wrapSyncToolsAsAsync)
159+
.dynamicToolCallbacksRegistry(dynamicToolCallbacksRegistry);
151160

152161
if (resolver != null) {
153162
toolBuilder.toolCallbackResolver(resolver);

‎agentic-spring-ai-agent-framework/src/main/java/io/github/agentic/spring/ai/graph/agent/node/AgentLlmNode.java‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -74,6 +74,13 @@ public class AgentLlmNode implements NodeActionWithConfig {
7474
// FIXME: toolCallbacks should be managed in chatOptions only. Currently it's guaranteed immutable with unmodifiableList.
7575
private List<ToolCallback> toolCallbacks = new ArrayList<>();
7676

77+
/**
78+
* Shared in-memory registry (with {@link AgentToolNode}) of tool callbacks disclosed
79+
* dynamically at model-call time. It keeps the callbacks resolvable after a
80+
* Human-in-the-Loop resumption, where the config context is cleared.
81+
*/
82+
private Map<String, ToolCallback> dynamicToolCallbacksRegistry;
83+
7784
private List<ModelInterceptor> modelInterceptors = new ArrayList<>();
7885

7986
private List<StreamingModelInterceptor> streamingInterceptors = new ArrayList<>();
@@ -107,6 +114,7 @@ public AgentLlmNode(Builder builder) {
107114
if (builder.toolCallbacks != null) {
108115
this.toolCallbacks = builder.toolCallbacks;
109116
}
117+
this.dynamicToolCallbacksRegistry = builder.dynamicToolCallbacksRegistry;
110118
if (builder.modelInterceptors != null) {
111119
this.modelInterceptors = builder.modelInterceptors;
112120
}
@@ -492,6 +500,7 @@ private ChatClient.ChatClientRequestSpec buildChatClientRequestSpec(ModelRequest
492500
filteredToolCallbacks = ToolCallbackUtils.deduplicateByName(filteredToolCallbacks, dynamicToolCallbacks);
493501
// FIXME, use RunnableConfig to pass dynamic tool callbacks to tool node via config context (internal use)
494502
config.context().put(RunnableConfig.DYNAMIC_TOOL_CALLBACKS_METADATA_KEY, dynamicToolCallbacks);
503+
registerDynamicToolCallbacks(dynamicToolCallbacks);
495504
}
496505
else {
497506
config.context().remove(RunnableConfig.DYNAMIC_TOOL_CALLBACKS_METADATA_KEY);
@@ -514,6 +523,16 @@ private ChatClient.ChatClientRequestSpec buildChatClientRequestSpec(ModelRequest
514523
return promptSpec;
515524
}
516525

526+
private void registerDynamicToolCallbacks(List<ToolCallback> dynamicToolCallbacks) {
527+
if (dynamicToolCallbacksRegistry == null) {
528+
return;
529+
}
530+
dynamicToolCallbacksRegistry.clear();
531+
for (ToolCallback callback : dynamicToolCallbacks) {
532+
dynamicToolCallbacksRegistry.put(callback.getToolDefinition().name(), callback);
533+
}
534+
}
535+
517536
public String getName() {
518537
return AGENT_MODEL_NAME;
519538
}
@@ -535,6 +554,8 @@ public static class Builder {
535554

536555
private List<ToolCallback> toolCallbacks;
537556

557+
private Map<String, ToolCallback> dynamicToolCallbacksRegistry;
558+
538559
private List<ModelInterceptor> modelInterceptors;
539560

540561
private List<StreamingModelInterceptor> streamingInterceptors;
@@ -580,6 +601,11 @@ public Builder toolCallbacks(List<ToolCallback> toolCallbacks) {
580601
return this;
581602
}
582603

604+
public Builder dynamicToolCallbacksRegistry(Map<String, ToolCallback> dynamicToolCallbacksRegistry) {
605+
this.dynamicToolCallbacksRegistry = dynamicToolCallbacksRegistry;
606+
return this;
607+
}
608+
583609
public Builder modelInterceptors(List<ModelInterceptor> modelInterceptors) {
584610
this.modelInterceptors = modelInterceptors;
585611
return this;

‎agentic-spring-ai-agent-framework/src/main/java/io/github/agentic/spring/ai/graph/agent/node/AgentToolNode.java‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -121,13 +121,24 @@ public class AgentToolNode implements NodeActionWithConfig {
121121

122122
private ToolExecutionExceptionProcessor toolExecutionExceptionProcessor;
123123

124+
/**
125+
* In-memory registry of tool callbacks disclosed dynamically at model-call time
126+
* (e.g. skill tools injected by a progressive-disclosure model interceptor). The same
127+
* compiled graph instance is reused when a run resumes after a Human-in-the-Loop
128+
* interruption, so this registry survives resumption even though
129+
* {@code config.context()} is cleared.
130+
*/
131+
private final Map<String, ToolCallback> dynamicToolCallbacks;
132+
124133
public AgentToolNode(Builder builder) {
125134
this.agentName = builder.agentName;
126135
this.enableActingLog = builder.enableActingLog;
127136
this.toolCallbackResolver = builder.toolCallbackResolver;
128137
this.toolCallbacks = builder.toolCallbacks;
129138
this.toolContext = builder.toolContext;
130139
this.toolExecutionExceptionProcessor = builder.toolExecutionExceptionProcessor;
140+
this.dynamicToolCallbacks = builder.dynamicToolCallbacksRegistry != null ? builder.dynamicToolCallbacksRegistry
141+
: new ConcurrentHashMap<>();
131142
this.parallelToolExecution = builder.parallelToolExecution;
132143
this.maxParallelTools = builder.maxParallelTools;
133144
this.toolExecutionTimeout = builder.toolExecutionTimeout;
@@ -146,6 +157,24 @@ void setToolCallbackResolver(ToolCallbackResolver toolCallbackResolver) {
146157
this.toolCallbackResolver = toolCallbackResolver;
147158
}
148159

160+
/**
161+
* Registers tool callbacks disclosed dynamically (for example by a progressive-disclosure
162+
* model interceptor) so they stay resolvable when a run resumes after an interruption and
163+
* {@code config.context()} no longer carries them. Called by {@link AgentLlmNode} whenever
164+
* it computes the dynamic tool callbacks for a model call.
165+
*/
166+
void registerDynamicToolCallbacks(List<ToolCallback> callbacks) {
167+
dynamicToolCallbacks.clear();
168+
if (callbacks == null) {
169+
return;
170+
}
171+
for (ToolCallback callback : callbacks) {
172+
if (callback != null) {
173+
dynamicToolCallbacks.put(callback.getToolDefinition().name(), callback);
174+
}
175+
}
176+
}
177+
149178
public List<ToolCallback> getToolCallbacks() {
150179
return toolCallbacks;
151180
}
@@ -852,6 +881,13 @@ private ToolCallback resolve(String toolName, RunnableConfig config) {
852881
if (fromDynamic != null) {
853882
return fromDynamic;
854883
}
884+
// Fall back to the in-memory registry populated by AgentLlmNode: the config context is
885+
// cleared when a subgraph resumes after a Human-in-the-Loop interruption, while the
886+
// registry lives on the reused compiled graph instance.
887+
ToolCallback fromRegistry = dynamicToolCallbacks.get(toolName);
888+
if (fromRegistry != null) {
889+
return fromRegistry;
890+
}
855891
return toolCallbackResolver == null ? null : toolCallbackResolver.resolve(toolName);
856892
}
857893

@@ -892,6 +928,8 @@ public static class Builder {
892928

893929
private Map<String, Object> toolContext = new HashMap<>();
894930

931+
private Map<String, ToolCallback> dynamicToolCallbacksRegistry;
932+
895933
private ToolCallbackResolver toolCallbackResolver;
896934

897935
private ToolExecutionExceptionProcessor toolExecutionExceptionProcessor;
@@ -979,6 +1017,11 @@ public Builder toolCallbackResolver(ToolCallbackResolver toolCallbackResolver) {
9791017
return this;
9801018
}
9811019

1020+
public Builder dynamicToolCallbacksRegistry(Map<String, ToolCallback> dynamicToolCallbacksRegistry) {
1021+
this.dynamicToolCallbacksRegistry = dynamicToolCallbacksRegistry;
1022+
return this;
1023+
}
1024+
9821025
public Builder toolContext(Map<String, Object> toolContext) {
9831026
this.toolContext = new HashMap<>(toolContext);
9841027
return this;
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
/*
2+
* Copyright 2024-2026 the original author or authors.
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* https://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
package io.github.agentic.spring.ai.graph.agent.node;
17+
18+
import io.github.agentic.spring.ai.graph.OverAllState;
19+
import io.github.agentic.spring.ai.graph.RunnableConfig;
20+
21+
import org.junit.jupiter.api.DisplayName;
22+
import org.junit.jupiter.api.Test;
23+
24+
import org.springframework.ai.chat.messages.AssistantMessage;
25+
import org.springframework.ai.chat.messages.ToolResponseMessage;
26+
import org.springframework.ai.tool.ToolCallback;
27+
import org.springframework.ai.tool.execution.ToolExecutionExceptionProcessor;
28+
import org.springframework.ai.tool.function.FunctionToolCallback;
29+
30+
import java.time.Duration;
31+
import java.util.ArrayList;
32+
import java.util.HashMap;
33+
import java.util.List;
34+
import java.util.Map;
35+
36+
import static org.assertj.core.api.Assertions.assertThat;
37+
38+
/**
39+
* Tests for the in-memory dynamic tool callback registry on {@link AgentToolNode}.
40+
*
41+
* <p>
42+
* Covers the Human-in-the-Loop resumption scenario reported in issue #35: skill tools are
43+
* disclosed dynamically at model-call time and passed to the tool node through
44+
* {@code config.context()}, which is cleared when a subgraph resumes after an interruption.
45+
* The registry (shared with {@link AgentLlmNode} via the agent builder) keeps the disclosed
46+
* callbacks resolvable across resumption.
47+
* </p>
48+
*
49+
* @author Kal'tsit
50+
* @since 1.0.0
51+
*/
52+
@DisplayName("AgentToolNode Dynamic Tool Callback Registry Tests")
53+
class AgentToolNodeDynamicToolCallbackRegistryTest {
54+
55+
private static final ToolExecutionExceptionProcessor DEFAULT_PROCESSOR = e -> "Error: " + e.getMessage();
56+
57+
private ToolCallback queryTool() {
58+
return FunctionToolCallback.builder("queryTool", (QueryInput input) -> "result:" + input.q())
59+
.description("Query tool")
60+
.inputType(QueryInput.class)
61+
.build();
62+
}
63+
64+
record QueryInput(String q) {
65+
}
66+
67+
private AgentToolNode buildNode() {
68+
return AgentToolNode.builder()
69+
.agentName("test-agent")
70+
.toolExecutionTimeout(Duration.ofMinutes(5))
71+
.toolExecutionExceptionProcessor(DEFAULT_PROCESSOR)
72+
.build();
73+
}
74+
75+
private OverAllState stateWithToolCall(String toolName, String arguments) {
76+
AssistantMessage assistantMessage = AssistantMessage.builder()
77+
.content("")
78+
.toolCalls(List.of(new AssistantMessage.ToolCall("call_1", "function", toolName, arguments)))
79+
.build();
80+
Map<String, Object> stateData = new HashMap<>();
81+
stateData.put("messages", new ArrayList<>(List.of(assistantMessage)));
82+
return new OverAllState(stateData);
83+
}
84+
85+
@Test
86+
@DisplayName("Dynamic registry resolves a tool when the config context is empty (HITL resume scenario)")
87+
void dynamicRegistryResolvesToolWhenConfigContextIsEmpty() throws Exception {
88+
AgentToolNode node = buildNode();
89+
node.registerDynamicToolCallbacks(List.of(queryTool()));
90+
91+
// Simulate a resumed run: a fresh config whose context no longer carries the
92+
// dynamically disclosed tool callbacks.
93+
RunnableConfig config = RunnableConfig.builder().threadId("test-thread").build();
94+
95+
Map<String, Object> result = node.apply(stateWithToolCall("queryTool", "{\"q\":\"hello\"}"), config);
96+
97+
ToolResponseMessage responseMessage = (ToolResponseMessage) result.get("messages");
98+
assertThat(responseMessage.getResponses()).hasSize(1);
99+
assertThat(responseMessage.getResponses().get(0).responseData()).contains("result:hello");
100+
}
101+
102+
@Test
103+
@DisplayName("A tool absent from the registry is reported as unavailable")
104+
void toolAbsentFromRegistryIsReportedUnavailable() throws Exception {
105+
AgentToolNode node = buildNode();
106+
107+
RunnableConfig config = RunnableConfig.builder().threadId("test-thread").build();
108+
109+
Map<String, Object> result = node.apply(stateWithToolCall("unknownTool", "{}"), config);
110+
111+
ToolResponseMessage responseMessage = (ToolResponseMessage) result.get("messages");
112+
assertThat(responseMessage.getResponses()).hasSize(1);
113+
assertThat(responseMessage.getResponses().get(0).responseData()).contains("Tool not available: unknownTool");
114+
}
115+
116+
}

0 commit comments

Comments
 (0)