Wrap up langchain4j integration work; add CI to run integration tests

Signed-off-by: Ricardo Zanini <[email protected]>

Author: ricardozanini

.github/workflows/integration-tests.yml

@@ -0,0 +1,40 @@
+name: sdk-java Integration Tests
+on:
+  issue_comment:
+    types: [ created ]
+
+jobs:
+  run-integration-tests:
+    # 2) Only run if the comment is exactly "/run integration-tests"
+    #    and it’s on a pull request (not on an issue)
+    if: >
+      github.event.comment.body == '/run integration-tests' &&
+      github.event.issue.pull_request != null
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+      pull-requests: write
+      checks: write
+      id-token: write
+
+    steps:
+      # 3) Checkout the **PR’s** code
+      - name: Checkout PR code
+        uses: actions/checkout@v4
+        with:
+          repository: ${{ github.event.issue.pull_request.head.repo.full_name }}
+          ref: ${{ github.event.issue.pull_request.head.ref }}
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      # 4) Set up Java/Maven (cache enabled)
+      - name: Set up JDK 17
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: 17
+          cache: maven
+
+      # 5) Run only the IT suite
+      - name: Run integration-tests profile
+        run: mvn -B -f pom.xml clean verify -Pintegration-tests

.github/workflows/maven-verify.yml

@@ -17,35 +17,20 @@ jobs:
       - name: Checkout sdk-java
         uses: actions/checkout@v4
 
-      # 2. (Temporary) Checkout the langchain4j repo at agentic-module
-      - name: Checkout langchain4j (agentic-module)
-        uses: actions/checkout@v4
-        with:
-          repository: mariofusco/langchain4j
-          ref: agentic-module
-          path: langchain4j
-
-      # 3. Set up JDK 17 for both builds
+      # 2. Set up JDK 17 for both builds
       - name: Set up JDK 17
         uses: actions/setup-java@v4
         with:
           distribution: temurin
           java-version: 17
           cache: 'maven'
 
-      # 4. Build the external agentic module
-      - name: Build langchain4j-agentic
-        run: |
-          mvn -B -U -T12C -f langchain4j/pom.xml clean package -DskipTests
-          mvn -B -f langchain4j/langchain4j-agentic/pom.xml clean install -DskipTests
-
-      # 5. Verify the main sdk-java project, excluding the two agentic modules
+      # 3. Verify the main sdk-java project, excluding the two agentic modules
       - name: Verify with Maven
         run: |
-          mvn -B -f pom.xml clean install verify \
-            -am
+          mvn -B -f pom.xml clean install verify -am
 
-      # 6. Verify examples
+      # 4. Verify examples
       - name: Verify Examples with Maven
         run: |
           mvn -B -f examples/pom.xml clean install verify

experimental/agentic/src/main/java/io/serverlessworkflow/impl/expressions/agentic/AgenticModel.java

@@ -15,16 +15,17 @@
  */
 package io.serverlessworkflow.impl.expressions.agentic;
 
-import dev.langchain4j.agentic.cognisphere.Cognisphere;
+import dev.langchain4j.agentic.scope.AgenticScope;
 import io.serverlessworkflow.impl.WorkflowModel;
 import io.serverlessworkflow.impl.expressions.func.JavaModel;
 import java.util.Collection;
