Skip to content

Commit b39901a

Browse files
authored
Merge pull request #356 from konlue/feat/issue313-controlled-model-retry
feat(agent): control model retry attempts with a deadline-aware policy (issue #313)
2 parents 3f2ff6b + fbc7670 commit b39901a

18 files changed

Lines changed: 1827 additions & 76 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)