feat(agent): add graph-independent ReAct core

README.md

@@ -62,6 +62,7 @@ Open [http://localhost:8080/chatui/index.html](http://localhost:8080/chatui/inde
 | [Graph Core](argi-graph-core) | State management, persistence, and workflow runtime |
 | [Runtime API](argi-runtime-api) | JDK-only identity, definition and execution-control contracts |
 | [Agent API](argi-agent-api) | Engine-neutral agent invocation and shared interception contracts |
+| [Agent Core](argi-agent-core) | Graph-independent ReAct execution loop and tool lifecycle |
 | [Runtime Core](argi-runtime-core) | Engine-neutral Run/Task data, codecs and reference storage |
 | [Studio](argi-studio) | Visual debugging UI for agents |
 | [Sandbox](https://github.com/agentic-ai-java/argi-extensions/tree/main/sandbox/argi-sandbox) | Optional isolated execution environment for tool calls, maintained in Extensions |

argi-agent-api/README.md

@@ -6,8 +6,9 @@ Agent invocation contracts. Its only production dependencies are `argi-api`
 budgets and execution control). It does not bring in Graph, Runtime Core,
 Jackson, Reactor, Spring, provider SDKs or an execution engine.
 
-This completes the contract extraction in [#195](https://github.com/agentic-ai-java/argi/issues/195),
-not the independent ReAct engine (#196), declarative Workflow engine (#197),
+This completes the contract extraction in [#195](https://github.com/agentic-ai-java/argi/issues/195) and
+is consumed by the independent ReAct engine in `argi-agent-core`; it is not the
+declarative Workflow engine (#197),
 Loop migration/optional bridge (#198), or definition factories (#199).
 The existing Graph-backed agents continue to work through their existing API.
 

argi-agent-framework/src/main/java/io/github/agentic/ai/graph/agent/AgentResult.java → argi-agent-api/src/main/java/io/github/agentic/ai/graph/agent/AgentResult.java

@@ -22,7 +22,7 @@
 
 /**
  * Structured delivery contract for an agent run, produced by the opt-in
- * {@link ReactAgent#callResult(Object)} entries. The existing {@code call}/{@code
+ * strict result-delivery entries. The existing Graph {@code call}/{@code
  * invoke}/{@code stream} APIs keep returning raw messages; this type is only produced
  * by the strict-delivery entries, so adoption is fully opt-in.
  *

argi-agent-core/README.md

@@ -0,0 +1,40 @@
+# ARGI Agent Core
+
+`argi-agent-core` contains the first graph-independent ReAct execution engine. It
+depends on `argi-agent-api`, `argi-api` and `argi-runtime-api`; it does not load
+`StateGraph`, `CompiledGraph`, `RunnableConfig`, Graph persistence, Reactor or a
+Spring application context.
+
+## Execution stages
+
+`ReActAgent` performs the following ordered stages for every turn:
+
+1. Build a neutral model request and apply model interceptors.
+2. Call the model synchronously or consume its normalized stream.
+3. Append the assistant response and publish usage/message events.
+4. Authorize and optionally validate every tool call.
+5. Execute tools sequentially, map business outcomes and append tool messages.
+6. Admit optional context patches at the configured validation boundary.
+7. Finish, suspend for human approval, or continue until the turn limit.
+
+Tool failures become model-visible error messages and normally continue the loop,
+matching the existing agent behavior. Authorization failures either become an error
+message or enter the explicitly configured `HumanInTheLoop` boundary. Cancellation,
+deadline expiry and ownership loss fail the execution and cancel the in-flight model
+or tool stage; no state is published after control loss.
+
+## Deliberate boundaries
+
+This slice supports sequential tool calls, in-process human suspension and opaque
+resume validation. It does not provide Graph checkpoint recovery, parallel tool
+aggregation, a scheduler, durable HITL storage, child-agent orchestration or a
+remote protocol. Those semantics require explicit contracts in the corresponding
+architecture tasks and are not silently emulated with an `OverAllState` replacement.
+
+Structured output uses the shared `StructuredOutputFinalizer`; invalid output fails
+the execution through `AgentExecutionException` instead of being reported as a
+successful `AgentOutcome`.
+
+The existing Graph-backed `ReactAgent` remains unchanged and continues to own its
+Graph state, checkpoints, hooks and legacy public API. Applications opt into this
+engine by depending on `argi-agent-core` and constructing `ReActAgent` directly.

argi-agent-core/pom.xml

@@ -0,0 +1,64 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ * Copyright 2026 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ -->
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <parent>
+        <groupId>io.github.agentic-ai-java</groupId>
+        <artifactId>argi</artifactId>
+        <version>${revision}</version>
+    </parent>
+    <artifactId>argi-agent-core</artifactId>
+    <packaging>jar</packaging>
+    <name>ARGI Agent Core</name>
+    <description>Graph-independent ReAct execution and shared agent runtime components</description>
+    <dependencies>
+        <dependency>
+            <groupId>org.assertj</groupId>
+            <artifactId>assertj-core</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>io.github.agentic-ai-java</groupId>
+            <artifactId>argi-agent-api</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>io.github.agentic-ai-java</groupId>
+            <artifactId>argi-api</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>io.github.agentic-ai-java</groupId>
+            <artifactId>argi-runtime-api</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>com.fasterxml.jackson.core</groupId>
+            <artifactId>jackson-databind</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>com.networknt</groupId>
+            <artifactId>json-schema-validator</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>tools.jackson.core</groupId>
+            <artifactId>jackson-databind</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter</artifactId>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+</project>

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

@@ -0,0 +1,34 @@
+/*
+ * Copyright 2026 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.github.agentic.ai.agent.react;
+
+import io.github.agentic.ai.graph.agent.AgentResult;
+
+/** Signals a failed structured-output delivery without turning it into a successful outcome. */
+public final class AgentExecutionException extends RuntimeException {
+
+	private final AgentResult result;
+
+	public AgentExecutionException(AgentResult result) {
+		super("Agent execution did not produce a valid structured result");
+		this.result = result;
+	}
+
+	public AgentResult result() {
+		return result;
+	}
+
+}

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

@@ -0,0 +1,50 @@
+/*
+ * Copyright 2026 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.github.agentic.ai.agent.react;
+
+import io.github.agentic.ai.agent.AgentExecutionContext;
+import io.github.agentic.ai.agent.AgentOutcome;
+import io.github.agentic.ai.agent.AgentRequest;
+
+import java.util.Map;
+
+/**
+ * Application boundary for pausing a ReAct run when a human decision is required.
+ * Durable storage, token authentication and replay protection remain application
+ * responsibilities; this interface does not turn a token into a credential.
+ */
+public interface HumanInTheLoop {
+
+	/**
+	 * Validates an opaque continuation before the run consumes resumed inputs.
+	 * Implementations should reject stale, replayed or cross-tenant tokens.
+	 */
+	default void validateResume(AgentRequest request, AgentExecutionContext context) {
+	}
+
+	/** Creates the application-owned continuation returned to the caller. */
+	AgentOutcome.Suspension suspend(HumanRequest request, AgentExecutionContext context);
+
+	record HumanRequest(String reason, String toolName, String toolCallId, Map<String, Object> details) {
+
+		public HumanRequest {
+			reason = reason == null ? "Human approval is required" : reason;
+			details = details == null ? Map.of() : Map.copyOf(details);
+		}
+
+	}
+
+}