+import java.util.Map;
 import java.util.Optional;
 
 class AgenticModel extends JavaModel {
 
-  AgenticModel(Cognisphere cognisphere) {
-    super(cognisphere);
+  AgenticModel(AgenticScope agenticScope) {
+    super(agenticScope);
   }
 
   @Override
@@ -39,8 +40,10 @@ public Collection<WorkflowModel> asCollection() {
 
   @Override
   public <T> Optional<T> as(Class<T> clazz) {
-    if (Cognisphere.class.isAssignableFrom(clazz)) {
+    if (AgenticScope.class.isAssignableFrom(clazz)) {
       return Optional.of(clazz.cast(object));
+    } else if (Map.class.isAssignableFrom(clazz)) {
+      return Optional.of(clazz.cast(((AgenticScope) object).state()));
     } else {
       return super.as(clazz);
     }

experimental/agentic/src/main/java/io/serverlessworkflow/impl/expressions/agentic/AgenticModelCollection.java

@@ -15,37 +15,37 @@
  */
 package io.serverlessworkflow.impl.expressions.agentic;
 
-import dev.langchain4j.agentic.cognisphere.Cognisphere;
-import dev.langchain4j.agentic.cognisphere.ResultWithCognisphere;
+import dev.langchain4j.agentic.scope.AgenticScope;
+import dev.langchain4j.agentic.scope.ResultWithAgenticScope;
 import io.serverlessworkflow.impl.WorkflowModel;
 import io.serverlessworkflow.impl.expressions.func.JavaModelCollection;
 import java.util.Collection;
 import java.util.Optional;
 
 class AgenticModelCollection extends JavaModelCollection {
 
-  private final Cognisphere cognisphere;
+  private final AgenticScope agenticScope;
 
-  AgenticModelCollection(Collection<?> object, Cognisphere cognisphere) {
+  AgenticModelCollection(Collection<?> object, AgenticScope agenticScope) {
     super(object);
-    this.cognisphere = cognisphere;
+    this.agenticScope = agenticScope;
   }
 
-  AgenticModelCollection(Cognisphere cognisphere) {
-    this.cognisphere = cognisphere;
+  AgenticModelCollection(AgenticScope agenticScope) {
+    this.agenticScope = agenticScope;
   }
 
   @Override
   protected WorkflowModel nextItem(Object obj) {
-    return new AgenticModel((Cognisphere) obj);
+    return new AgenticModel((AgenticScope) obj);
   }
 
   @Override
   public <T> Optional<T> as(Class<T> clazz) {
-    if (Cognisphere.class.isAssignableFrom(clazz)) {
-      return Optional.of(clazz.cast(cognisphere));
-    } else if (ResultWithCognisphere.class.isAssignableFrom(clazz)) {
-      return Optional.of(clazz.cast(new ResultWithCognisphere<>(cognisphere, object)));
+    if (AgenticScope.class.isAssignableFrom(clazz)) {
+      return Optional.of(clazz.cast(agenticScope));
+    } else if (ResultWithAgenticScope.class.isAssignableFrom(clazz)) {
+      return Optional.of(clazz.cast(new ResultWithAgenticScope<>(agenticScope, object)));
     } else {
       return super.as(clazz);
     }

experimental/agentic/src/main/java/io/serverlessworkflow/impl/expressions/agentic/AgenticModelFactory.java

@@ -15,39 +15,38 @@
  */
 package io.serverlessworkflow.impl.expressions.agentic;
 
-import dev.langchain4j.agentic.cognisphere.Cognisphere;
+import dev.langchain4j.agentic.scope.AgenticScope;
 import io.cloudevents.CloudEvent;
 import io.cloudevents.CloudEventData;
 import io.serverlessworkflow.impl.WorkflowModel;
 import io.serverlessworkflow.impl.WorkflowModelCollection;
 import io.serverlessworkflow.impl.WorkflowModelFactory;
-import io.serverlessworkflow.impl.expressions.agentic.langchain4j.CognisphereRegistryAssessor;
+import io.serverlessworkflow.impl.expressions.agentic.langchain4j.AgenticScopeRegistryAssessor;
 import io.serverlessworkflow.impl.expressions.func.JavaModel;
 import java.time.OffsetDateTime;
 import java.util.Map;
 
 class AgenticModelFactory implements WorkflowModelFactory {
 
   /**
-   * Applies any change to the model after running as task. We will always set it to
-   * a @DefaultCognisphere object since @AgentExecutor is always adding the output to the
-   * cognisphere. We just have to make sure that cognisphere is always passed to the next input
-   * task.
+   * Applies any change to the model after running as task. We will always set it to a @AgenticScope
+   * object since @AgentExecutor is always adding the output to the agenticScope. We just have to
+   * make sure that agenticScope is always passed to the next input task.
    *
-   * @param prev the global Cognisphere object getting updated by the workflow context
-   * @param obj the same Cognisphere object updated by the AgentExecutor
-   * @return the workflow context model holding the cognisphere object.
+   * @param prev the global AgenticScope object getting updated by the workflow context
+   * @param obj the same AgenticScope object updated by the AgentExecutor
+   * @return the workflow context model holding the agenticScope object.
    */
   @Override
   public WorkflowModel fromAny(WorkflowModel prev, Object obj) {
-    // We ignore `obj` since it's already included in `prev` within the Cognisphere instance
+    // We ignore `obj` since it's already included in `prev` within the agenticScope instance
     return prev;
   }
 
   @Override
   public WorkflowModel combine(Map<String, WorkflowModel> workflowVariables) {
-    // TODO: create a new cognisphere object in the CognisphereRegistryAssessor per branch
-    // TODO: Since we share the same cognisphere object, both branches are updating the same
+    // TODO: create a new agenticScope object in the AgenticScopeRegistryAssessor per branch
+    // TODO: Since we share the same agenticScope object, both branches are updating the same
     // instance, so for now we return the first key.
     return workflowVariables.values().iterator().next();
   }
@@ -57,7 +56,7 @@ public WorkflowModelCollection createCollection() {
     throw new UnsupportedOperationException();
   }
 
-  // TODO: all these methods can use Cognisphere as long as we have access to the `outputName`
+  // TODO: all these methods can use agenticScope as long as we have access to the `outputName`
 
   @Override
   public WorkflowModel from(boolean value) {
@@ -91,9 +90,9 @@ public WorkflowModel from(OffsetDateTime value) {
 
   @Override
   public WorkflowModel from(Map<String, Object> map) {
-    final Cognisphere cognisphere = new CognisphereRegistryAssessor().getCognisphere();
-    cognisphere.writeStates(map);
-    return new AgenticModel(cognisphere);
+    final AgenticScope agenticScope = new AgenticScopeRegistryAssessor().getAgenticScope();
+    agenticScope.writeStates(map);
+    return new AgenticModel(agenticScope);
   }
 
   @Override
@@ -103,8 +102,8 @@ public WorkflowModel fromNull() {
 
   @Override
   public WorkflowModel fromOther(Object value) {
-    if (value instanceof Cognisphere) {
-      return new AgenticModel((Cognisphere) value);
+    if (value instanceof AgenticScope) {
+      return new AgenticModel((AgenticScope) value);
     }
     return new JavaModel(value);
   }

experimental/agentic/src/main/java/io/serverlessworkflow/impl/expressions/agentic/langchain4j/CognisphereRegistryAssessor.java renamed to experimental/agentic/src/main/java/io/serverlessworkflow/impl/expressions/agentic/langchain4j/AgenticScopeRegistryAssessor.java

@@ -15,56 +15,57 @@
  */
 package io.serverlessworkflow.impl.expressions.agentic.langchain4j;
 
-import dev.langchain4j.agentic.cognisphere.CognisphereRegistry;
-import dev.langchain4j.agentic.cognisphere.DefaultCognisphere;
-import dev.langchain4j.agentic.internal.CognisphereOwner;
+import dev.langchain4j.agentic.internal.AgenticScopeOwner;
+import dev.langchain4j.agentic.scope.AgenticScopeRegistry;
+import dev.langchain4j.agentic.scope.DefaultAgenticScope;
 import java.util.Objects;
 import java.util.UUID;
 import java.util.concurrent.atomic.AtomicReference;
 
-public class CognisphereRegistryAssessor implements CognisphereOwner {
+public class AgenticScopeRegistryAssessor implements AgenticScopeOwner {
 
-  private final AtomicReference<CognisphereRegistry> cognisphereRegistry = new AtomicReference<>();
+  private final AtomicReference<AgenticScopeRegistry> agenticScopeRegistry =
+      new AtomicReference<>();
   private final String agentId;
-  private DefaultCognisphere cognisphere;
+  private DefaultAgenticScope agenticScope;
   private Object memoryId;
 
-  public CognisphereRegistryAssessor(String agentId) {
+  public AgenticScopeRegistryAssessor(String agentId) {
     Objects.requireNonNull(agentId, "Agent id cannot be null");
     this.agentId = agentId;
   }
 
   // TODO: have access to the workflow definition and assign its name instead
-  public CognisphereRegistryAssessor() {
+  public AgenticScopeRegistryAssessor() {
     this.agentId = UUID.randomUUID().toString();
   }
 
   public void setMemoryId(Object memoryId) {
     this.memoryId = memoryId;
   }
 
-  public DefaultCognisphere getCognisphere() {
-    if (cognisphere != null) {
-      return cognisphere;
+  public DefaultAgenticScope getAgenticScope() {
+    if (agenticScope != null) {
+      return agenticScope;
     }
 
     if (memoryId != null) {
-      this.cognisphere = registry().getOrCreate(memoryId);
+      this.agenticScope = registry().getOrCreate(memoryId);
     } else {
-      this.cognisphere = registry().createEphemeralCognisphere();
+      this.agenticScope = registry().createEphemeralAgenticScope();
     }
-    return this.cognisphere;
+    return this.agenticScope;
   }
 
   @Override
-  public CognisphereOwner withCognisphere(DefaultCognisphere cognisphere) {
-    this.cognisphere = cognisphere;
+  public AgenticScopeOwner withAgenticScope(DefaultAgenticScope agenticScope) {
+    this.agenticScope = agenticScope;
     return this;
   }
 
   @Override
-  public CognisphereRegistry registry() {
-    cognisphereRegistry.compareAndSet(null, new CognisphereRegistry(agentId));
-    return cognisphereRegistry.get();
+  public AgenticScopeRegistry registry() {
+    agenticScopeRegistry.compareAndSet(null, new AgenticScopeRegistry(agentId));
+    return agenticScopeRegistry.get();
   }
 }

fluent/agentic-langchain4j/src/main/java/io/serverlessworkflow/fluent/agentic/langchain4j/AbstractAgentService.java

@@ -15,10 +15,12 @@
  */
 package io.serverlessworkflow.fluent.agentic.langchain4j;
 
-import dev.langchain4j.agentic.cognisphere.Cognisphere;
-import dev.langchain4j.agentic.cognisphere.DefaultCognisphere;
+import dev.langchain4j.agentic.agent.ErrorContext;
+import dev.langchain4j.agentic.agent.ErrorRecoveryResult;
 import dev.langchain4j.agentic.internal.AgentSpecification;
-import dev.langchain4j.agentic.internal.CognisphereOwner;
+import dev.langchain4j.agentic.internal.AgenticScopeOwner;
+import dev.langchain4j.agentic.scope.AgenticScope;
+import dev.langchain4j.agentic.scope.DefaultAgenticScope;
 import io.serverlessworkflow.api.types.Workflow;
 import io.serverlessworkflow.fluent.agentic.AgentWorkflowBuilder;
 import io.serverlessworkflow.impl.WorkflowApplication;
@@ -29,7 +31,8 @@
 public abstract class AbstractAgentService<T, S> implements WorkflowDefinitionBuilder {
 
   // Workflow OutputAs
-  private static final Function<Cognisphere, Object> DEFAULT_OUTPUT_FUNCTION = cognisphere -> null;
+  private static final Function<AgenticScope, Object> DEFAULT_OUTPUT_FUNCTION =
+      agenticScope -> null;
 
   protected final WorkflowApplication.Builder workflowExecBuilder;
   protected final AgentWorkflowBuilder workflowBuilder;
@@ -46,34 +49,39 @@ public T build() {
     return (T)
         Proxy.newProxyInstance(
             this.agentServiceClass.getClassLoader(),
-            new Class<?>[] {agentServiceClass, AgentSpecification.class, CognisphereOwner.class},
+            new Class<?>[] {agentServiceClass, AgentSpecification.class, AgenticScopeOwner.class},
             new WorkflowInvocationHandler(
                 this.workflowBuilder.build(), this.workflowExecBuilder, this.agentServiceClass));
   }
 
   @SuppressWarnings("unchecked")
-  public S beforeCall(Consumer<Cognisphere> beforeCall) {
+  public S beforeCall(Consumer<AgenticScope> beforeCall) {
     this.workflowBuilder.inputFrom(
         cog -> {
           beforeCall.accept(cog);
           return cog;
         },
-        Cognisphere.class);
+        AgenticScope.class);
     return (S) this;
   }
 
   @SuppressWarnings("unchecked")
   public S outputName(String outputName) {
-    Function<DefaultCognisphere, Object> outputFunction = cog -> cog.readState(outputName);
-    this.workflowBuilder.outputAs(outputFunction, DefaultCognisphere.class);
+    Function<DefaultAgenticScope, Object> outputFunction = cog -> cog.readState(outputName);
+    this.workflowBuilder.outputAs(outputFunction, DefaultAgenticScope.class);
     this.workflowBuilder.document(
         d -> d.metadata(m -> m.metadata(META_KEY_OUTPUTNAME, outputName)));
     return (S) this;
   }
 
   @SuppressWarnings("unchecked")
-  public S output(Function<Cognisphere, Object> output) {
-    this.workflowBuilder.outputAs(output, Cognisphere.class);
+  public S output(Function<AgenticScope, Object> output) {
+    this.workflowBuilder.outputAs(output, AgenticScope.class);
+    return (S) this;
+  }
+
+  @SuppressWarnings("unchecked")
+  public S errorHandler(Function<ErrorContext, ErrorRecoveryResult> errorHandler) {
     return (S) this;
   }