feat: enhance LLM call control with AgentSkipCompletion enum and update related methods

README.md

@@ -1069,7 +1069,13 @@ If `context.setStreaming(true)` is enabled and the handler implements `StreamedA
 
 ### Skipping LLM Calls
 
-Set `context.setSkipNextCompletion(true)` to turn the next step into a processing-only pass. The flag resets automatically after that step.
+Use `context.setSkipNextCompletion(...)` to control LLM call behavior for the next step. The flag resets automatically after that step.
+
+| Value | Behavior |
+|-------|----------|
+| `AgentSkipCompletion.NO_SKIP` | Executes the LLM call normally (default) |
+| `AgentSkipCompletion.SETUP_CONVERSATION_ONLY` | Sets up the conversation but skips the LLM call |
+| `AgentSkipCompletion.SKIP` | Skips the entire turn, including conversation setup |
 
 ### Cache Bypass Controls
 

src/main/java/de/extio/lmlib/agent/AgentContext.java

@@ -27,7 +27,7 @@ public final class AgentContext {
 
 	private volatile Exception errorException;
 	
-	private volatile boolean skipNextCompletion;
+	private volatile AgentSkipCompletion skipNextCompletion;
 
 	private volatile boolean skipCache;
 
@@ -235,11 +235,11 @@ public final class AgentContext {
 		this.errorException = null;
 	}
 	
-	public boolean isSkipNextCompletion() {
+	public AgentSkipCompletion isSkipNextCompletion() {
 		return this.skipNextCompletion;
 	}
 	
-	public void setSkipNextCompletion(final boolean skipNextCompletion) {
+	public void setSkipNextCompletion(final AgentSkipCompletion skipNextCompletion) {
 		this.skipNextCompletion = skipNextCompletion;
 	}
 

src/main/java/de/extio/lmlib/agent/AgentSkipCompletion.java

@@ -0,0 +1,13 @@
+package de.extio.lmlib.agent;
+
+public enum AgentSkipCompletion {
+	
+	/** Execute the LLM call normally */
+	NO_SKIP,
+	
+	/** Only set up the conversation without executing the LLM call */
+	SETUP_CONVERSATION_ONLY,
+	
+	/** Skip the turn entirely */
+	SKIP
+}

src/main/java/de/extio/lmlib/agent/BaseAgent.java

@@ -134,7 +134,7 @@ public interface BaseAgent {
 			context.setError(AgentErrorType.GENERAL, ex);
 			return List.of(context);
 		}
-		final boolean skipCompletion = context.isSkipNextCompletion();
+		final AgentSkipCompletion skipCompletion = context.isSkipNextCompletion();
 
 		splits.addAll(this.applyTemplate(context));
 		final var tasks = new ArrayList<CompletableFuture<?>>(splits.size());
@@ -142,9 +142,10 @@ public interface BaseAgent {
 			tasks.add(CompletableFuture.runAsync(() -> {
 				try {
 					split.context().clearError();
-					final boolean skipCompletionInSplit = skipCompletion || this.agentType(split.context()) == AgentType.PROCESSING_ONLY;
+					final boolean skipCompletionInSplitEntirely = skipCompletion == AgentSkipCompletion.SKIP || this.agentType(split.context()) == AgentType.PROCESSING_ONLY;
-					if (skipCompletionInSplit) {
+					final boolean skipCompletionInSplitSetupConversation = skipCompletion == AgentSkipCompletion.SETUP_CONVERSATION_ONLY;
-						split.context().setSkipNextCompletion(false);
+					if (skipCompletionInSplitEntirely || skipCompletionInSplitSetupConversation) {
+						split.context().setSkipNextCompletion(AgentSkipCompletion.NO_SKIP);
 						split.context().getGraph().add("○");
 					}
 					else {
@@ -153,12 +154,13 @@ public interface BaseAgent {
 					}
 					split.context().getGraph().add(this.name());
 					
-					if (!skipCompletionInSplit) {
+					if (!skipCompletionInSplitEntirely) {
 						final var completionClient = Objects.requireNonNull(client);
 						final boolean skipCache = split.context().isSkipCache() || split.context().isAlwaysSkipCache();
 						split.context().setSkipCache(false);
 						final var conversation = this.setupConversation(split);
 						final var requestedModelProfile = this.modelProfile(split.context());
+						if (!skipCompletionInSplitSetupConversation) {
 							final var supportsToolCalling = requestedModelProfile != null ? completionClient.supportsToolCalling(requestedModelProfile) : completionClient.supportsToolCalling(this.modelCategory(split.context()));
 							var toolCallData = supportsToolCalling ? this.toolCallData(split.context()) : null;
 							this.rememberToolCallData(split.context(), toolCallData);
@@ -281,6 +283,7 @@ public interface BaseAgent {
 								}
 							} while (retryOuterLoop);
 						}
+					}
 					
 					this.postProcess(split.context());
 					if (split.context().getAgentContextUpdateConsumer() != null) {
@@ -465,8 +468,8 @@ public interface BaseAgent {
 		return conversation;
 	}
 	
-	private void appendLastCompletionToConversation(final AgentContext context, final boolean skipCompletion) {
+	private void appendLastCompletionToConversation(final AgentContext context, final AgentSkipCompletion skipCompletion) {
-		if (skipCompletion || context.getConversation() == null || context.getLastCompletion() == null) {
+		if (context.getConversation() == null || context.getLastCompletion() == null || (skipCompletion != null && skipCompletion != AgentSkipCompletion.NO_SKIP)) {
 			return;
 		}
 		final var currentAgent = context.getAgents().get(context.getCurrentAgentName());
@@ -496,7 +499,7 @@ public interface BaseAgent {
 		context.setValue("_toolCallData", null);
 	}
 	
-	private void nextAgent(final AgentContext context, final boolean skipCompletion) {
+	private void nextAgent(final AgentContext context, final AgentSkipCompletion skipCompletion) {
 		context.setNextAgent(this.chooseNextAgent(context));
 		
 		if (context.getNextAgent() != null) {