Skip to content

Commit 619f11d

Browse files
feat(agent): wire strict tool-state mode into ReAct agent (T37)
Opt-in strictToolState on the independent ReAct path: tools receive a read-only view of the invocation state (writes escape only through the patch channel) and the shared StrictPatchAdmission enforces the hard failure-discard rule plus policy validation. Sequential merging stays last-write-wins by design - documented in the builder javadoc - since the ReAct state is invocation-local and execution is sequential. Refs #140
1 parent 3eb05ba commit 619f11d

2 files changed

Lines changed: 350 additions & 1 deletion

File tree

‎argi-agent/argi-agent-core/src/main/java/io/github/agentic/ai/agent/react/ReActAgent.java‎

Lines changed: 39 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,9 @@
4141
import io.github.agentic.ai.agent.interceptor.authorization.ToolAuthorizationPolicy;
4242
import io.github.agentic.ai.agent.result.StructuredOutputFinalizer;
4343
import io.github.agentic.ai.agent.tool.patch.ToolContextPatchPolicy;
44+
import io.github.agentic.ai.agent.tool.patch.strict.StateIsolation;
45+
import io.github.agentic.ai.agent.tool.patch.strict.StrictPatchAdmission;
46+
import io.github.agentic.ai.agent.tool.patch.strict.ToolUpdateUnit;
4447
import io.github.agentic.ai.agent.tool.patch.ToolContextPatchValidator;
4548
import io.github.agentic.ai.agent.tool.patch.ToolContextPatchViolationException;
4649
import io.github.agentic.ai.agent.validation.ToolArgumentValidator;
@@ -79,6 +82,8 @@ public final class ReActAgent implements Agent {
7982

8083
private final ToolContextPatchPolicy patchPolicy;
8184

85+
private final boolean strictToolState;
86+
8287
private final BusinessOutcomeMapperRegistry outcomeMappers;
8388

8489
private final HumanInTheLoop humanInTheLoop;
@@ -101,6 +106,7 @@ private ReActAgent(Builder builder) {
101106
"authorizationPolicy must not be null");
102107
this.validateToolArguments = builder.validateToolArguments;
103108
this.patchPolicy = builder.patchPolicy;
109+
this.strictToolState = builder.strictToolState;
104110
this.outcomeMappers = Objects.requireNonNull(builder.outcomeMappers, "outcomeMappers must not be null");
105111
this.humanInTheLoop = builder.humanInTheLoop;
106112
this.outputFinalizer = builder.outputFinalizer;
@@ -135,6 +141,8 @@ public static final class Builder {
135141

136142
private ToolContextPatchPolicy patchPolicy;
137143

144+
private boolean strictToolState;
145+
138146
private BusinessOutcomeMapperRegistry outcomeMappers = BusinessOutcomeMapperRegistry.empty();
139147

140148
private HumanInTheLoop humanInTheLoop;
@@ -178,6 +186,24 @@ public Builder patchPolicy(ToolContextPatchPolicy patchPolicy) {
178186
return this;
179187
}
180188

189+
/**
190+
* Opt-in strict tool-state mode. Tools then receive a read-only view of the
191+
* invocation state instead of the live map (writes escape only through the
192+
* {@link ToolContextPatchProvider} patch channel), and a failed call's patch is
193+
* always discarded regardless of {@code discardPatchOnFailedResult}. Merging
194+
* stays sequential last-write-wins, deliberately diverging from the graph path's
195+
* KeyStrategy-honoring strict merges: the ReAct state is an invocation-local
196+
* output map rather than the shared graph blackboard, and tool execution is
197+
* sequential, so the result is already deterministic w.r.t. completion order.
198+
* Default {@code false}: legacy behavior.
199+
* @param strict true to enable strict tool-state semantics
200+
* @return this builder
201+
*/
202+
public Builder strictToolState(boolean strict) {
203+
this.strictToolState = strict;
204+
return this;
205+
}
206+
181207
public Builder outcomeMappers(BusinessOutcomeMapperRegistry outcomeMappers) {
182208
this.outcomeMappers = Objects.requireNonNull(outcomeMappers, "outcomeMappers must not be null");
183209
return this;
@@ -492,7 +518,9 @@ private ToolStep executeTool(ToolCall call, List<ChatMessage> messages, Map<Stri
492518
return new ToolStep(false, null);
493519
}
494520
}
495-
CompletableFuture<ToolResult> future = availableTools.execute(call, new ToolContext(state)).toCompletableFuture();
521+
Map<String, Object> toolVisibleState = strictToolState ? StateIsolation.readOnlyView(state) : state;
522+
CompletableFuture<ToolResult> future = availableTools.execute(call, new ToolContext(toolVisibleState))
523+
.toCompletableFuture();
496524
toolOperation.set(future);
497525
try (AutoCloseable ignored = context.control().onLoss(() -> future.cancel(true))) {
498526
ToolResult result;
@@ -530,6 +558,16 @@ private void admitPatch(String toolName, ToolResult result, Map<String, Object>
530558
if (patch == null || patch.isEmpty()) {
531559
return;
532560
}
561+
if (strictToolState) {
562+
// Hard rule: a failed call's patch is always discarded, independent of
563+
// discardPatchOnFailedResult; the shared admission also applies the policy
564+
// validation, so both paths enforce identical rules.
565+
if (StrictPatchAdmission.admit(patchPolicy,
566+
new ToolUpdateUnit(toolName, !result.error(), patch))) {
567+
state.putAll(patch);
568+
}
569+
return;
570+
}
533571
if (patchPolicy != null && result.error() && patchPolicy.discardPatchOnFailedResult()) {
534572
return;
535573
}

0 commit comments

Comments
 (0)