Skip to content

Commit 119bcb0

Browse files
committed
feat(plugins): port ReflectAndRetryToolPlugin from adk-python
1 parent 1929be7 commit 119bcb0

7 files changed

Lines changed: 967 additions & 0 deletions

File tree

Lines changed: 215 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,215 @@
1+
/*
2+
* Copyright 2026 Google LLC
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+
* http://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+
17+
package com.google.adk.plugins.reflectandretry;
18+
19+
import static com.google.common.base.Preconditions.checkArgument;
20+
import static com.google.common.base.Preconditions.checkNotNull;
21+
22+
import com.google.adk.plugins.BasePlugin;
23+
import com.google.adk.tools.BaseTool;
24+
import com.google.adk.tools.ToolContext;
25+
import com.google.common.base.Strings;
26+
import com.google.common.collect.ImmutableMap;
27+
import io.reactivex.rxjava3.core.Maybe;
28+
import java.util.Map;
29+
30+
/**
31+
* Provides self-healing error recovery for tool failures.
32+
*
33+
* <p>This plugin intercepts tool failures, hands the model structured guidance for reflection and
34+
* correction, and lets it retry up to a configurable limit. Failure counts are tracked per tool
35+
* within a scope, so a success with one tool resets that tool's counter without forgiving
36+
* another's.
37+
*
38+
* <p>Port of adk-python's {@code ReflectAndRetryToolPlugin} ({@code
39+
* plugins/reflect_retry_tool_plugin.py}).
40+
*
41+
* <p>Example:
42+
*
43+
* <pre>{@code
44+
* Runner runner =
45+
* new Runner(
46+
* agent,
47+
* APP_NAME,
48+
* artifactService,
49+
* sessionService,
50+
* ImmutableList.of(new ReflectAndRetryToolPlugin(3)));
51+
* }</pre>
52+
*
53+
* <p>{@link #scopeKey} and {@link #extractErrorFromResult} are {@code protected} because adk-python
54+
* documents both as overridable.
55+
*/
56+
public class ReflectAndRetryToolPlugin extends BasePlugin {
57+
58+
private static final String DEFAULT_NAME = "reflect_retry_tool_plugin";
59+
private static final int DEFAULT_MAX_RETRIES = 3;
60+
private static final String GLOBAL_SCOPE_KEY = "__global_reflect_and_retry_scope__";
61+
private static final String NEGATIVE_RETRIES = "maxRetries must be non-negative, but was %s";
62+
63+
/** The observed failure count when retrying is disabled: the one failure being reported. */
64+
private static final int FIRST_FAILURE = 1;
65+
66+
private final int maxRetries;
67+
private final boolean throwExceptionIfRetryExceeded;
68+
private final TrackingScope trackingScope;
69+
private final ToolFailureTracker failures = new ToolFailureTracker();
70+
71+
/** Three retries, throwing when exceeded, tracked per invocation. */
72+
public ReflectAndRetryToolPlugin() {
73+
this(DEFAULT_NAME, DEFAULT_MAX_RETRIES, true, TrackingScope.INVOCATION);
74+
}
75+
76+
/** As above, with a custom retry limit. */
77+
public ReflectAndRetryToolPlugin(int maxRetries) {
78+
this(DEFAULT_NAME, maxRetries, true, TrackingScope.INVOCATION);
79+
}
80+
81+
/**
82+
* @param name plugin instance identifier
83+
* @param maxRetries maximum consecutive failures before giving up; {@code 0} disables retrying
84+
* @param throwExceptionIfRetryExceeded whether to propagate the final error once the limit is
85+
* reached, rather than returning guidance
86+
* @param trackingScope lifetime of the failure counters
87+
* @throws IllegalArgumentException if {@code maxRetries} is negative
88+
* @throws NullPointerException if {@code trackingScope} is null
89+
*/
90+
public ReflectAndRetryToolPlugin(
91+
String name,
92+
int maxRetries,
93+
boolean throwExceptionIfRetryExceeded,
94+
TrackingScope trackingScope) {
95+
super(name);
96+
checkArgument(maxRetries >= 0, NEGATIVE_RETRIES, maxRetries);
97+
this.maxRetries = maxRetries;
98+
this.throwExceptionIfRetryExceeded = throwExceptionIfRetryExceeded;
99+
this.trackingScope = checkNotNull(trackingScope, "trackingScope cannot be null");
100+
}
101+
102+
/**
103+
* Resets the tool's failure count on success, or routes an error carried inside an otherwise
104+
* successful result into the retry logic.
105+
*
106+
* <p>A result this plugin produced earlier is passed straight through: reflecting on a reflection
107+
* would count a single tool failure twice.
108+
*/
109+
@Override
110+
public Maybe<Map<String, Object>> afterToolCallback(
111+
BaseTool tool,
112+
Map<String, Object> toolArgs,
113+
ToolContext toolContext,
114+
Map<String, Object> result) {
115+
if (ToolFailureResponse.isReflection(result)) {
116+
return Maybe.empty();
117+
}
118+
return extractErrorFromResult(tool, toolArgs, toolContext, result)
119+
.flatMap(error -> handleToolError(tool, toolArgs, toolContext, error))
120+
.switchIfEmpty(Maybe.fromRunnable(() -> resetFailures(tool, toolContext)));
121+
}
122+
123+
/** Turns a thrown tool error into reflection guidance for the model. */
124+
@Override
125+
public Maybe<Map<String, Object>> onToolErrorCallback(
126+
BaseTool tool, Map<String, Object> toolArgs, ToolContext toolContext, Throwable error) {
127+
return handleToolError(tool, toolArgs, toolContext, error);
128+
}
129+
130+
/**
131+
* Detects an error inside a tool result that did <em>not</em> throw — for example {@code
132+
* {"status": "error"}} — so it can drive the same retry logic.
133+
*
134+
* <p>Empty by default, exactly as in adk-python. Override to opt in.
135+
*/
136+
protected Maybe<Throwable> extractErrorFromResult(
137+
BaseTool tool,
138+
Map<String, Object> toolArgs,
139+
ToolContext toolContext,
140+
Map<String, Object> result) {
141+
return Maybe.empty();
142+
}
143+
144+
/**
145+
* The key failure counts are grouped under. Override to track per user or per session instead of
146+
* the configured {@link TrackingScope}.
147+
*/
148+
protected String scopeKey(ToolContext toolContext) {
149+
return switch (trackingScope) {
150+
case INVOCATION -> toolContext.invocationId();
151+
case GLOBAL -> GLOBAL_SCOPE_KEY;
152+
};
153+
}
154+
155+
/**
156+
* Counts the failure and decides between guidance, a final message, or propagating the error.
157+
*
158+
* <p>Never completes empty. {@link #afterToolCallback} treats an empty result as "the tool
159+
* succeeded" and resets the counter, so an empty return here would clear the count of the very
160+
* call that just failed.
161+
*/
162+
private Maybe<Map<String, Object>> handleToolError(
163+
BaseTool tool, Map<String, Object> toolArgs, ToolContext toolContext, Throwable error) {
164+
if (maxRetries == 0) {
165+
return exhausted(tool, toolArgs, error, FIRST_FAILURE);
166+
}
167+
int attempt = failures.recordFailure(scopeKey(toolContext), tool.name());
168+
if (attempt <= maxRetries) {
169+
return Maybe.just(reflection(tool, toolArgs, error, attempt));
170+
}
171+
return exhausted(tool, toolArgs, error, attempt);
172+
}
173+
174+
/**
175+
* Either propagates the final error or hands back the give-up message, per configuration.
176+
*
177+
* <p>{@code failures} is the number of consecutive failures actually observed, which is what both
178+
* the give-up message and the response's {@code retry_count} report. Retrying is disabled at
179+
* {@code maxRetries == 0}, where nothing is counted at all — upstream returns before its counter
180+
* runs ({@code reflect_retry_tool_plugin.py:243-246}) and so does this — so the observed count
181+
* there is the one failure being reported.
182+
*/
183+
private Maybe<Map<String, Object>> exhausted(
184+
BaseTool tool, Map<String, Object> toolArgs, Throwable error, int failures) {
185+
return throwExceptionIfRetryExceeded
186+
? Maybe.error(error)
187+
: Maybe.just(retryExceeded(tool, toolArgs, error, failures));
188+
}
189+
190+
private void resetFailures(BaseTool tool, ToolContext toolContext) {
191+
failures.reset(scopeKey(toolContext), tool.name());
192+
}
193+
194+
private ImmutableMap<String, Object> reflection(
195+
BaseTool tool, Map<String, Object> toolArgs, Throwable error, int attempt) {
196+
return response(
197+
error, attempt, ReflectionGuidance.forRetry(tool, toolArgs, error, attempt, maxRetries));
198+
}
199+
200+
private ImmutableMap<String, Object> retryExceeded(
201+
BaseTool tool, Map<String, Object> toolArgs, Throwable error, int failures) {
202+
return response(
203+
error, failures, ReflectionGuidance.forExhausted(tool, toolArgs, error, failures));
204+
}
205+
206+
private static ImmutableMap<String, Object> response(
207+
Throwable error, int retryCount, String guidance) {
208+
return new ToolFailureResponse(
209+
error.getClass().getSimpleName(),
210+
Strings.nullToEmpty(error.getMessage()),
211+
retryCount,
212+
guidance)
213+
.toMap();
214+
}
215+
}
Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
/*
2+
* Copyright 2026 Google LLC
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+
* http://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+
17+
package com.google.adk.plugins.reflectandretry;
18+
19+
import com.fasterxml.jackson.core.JsonProcessingException;
20+
import com.google.adk.JsonBaseModel;
21+
import com.google.adk.tools.BaseTool;
22+
import com.google.common.base.Strings;
23+
import java.util.Map;
24+
25+
/**
26+
* The text {@link ReflectAndRetryToolPlugin} sends the model after a tool fails.
27+
*
28+
* <p>Kept apart from the plugin so that one class decides <em>whether</em> to retry and this one
29+
* decides only <em>what the model is told</em>. Both messages are ports of the f-strings in
30+
* adk-python's {@code reflect_retry_tool_plugin.py} and are reproduced verbatim.
31+
*/
32+
final class ReflectionGuidance {
33+
34+
private static final String ERROR_DETAILS_FORMAT = "%s: %s";
35+
36+
private static final String RETRY =
37+
"""
38+
The call to tool `%s` failed.
39+
40+
**Error Details:**
41+
```
42+
%s
43+
```
44+
45+
**Tool Arguments Used:**
46+
```json
47+
%s
48+
```
49+
50+
**Reflection Guidance:**
51+
This is retry attempt **%d of %d**. Analyze the error and the arguments you provided. Do not \
52+
repeat the exact same call. Consider the following before your next attempt:
53+
54+
1. **Invalid Parameters**: Does the error suggest that one or more arguments are incorrect, \
55+
badly formatted, or missing? Review the tool's schema and your arguments.
56+
2. **State or Preconditions**: Did a previous step fail or not produce the necessary \
57+
state/resource for this tool to succeed?
58+
3. **Alternative Approach**: Is this the right tool for the job? Could another tool or a \
59+
different sequence of steps achieve the goal?
60+
4. **Simplify the Task**: Can you break the problem down into smaller, simpler steps?
61+
5. **Wrong Function Name**: Does the error indicates the tool is not found? Please check \
62+
again and only use available tools.
63+
64+
Formulate a new plan based on your analysis and try a corrected or different approach.""";
65+
66+
private static final String EXHAUSTED =
67+
"""
68+
The tool `%s` has failed consecutively %d times and the retry limit has been exceeded.
69+
70+
**Last Error:**
71+
```
72+
%s
73+
```
74+
75+
**Last Arguments Used:**
76+
```json
77+
%s
78+
```
79+
80+
**Final Instruction:**
81+
**Do not attempt to use the `%s` tool again for this task.** You must now try a different \
82+
approach. Acknowledge the failure and devise a new strategy, potentially using other \
83+
available tools or informing the user that the task cannot be completed.""";
84+
85+
private ReflectionGuidance() {}
86+
87+
/** Asks the model to analyze the failure and try a corrected call. */
88+
static String forRetry(
89+
BaseTool tool, Map<String, Object> toolArgs, Throwable error, int attempt, int maxRetries) {
90+
return RETRY.formatted(
91+
tool.name(), errorDetails(error), argsAsJson(toolArgs), attempt, maxRetries);
92+
}
93+
94+
/**
95+
* Tells the model to stop calling the tool and change approach.
96+
*
97+
* <p>{@code failures} is the number of consecutive failures observed. adk-python interpolates its
98+
* configured {@code max_retries} here instead ({@code reflect_retry_tool_plugin.py:357}), which
99+
* under-reports by one at every setting because the give-up fires on the failure *after* the
100+
* limit — and at {@code max_retries=0} tells the model the tool "has failed consecutively 0 times
101+
* and the retry limit has been exceeded". This port reports what actually happened.
102+
*/
103+
static String forExhausted(
104+
BaseTool tool, Map<String, Object> toolArgs, Throwable error, int failures) {
105+
return EXHAUSTED.formatted(
106+
tool.name(), failures, errorDetails(error), argsAsJson(toolArgs), tool.name());
107+
}
108+
109+
private static String errorDetails(Throwable error) {
110+
return ERROR_DETAILS_FORMAT.formatted(
111+
error.getClass().getSimpleName(), Strings.nullToEmpty(error.getMessage()));
112+
}
113+
114+
/**
115+
* Pretty-prints the arguments for the guidance message, falling back to the map's own rendering.
116+
*
117+
* <p>Never throws: a serialization failure must not mask the tool failure being reported, and the
118+
* model still needs the echo of the arguments it sent. Mirrors adk-python's {@code
119+
* json.dumps(..., default=str)}.
120+
*/
121+
private static String argsAsJson(Map<String, Object> toolArgs) {
122+
try {
123+
return JsonBaseModel.getMapper()
124+
.writerWithDefaultPrettyPrinter()
125+
.writeValueAsString(toolArgs);
126+
} catch (JsonProcessingException e) {
127+
return String.valueOf(toolArgs);
128+
}
129+
}
130+
}

0 commit comments

Comments
 (0)