This is an automated email from the ASF dual-hosted git repository.
davsclaus pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel.git
The following commit(s) were added to refs/heads/main by this push:
new 7a04a64f6917 CAMEL-27152: camel-ai-tool - a tool call in flight
completes when its route stops (#30327)
7a04a64f6917 is described below
commit 7a04a64f6917e637bde45dd55265727d3ba03e5a
Author: Serdar Gökay <[email protected]>
AuthorDate: Wed Nov 18 12:33:22 2026 +0300
CAMEL-27152: camel-ai-tool - a tool call in flight completes when its route
stops (#30327)
A consumer that is neither Suspendable nor ShutdownAware is stopped at once
by
DefaultShutdownStrategy, and DefaultConsumer.doStop stops the route
processor. A tool call
still inside the route then failed at its next step, while the strategy
waited for it.
AiToolConsumer is now Suspendable: a route stop or graceful shutdown
suspends it first, which
deregisters the tool, and stops it once the calls in flight have completed.
Its doSuspend and
doResume become reachable, so suspendRoute suspends the route instead of
stopping it.
AiToolExecutor refuses a new call to a suspended tool, as request/reply
consumers do.
Co-Authored-By: Claude Fable 5.2 <[email protected]>
---
components/camel-ai/camel-ai-tool/pom.xml | 6 ++
.../camel/component/ai/tool/AiToolConsumer.java | 8 +-
.../camel/component/ai/tool/AiToolExecutor.java | 8 ++
.../component/ai/tool/AiToolExecutorTest.java | 27 ++++++
.../ai/tool/AiToolRouteStopInFlightTest.java | 96 ++++++++++++++++++++++
.../ROOT/pages/camel-4x-upgrade-guide-4_24.adoc | 7 ++
6 files changed, 151 insertions(+), 1 deletion(-)
diff --git a/components/camel-ai/camel-ai-tool/pom.xml
b/components/camel-ai/camel-ai-tool/pom.xml
index fefef6655c9e..7821e0522d96 100644
--- a/components/camel-ai/camel-ai-tool/pom.xml
+++ b/components/camel-ai/camel-ai-tool/pom.xml
@@ -66,6 +66,12 @@
<artifactId>assertj-core</artifactId>
<scope>test</scope>
</dependency>
+ <dependency>
+ <groupId>org.awaitility</groupId>
+ <artifactId>awaitility</artifactId>
+ <version>${awaitility-version}</version>
+ <scope>test</scope>
+ </dependency>
</dependencies>
</project>
diff --git
a/components/camel-ai/camel-ai-tool/src/main/java/org/apache/camel/component/ai/tool/AiToolConsumer.java
b/components/camel-ai/camel-ai-tool/src/main/java/org/apache/camel/component/ai/tool/AiToolConsumer.java
index c07d7fe68f59..e79562314182 100644
---
a/components/camel-ai/camel-ai-tool/src/main/java/org/apache/camel/component/ai/tool/AiToolConsumer.java
+++
b/components/camel-ai/camel-ai-tool/src/main/java/org/apache/camel/component/ai/tool/AiToolConsumer.java
@@ -20,6 +20,7 @@ import java.util.Map;
import org.apache.camel.CamelAuthorizationException;
import org.apache.camel.Processor;
+import org.apache.camel.Suspendable;
import org.apache.camel.spi.AuthorizationPolicy;
import org.apache.camel.support.CamelContextHelper;
import org.apache.camel.support.DefaultConsumer;
@@ -29,10 +30,15 @@ import org.slf4j.LoggerFactory;
/**
* Consumer that registers a Camel route as an AI tool in the {@link
AiToolRegistry} on start and deregisters on stop.
+ * <p>
+ * It is {@link Suspendable}, so a route stop or graceful shutdown suspends it
first, which deregisters the tool, and
+ * stops it once the tool calls in flight have completed or the shutdown
timeout has elapsed. Suspending the route
+ * deregisters the tool without stopping the route, and resuming it registers
the same tool spec again. A suspended tool
+ * refuses new calls.
*
* @since 4.22
*/
-public class AiToolConsumer extends DefaultConsumer {
+public class AiToolConsumer extends DefaultConsumer implements Suspendable {
private static final Logger LOG =
LoggerFactory.getLogger(AiToolConsumer.class);
diff --git
a/components/camel-ai/camel-ai-tool/src/main/java/org/apache/camel/component/ai/tool/AiToolExecutor.java
b/components/camel-ai/camel-ai-tool/src/main/java/org/apache/camel/component/ai/tool/AiToolExecutor.java
index 5ec1beab00d8..b1570bfe073e 100644
---
a/components/camel-ai/camel-ai-tool/src/main/java/org/apache/camel/component/ai/tool/AiToolExecutor.java
+++
b/components/camel-ai/camel-ai-tool/src/main/java/org/apache/camel/component/ai/tool/AiToolExecutor.java
@@ -174,6 +174,14 @@ public final class AiToolExecutor {
return new AiToolResult.ExecutionError(cause.getMessage(), cause);
}
+ // A suspended tool (suspended route, graceful shutdown) refuses new
calls, as request/reply consumers do while
+ // suspended; a caller may still hold its spec from before the
suspend. Calls in flight are past this point.
+ if (consumer.isSuspendingOrSuspended()) {
+ IllegalStateException cause = new IllegalStateException(
+ String.format("Tool '%s' is suspended", toolName));
+ return new AiToolResult.ExecutionError(cause.getMessage(), cause);
+ }
+
// Use the authorization-guarded processor when the consumer applied
an AuthorizationPolicy, so the guard runs
// before the route body; falls back to the plain route processor
otherwise.
Processor routeProcessor = consumer instanceof AiToolConsumer atc ?
atc.getToolProcessor() : consumer.getProcessor();
diff --git
a/components/camel-ai/camel-ai-tool/src/test/java/org/apache/camel/component/ai/tool/AiToolExecutorTest.java
b/components/camel-ai/camel-ai-tool/src/test/java/org/apache/camel/component/ai/tool/AiToolExecutorTest.java
index 2985db156dbe..c545b59d5337 100644
---
a/components/camel-ai/camel-ai-tool/src/test/java/org/apache/camel/component/ai/tool/AiToolExecutorTest.java
+++
b/components/camel-ai/camel-ai-tool/src/test/java/org/apache/camel/component/ai/tool/AiToolExecutorTest.java
@@ -118,6 +118,12 @@ public class AiToolExecutorTest extends CamelTestSupport {
+ "&description=Returns null body with output schema"
+
"&outputSchema=classpath:output-schemas/weather-result.json")
.setBody(constant((Object) null));
+
+ from("ai-tool:suspendableTool"
+ + "?tags=test"
+ + "&description=A tool whose route is suspended and
resumed")
+ .routeId("suspendableTool")
+ .setBody(constant("suspendable result"));
}
};
}
@@ -279,6 +285,27 @@ public class AiToolExecutorTest extends CamelTestSupport {
assertThat(error.cause()).isInstanceOf(IllegalStateException.class);
}
+ @Test
+ void testExecuteReturnsExecutionErrorForSuspendedTool() throws Exception {
+ // a caller can hold a spec it obtained before the route was suspended
+ AiToolSpec spec = findSpec("suspendableTool");
+ context.getRouteController().suspendRoute("suspendableTool");
+
+ AiToolResult refused = AiToolExecutor.execute(spec, null, new
DefaultExchange(context));
+
+ assertThat(refused).isInstanceOf(AiToolResult.ExecutionError.class);
+ AiToolResult.ExecutionError error = (AiToolResult.ExecutionError)
refused;
+ assertThat(error.message()).isEqualTo("Tool 'suspendableTool' is
suspended");
+ assertThat(error.cause()).isInstanceOf(IllegalStateException.class);
+
+ context.getRouteController().resumeRoute("suspendableTool");
+
+ assertThat(findSpec("suspendableTool")).isSameAs(spec);
+ AiToolResult result = AiToolExecutor.execute(spec, null, new
DefaultExchange(context));
+ assertThat(result).isInstanceOf(AiToolResult.Success.class);
+ assertThat(((AiToolResult.Success)
result).value()).isEqualTo("suspendable result");
+ }
+
@Test
public void testExecuteReturnsNoResultForNullBody() {
AiToolSpec spec = findSpec("nullBodyTool");
diff --git
a/components/camel-ai/camel-ai-tool/src/test/java/org/apache/camel/component/ai/tool/AiToolRouteStopInFlightTest.java
b/components/camel-ai/camel-ai-tool/src/test/java/org/apache/camel/component/ai/tool/AiToolRouteStopInFlightTest.java
new file mode 100644
index 000000000000..a612645e8b13
--- /dev/null
+++
b/components/camel-ai/camel-ai-tool/src/test/java/org/apache/camel/component/ai/tool/AiToolRouteStopInFlightTest.java
@@ -0,0 +1,96 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You 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
+ *
+ * http://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 org.apache.camel.component.ai.tool;
+
+import java.util.Map;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.Future;
+import java.util.concurrent.TimeUnit;
+
+import org.apache.camel.ServiceStatus;
+import org.apache.camel.builder.RouteBuilder;
+import org.apache.camel.support.DefaultExchange;
+import org.apache.camel.test.junit6.CamelTestSupport;
+import org.junit.jupiter.api.Test;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.awaitility.Awaitility.await;
+
+/**
+ * A tool call that is in flight inside an {@code ai-tool} route when the
route is stopped completes: the shutdown
+ * strategy suspends the consumer, which deregisters the tool, waits for the
call, and then stops the route.
+ */
+class AiToolRouteStopInFlightTest extends CamelTestSupport {
+
+ private final CountDownLatch entered = new CountDownLatch(1);
+ private final CountDownLatch release = new CountDownLatch(1);
+
+ @Override
+ protected RouteBuilder createRouteBuilder() {
+ return new RouteBuilder() {
+ public void configure() {
+ from("ai-tool:held?tags=test&description=Held inside the
route").routeId("held")
+ .process(exchange -> {
+ entered.countDown();
+ if (!release.await(10, TimeUnit.SECONDS)) {
+ throw new IllegalStateException("The call was
not released");
+ }
+ })
+ .setBody(constant("ok"));
+ }
+ };
+ }
+
+ @Test
+ void aCallHeldInsideTheRouteCompletesWhenTheRouteStops() throws Exception {
+ AiToolSpec spec = findSpec("held");
+ ExecutorService executor = Executors.newFixedThreadPool(2);
+ try {
+ Future<AiToolResult> call
+ = executor.submit(() -> AiToolExecutor.execute(spec,
Map.of(), new DefaultExchange(context)));
+ assertThat(entered.await(10, TimeUnit.SECONDS)).isTrue();
+
+ Future<?> stop = executor.submit(() -> {
+ context.getRouteController().stopRoute("held");
+ return null;
+ });
+ // the shutdown strategy has suspended the consumer and now waits
for the call
+ await().atMost(10, TimeUnit.SECONDS).until(() ->
spec.getConsumer().isSuspended());
+
assertThat(AiToolRegistry.getOrCreate(context).getToolsByTag("test"))
+ .extracting(AiToolSpec::getName)
+ .doesNotContain("held");
+ release.countDown();
+
+ AiToolResult result = call.get(10, TimeUnit.SECONDS);
+ assertThat(result).isInstanceOf(AiToolResult.Success.class);
+ assertThat(((AiToolResult.Success)
result).value()).isEqualTo("ok");
+ stop.get(10, TimeUnit.SECONDS);
+
assertThat(context.getRouteController().getRouteStatus("held")).isEqualTo(ServiceStatus.Stopped);
+ } finally {
+ executor.shutdownNow();
+ }
+ }
+
+ private AiToolSpec findSpec(String toolName) {
+ return
AiToolRegistry.getOrCreate(context).getToolsByTag("test").stream()
+ .filter(s -> toolName.equals(s.getName()))
+ .findFirst()
+ .orElseThrow(() -> new AssertionError("Tool not found: " +
toolName));
+ }
+}
diff --git
a/docs/user-manual/modules/ROOT/pages/camel-4x-upgrade-guide-4_24.adoc
b/docs/user-manual/modules/ROOT/pages/camel-4x-upgrade-guide-4_24.adoc
index 010e3ece31ce..65ad6612138c 100644
--- a/docs/user-manual/modules/ROOT/pages/camel-4x-upgrade-guide-4_24.adoc
+++ b/docs/user-manual/modules/ROOT/pages/camel-4x-upgrade-guide-4_24.adoc
@@ -387,6 +387,13 @@ now reject the invocation before the tool route runs.
Previously, these argument
required-argument check and then be discarded by the reserved-name filter,
leaving the route without
a required value. Rename these parameters and update their `parameter.*` or
`argSchema` declarations.
+=== camel-ai-tool - suspending a route no longer stops it, and tool calls in
flight complete when the route stops
+
+Suspending an `ai-tool` route, with `suspendRoute` or `context.suspend()`, now
suspends the route instead of stopping
+it: the tool is deregistered, tool calls in flight complete, a new call to the
suspended tool is refused, and resuming
+the route registers the tool again. When an `ai-tool` route is stopped, or
Camel shuts down gracefully, tool calls in
+flight now complete instead of failing.
+
=== camel-wordpress - each endpoint uses its own site URL and credentials
Each WordPress endpoint now has a client of its own, set up from the `url`,
`apiVersion`, `user` and `password`