feat(agent): control model retry attempts with a deadline-aware policy (issue #313)

argi-agent/argi-agent-api/src/main/java/io/github/agentic/ai/agent/interceptor/ModelRequest.java

@@ -20,6 +20,7 @@
 import io.github.agentic.ai.api.chat.ChatRole;
 import io.github.agentic.ai.api.chat.GenerationOptions;
 import io.github.agentic.ai.api.tool.ToolRegistry;
+import io.github.agentic.ai.runtime.execution.ExecutionGuard;
 import io.github.agentic.ai.runtime.execution.TrustedExecutionContext;
 
 import java.util.ArrayList;
@@ -62,6 +63,12 @@ public class ModelRequest {
 	// context map.
 	private final TrustedExecutionContext trustedExecutionContext;
 
+	// The guard of the run that owns this request. It carries the liveness and the
+	// deadline of the run to the interceptors, so that a retry sequence can be
+	// bounded by the run itself. It never leaves the process: the request attributes
+	// are passed to the provider and must stay free of runtime objects.
+	private final ExecutionGuard executionGuard;
+
 	public ModelRequest(ChatMessage systemMessage, List<ChatMessage> messages, GenerationOptions options,
 			ChatClient chatClient, ToolRegistry toolRegistry, List<String> tools, boolean toolSelectionSpecified,
 			ToolRegistry dynamicToolRegistry, Map<String, String> toolDescriptions, Map<String, Object> context,
@@ -74,6 +81,15 @@ public ModelRequest(ChatMessage systemMessage, List<ChatMessage> messages, Gener
 			ChatClient chatClient, ToolRegistry toolRegistry, List<String> tools, boolean toolSelectionSpecified,
 			ToolRegistry dynamicToolRegistry, Map<String, String> toolDescriptions, Map<String, Object> context,
 			Map<String, Object> attributes, TrustedExecutionContext trustedExecutionContext) {
+		this(systemMessage, messages, options, chatClient, toolRegistry, tools, toolSelectionSpecified,
+				dynamicToolRegistry, toolDescriptions, context, attributes, trustedExecutionContext, null);
+	}
+
+	public ModelRequest(ChatMessage systemMessage, List<ChatMessage> messages, GenerationOptions options,
+			ChatClient chatClient, ToolRegistry toolRegistry, List<String> tools, boolean toolSelectionSpecified,
+			ToolRegistry dynamicToolRegistry, Map<String, String> toolDescriptions, Map<String, Object> context,
+			Map<String, Object> attributes, TrustedExecutionContext trustedExecutionContext,
+			ExecutionGuard executionGuard) {
 		if (systemMessage != null && systemMessage.role() != ChatRole.SYSTEM) {
 			throw new IllegalArgumentException("systemMessage must have the SYSTEM role");
 		}
@@ -90,6 +106,7 @@ public ModelRequest(ChatMessage systemMessage, List<ChatMessage> messages, Gener
 		this.context = new HashMap<>(context);
 		this.attributes = Map.copyOf(attributes);
 		this.trustedExecutionContext = trustedExecutionContext;
+		this.executionGuard = executionGuard;
 	}
 
 	public static Builder builder() {
@@ -107,7 +124,8 @@ public static Builder builder(ModelRequest request) {
 			.toolDescriptions(request.toolDescriptions)
 			.context(request.context)
 			.attributes(request.attributes)
-			.trustedExecutionContext(request.trustedExecutionContext);
+			.trustedExecutionContext(request.trustedExecutionContext)
+			.executionGuard(request.executionGuard);
 		copy.toolSelectionSpecified = request.toolSelectionSpecified;
 		return copy;
 	}
@@ -167,6 +185,16 @@ public Optional<TrustedExecutionContext> getTrustedExecutionContext() {
 		return Optional.ofNullable(trustedExecutionContext);
 	}
 
+	/**
+	 * The guard of the run that issued this model call, when the run carries one. The
+	 * guard reports the liveness and the deadline of the run, so that an interceptor
+	 * that repeats the call can stop the sequence when the run is cancelled or out of
+	 * time. It is never passed to the provider.
+	 */
+	public Optional<ExecutionGuard> getExecutionGuard() {
+		return Optional.ofNullable(executionGuard);
+	}
+
 	public Map<String, String> getToolDescriptions() {
 		return toolDescriptions;
 	}
@@ -209,6 +237,8 @@ public static class Builder {
 
 		private TrustedExecutionContext trustedExecutionContext;
 
+		private ExecutionGuard executionGuard;
+
 		public Builder systemMessage(ChatMessage systemMessage) {
 			this.systemMessage = systemMessage;
 			return this;
@@ -277,10 +307,19 @@ public Builder trustedExecutionContext(TrustedExecutionContext trustedExecutionC
 			return this;
 		}
 
+		/**
+		 * Sets the guard of the run that owns this model call. The guard is propagated
+		 * by the engine and stays inside the process.
+		 */
+		public Builder executionGuard(ExecutionGuard executionGuard) {
+			this.executionGuard = executionGuard;
+			return this;
+		}
+
 		public ModelRequest build() {
 			return new ModelRequest(systemMessage, messages, options, chatClient, toolRegistry, tools,
 					toolSelectionSpecified, dynamicToolRegistry, toolDescriptions, context, attributes,
-					trustedExecutionContext);
+					trustedExecutionContext, executionGuard);
 		}
 
 	}

argi-agent/argi-agent-api/src/main/java/io/github/agentic/ai/agent/retry/ModelCallFailure.java

@@ -0,0 +1,43 @@
+/*
+ * Copyright 2024-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.retry;
+
+import java.util.Objects;
+import java.util.Set;
+
+/**
+ * A classified model call failure.
+ *
+ * @param category the classification of the failure
+ * @param cause the original failure, may be {@code null} when the failure was not
+ * classified from a throwable
+ */
+public record ModelCallFailure(ModelCallFailureCategory category, Throwable cause) {
+
+	public ModelCallFailure {
+		Objects.requireNonNull(category, "category must not be null");
+	}
+
+	/**
+	 * Whether the failure may be retried under the given policy.
+	 * @param retryableCategories the categories the policy allows to retry
+	 * @return {@code true} when the category is retryable
+	 */
+	public boolean isRetryable(Set<ModelCallFailureCategory> retryableCategories) {
+		return retryableCategories.contains(category);
+	}
+
+}

argi-agent/argi-agent-api/src/main/java/io/github/agentic/ai/agent/retry/ModelCallFailureCategory.java

@@ -0,0 +1,51 @@
+/*
+ * Copyright 2024-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.retry;
+
+/**
+ * Classification of a failed model call.
+ *
+ * <p>
+ * The category is derived from the failure itself, never from the text of an
+ * exception message: a permanent rejection that happens to mention a timeout must not
+ * be retried.
+ */
+public enum ModelCallFailureCategory {
+
+	/** A temporary failure that a later attempt may still overcome. */
+	TRANSIENT,
+
+	/** The provider asked the caller to slow down. */
+	RATE_LIMITED,
+
+	/** The request itself was rejected; another attempt cannot change the outcome. */
+	PERMANENT,
+
+	/** The call was cancelled or interrupted and must never be retried. */
+	CANCELLED,
+
+	/** The failure could not be classified and is therefore not retried by default. */
+	UNKNOWN;
+
+	/**
+	 * Whether this category is retryable without further configuration.
+	 * @return {@code true} for {@link #TRANSIENT} and {@link #RATE_LIMITED}
+	 */
+	public boolean isRetryableByDefault() {
+		return this == TRANSIENT || this == RATE_LIMITED;
+	}
+
+}

argi-orchestration/argi-agent-framework/src/test/java/io/github/agentic/ai/agent/orchestration/interceptor/modelretry/RetryDelayCalculatorTest.java → argi-agent/argi-agent-api/src/main/java/io/github/agentic/ai/agent/retry/ModelCallFailureClassifier.java

@@ -13,23 +13,24 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package io.github.agentic.ai.agent.orchestration.interceptor.modelretry;
+package io.github.agentic.ai.agent.retry;
 
-import org.junit.jupiter.api.Test;
-
-import static org.junit.jupiter.api.Assertions.assertEquals;
-
-class RetryDelayCalculatorTest {
-
-	@Test
-	void exponentialDelayIsCappedWithoutReadingTheClock() {
-		assertEquals(150, RetryDelayCalculator.nextDelay(100, 3.0, 150));
-		assertEquals(150, RetryDelayCalculator.nextDelay(150, 3.0, 150));
-	}
+/**
+ * Classifies a failed model call into a {@link ModelCallFailureCategory}.
+ *
+ * <p>
+ * Implementations must classify from the failure type and its cause chain. Matching
+ * on the text of an exception message is not a classification: the same message can
+ * describe a permanent rejection or a transient outage.
+ */
+@FunctionalInterface
+public interface ModelCallFailureClassifier {
 
-	@Test
-	void zeroDelayRemainsZero() {
-		assertEquals(0, RetryDelayCalculator.nextDelay(0, 2.0, 30_000));
-	}
+	/**
+	 * Classifies a failure.
+	 * @param failure the failure raised by the model call
+	 * @return the classified failure, never {@code null}
+	 */
+	ModelCallFailure classify(Throwable failure);
 
 }