Skip to content

Commit b81355b

Browse files
committed
feat(agent): control model retry attempts with a deadline-aware policy (issue agentic-ai-java#313)
The retry sequence of a model call was not bounded by its run. The retryability of a failure was guessed from the text of the exception message, the deadline of the run was ignored, and a cancelled run kept receiving provider calls because the loop observed thread interruption only. The decision now belongs to a neutral contract in argi-agent-api (io.github.agentic.ai.agent.retry) that classifies the failure by type and cause chain, bounds the number of attempts and observes the deadline and the cancellation of the run. The run guard reaches the interceptor through an optional ExecutionGuard on ModelRequest and is propagated by the independent ReAct engine and by the framework node, so a cancelled or expired run ends the backoff instead of dispatching another call. The existing configuration keeps its behaviour and every existing builder option keeps its default value; the type based classifier, the retryable categories, the reserved deadline time and the clock are opt in.
1 parent 03227f7 commit b81355b

17 files changed

Lines changed: 1696 additions & 74 deletions

File tree

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

Lines changed: 41 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@
2020
import io.github.agentic.ai.api.chat.ChatRole;
2121
import io.github.agentic.ai.api.chat.GenerationOptions;
2222
import io.github.agentic.ai.api.tool.ToolRegistry;
23+
import io.github.agentic.ai.runtime.execution.ExecutionGuard;
2324
import io.github.agentic.ai.runtime.execution.TrustedExecutionContext;
2425

2526
import java.util.ArrayList;
@@ -62,6 +63,12 @@ public class ModelRequest {
6263
// context map.
6364
private final TrustedExecutionContext trustedExecutionContext;
6465

66+
// The guard of the run that owns this request. It carries the liveness and the
67+
// deadline of the run to the interceptors, so that a retry sequence can be
68+
// bounded by the run itself. It never leaves the process: the request attributes
69+
// are passed to the provider and must stay free of runtime objects.
70+
private final ExecutionGuard executionGuard;
71+
6572
public ModelRequest(ChatMessage systemMessage, List<ChatMessage> messages, GenerationOptions options,
6673
ChatClient chatClient, ToolRegistry toolRegistry, List<String> tools, boolean toolSelectionSpecified,
6774
ToolRegistry dynamicToolRegistry, Map<String, String> toolDescriptions, Map<String, Object> context,
@@ -74,6 +81,15 @@ public ModelRequest(ChatMessage systemMessage, List<ChatMessage> messages, Gener
7481
ChatClient chatClient, ToolRegistry toolRegistry, List<String> tools, boolean toolSelectionSpecified,
7582
ToolRegistry dynamicToolRegistry, Map<String, String> toolDescriptions, Map<String, Object> context,
7683
Map<String, Object> attributes, TrustedExecutionContext trustedExecutionContext) {
84+
this(systemMessage, messages, options, chatClient, toolRegistry, tools, toolSelectionSpecified,
85+
dynamicToolRegistry, toolDescriptions, context, attributes, trustedExecutionContext, null);
86+
}
87+
88+
public ModelRequest(ChatMessage systemMessage, List<ChatMessage> messages, GenerationOptions options,
89+
ChatClient chatClient, ToolRegistry toolRegistry, List<String> tools, boolean toolSelectionSpecified,
90+
ToolRegistry dynamicToolRegistry, Map<String, String> toolDescriptions, Map<String, Object> context,
91+
Map<String, Object> attributes, TrustedExecutionContext trustedExecutionContext,
92+
ExecutionGuard executionGuard) {
7793
if (systemMessage != null && systemMessage.role() != ChatRole.SYSTEM) {
7894
throw new IllegalArgumentException("systemMessage must have the SYSTEM role");
7995
}
@@ -90,6 +106,7 @@ public ModelRequest(ChatMessage systemMessage, List<ChatMessage> messages, Gener
90106
this.context = new HashMap<>(context);
91107
this.attributes = Map.copyOf(attributes);
92108
this.trustedExecutionContext = trustedExecutionContext;
109+
this.executionGuard = executionGuard;
93110
}
94111

95112
public static Builder builder() {
@@ -107,7 +124,8 @@ public static Builder builder(ModelRequest request) {
107124
.toolDescriptions(request.toolDescriptions)
108125
.context(request.context)
109126
.attributes(request.attributes)
110-
.trustedExecutionContext(request.trustedExecutionContext);
127+
.trustedExecutionContext(request.trustedExecutionContext)
128+
.executionGuard(request.executionGuard);
111129
copy.toolSelectionSpecified = request.toolSelectionSpecified;
112130
return copy;
113131
}
@@ -167,6 +185,16 @@ public Optional<TrustedExecutionContext> getTrustedExecutionContext() {
167185
return Optional.ofNullable(trustedExecutionContext);
168186
}
169187

188+
/**
189+
* The guard of the run that issued this model call, when the run carries one. The
190+
* guard reports the liveness and the deadline of the run, so that an interceptor
191+
* that repeats the call can stop the sequence when the run is cancelled or out of
192+
* time. It is never passed to the provider.
193+
*/
194+
public Optional<ExecutionGuard> getExecutionGuard() {
195+
return Optional.ofNullable(executionGuard);
196+
}
197+
170198
public Map<String, String> getToolDescriptions() {
171199
return toolDescriptions;
172200
}
@@ -209,6 +237,8 @@ public static class Builder {
209237

210238
private TrustedExecutionContext trustedExecutionContext;
211239

240+
private ExecutionGuard executionGuard;
241+
212242
public Builder systemMessage(ChatMessage systemMessage) {
213243
this.systemMessage = systemMessage;
214244
return this;
@@ -277,10 +307,19 @@ public Builder trustedExecutionContext(TrustedExecutionContext trustedExecutionC
277307
return this;
278308
}
279309

310+
/**
311+
* Sets the guard of the run that owns this model call. The guard is propagated
312+
* by the engine and stays inside the process.
313+
*/
314+
public Builder executionGuard(ExecutionGuard executionGuard) {
315+
this.executionGuard = executionGuard;
316+
return this;
317+
}
318+
280319
public ModelRequest build() {
281320
return new ModelRequest(systemMessage, messages, options, chatClient, toolRegistry, tools,
282321
toolSelectionSpecified, dynamicToolRegistry, toolDescriptions, context, attributes,
283-
trustedExecutionContext);
322+
trustedExecutionContext, executionGuard);
284323
}
285324

286325
}
Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
/*
2+
* Copyright 2024-2026 the original author or authors.
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* https://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
package io.github.agentic.ai.agent.retry;
17+
18+
import java.util.Objects;
19+
import java.util.Set;
20+
21+
/**
22+
* A classified model call failure.
23+
*
24+
* @param category the classification of the failure
25+
* @param cause the original failure, may be {@code null} when the failure was not
26+
* classified from a throwable
27+
*/
28+
public record ModelCallFailure(ModelCallFailureCategory category, Throwable cause) {
29+
30+
public ModelCallFailure {
31+
Objects.requireNonNull(category, "category must not be null");
32+
}
33+
34+
/**
35+
* Whether the failure may be retried under the given policy.
36+
* @param retryableCategories the categories the policy allows to retry
37+
* @return {@code true} when the category is retryable
38+
*/
39+
public boolean isRetryable(Set<ModelCallFailureCategory> retryableCategories) {
40+
return retryableCategories.contains(category);
41+
}
42+
43+
}
Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
/*
2+
* Copyright 2024-2026 the original author or authors.
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* https://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
package io.github.agentic.ai.agent.retry;
17+
18+
/**
19+
* Classification of a failed model call.
20+
*
21+
* <p>
22+
* The category is derived from the failure itself, never from the text of an
23+
* exception message: a permanent rejection that happens to mention a timeout must not
24+
* be retried.
25+
*/
26+
public enum ModelCallFailureCategory {
27+
28+
/** A temporary failure that a later attempt may still overcome. */
29+
TRANSIENT,
30+
31+
/** The provider asked the caller to slow down. */
32+
RATE_LIMITED,
33+
34+
/** The request itself was rejected; another attempt cannot change the outcome. */
35+
PERMANENT,
36+
37+
/** The call was cancelled or interrupted and must never be retried. */
38+
CANCELLED,
39+
40+
/** The failure could not be classified and is therefore not retried by default. */
41+
UNKNOWN;
42+
43+
/**
44+
* Whether this category is retryable without further configuration.
45+
* @return {@code true} for {@link #TRANSIENT} and {@link #RATE_LIMITED}
46+
*/
47+
public boolean isRetryableByDefault() {
48+
return this == TRANSIENT || this == RATE_LIMITED;
49+
}
50+
51+
}

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

Lines changed: 17 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -13,23 +13,24 @@
1313
* See the License for the specific language governing permissions and
1414
* limitations under the License.
1515
*/
16-
package io.github.agentic.ai.agent.orchestration.interceptor.modelretry;
16+
package io.github.agentic.ai.agent.retry;
1717

18-
import org.junit.jupiter.api.Test;
19-
20-
import static org.junit.jupiter.api.Assertions.assertEquals;
21-
22-
class RetryDelayCalculatorTest {
23-
24-
@Test
25-
void exponentialDelayIsCappedWithoutReadingTheClock() {
26-
assertEquals(150, RetryDelayCalculator.nextDelay(100, 3.0, 150));
27-
assertEquals(150, RetryDelayCalculator.nextDelay(150, 3.0, 150));
28-
}
18+
/**
19+
* Classifies a failed model call into a {@link ModelCallFailureCategory}.
20+
*
21+
* <p>
22+
* Implementations must classify from the failure type and its cause chain. Matching
23+
* on the text of an exception message is not a classification: the same message can
24+
* describe a permanent rejection or a transient outage.
25+
*/
26+
@FunctionalInterface
27+
public interface ModelCallFailureClassifier {
2928

30-
@Test
31-
void zeroDelayRemainsZero() {
32-
assertEquals(0, RetryDelayCalculator.nextDelay(0, 2.0, 30_000));
33-
}
29+
/**
30+
* Classifies a failure.
31+
* @param failure the failure raised by the model call
32+
* @return the classified failure, never {@code null}
33+
*/
34+
ModelCallFailure classify(Throwable failure);
3435

3536
}

0 commit comments

Comments
 (0)