Added annotations for retry for qos provider, and also properties, with nested for action names gh-1221

Signed-off-by: hayden.rear <[email protected]>

Author: haydenrear

embabel-agent-api/src/main/kotlin/com/embabel/agent/api/annotation/annotations.kt

@@ -17,6 +17,7 @@ package com.embabel.agent.api.annotation
 
 import com.embabel.agent.api.common.PlannerType
 import com.embabel.agent.core.IoBinding
+import com.embabel.agent.core.Retry
 import com.embabel.common.core.types.Semver.Companion.DEFAULT_VERSION
 import com.embabel.common.core.types.ZeroToOne
 import org.springframework.core.annotation.AliasFor
@@ -181,6 +182,7 @@ annotation class Action(
     val toolGroups: Array<String> = [],
     val toolGroupRequirements: Array<ToolGroup> = [],
     val trigger: KClass<*> = Unit::class,
+    val retry: Array<Retry> = []
 )
 
 /**

embabel-agent-api/src/main/kotlin/com/embabel/agent/api/annotation/support/ActionMethodManager.kt

@@ -44,6 +44,8 @@ interface ActionMethodManager {
      */
     val argumentResolvers: List<ActionMethodArgumentResolver>
 
+    val actionQosProvider: ActionQosProvider
+
     /**
      * Create an Action from a method
      * @param method the method to create an action from

embabel-agent-api/src/main/kotlin/com/embabel/agent/api/annotation/support/DefaultActionMethodManager.kt

@@ -48,7 +48,7 @@ import kotlin.reflect.jvm.kotlinFunction
 @Component
 internal class DefaultActionMethodManager(
     val nameGenerator: MethodDefinedOperationNameGenerator = MethodDefinedOperationNameGenerator(),
-    val actionQosProvider: ActionQosProvider = DefaultActionQosProvider(),
+    override val actionQosProvider: ActionQosProvider = DefaultActionQosProvider(),
     override val argumentResolvers: List<ActionMethodArgumentResolver> = listOf(
         ProcessContextArgumentResolver(),
         OperationContextArgumentResolver(),

embabel-agent-api/src/main/kotlin/com/embabel/agent/api/annotation/support/DefaultActionQosProvider.kt

@@ -15,14 +15,44 @@
  */
 package com.embabel.agent.api.annotation.support
 
+import com.embabel.agent.api.annotation.Action
+import com.embabel.agent.api.annotation.Agent
 import com.embabel.agent.core.ActionQos
+import com.embabel.agent.spi.config.spring.AgentPlatformProperties
+import org.springframework.stereotype.Component
 import java.lang.reflect.Method
 
-class DefaultActionQosProvider : ActionQosProvider {
+@Component
+class DefaultActionQosProvider(
+    val perActionQosProperties: AgentPlatformProperties.ActionQosProperties = AgentPlatformProperties.ActionQosProperties()
+) : ActionQosProvider {
+
     override fun provideActionQos(
         method: Method,
         instance: Any
     ): ActionQos {
-        return ActionQos()
+
+        val defaultActionQos = perActionQosProperties.default.toActionQos()
+
+        val props = instance.javaClass.getAnnotation(Agent::class.java)?.let {
+            perActionQosProperties.agents[it.name]?.get(method.name)?.toActionQos(defaultActionQos)
+                ?: perActionQosProperties.default.toActionQos(defaultActionQos)
+        } ?: perActionQosProperties.default.toActionQos(defaultActionQos)
+
+        if (method.isAnnotationPresent(Action::class.java)
+            && method.getAnnotation(Action::class.java).retry.isNotEmpty()) {
+            return method.getAnnotation(Action::class.java).retry.first()
+                .let { retryAction ->
+                    ActionQos(
+                        retryAction.maxAttempts.firstOrNull() ?: props.maxAttempts,
+                        retryAction.backoffMillis.firstOrNull() ?: props.backoffMillis,
+                        retryAction.backoffMultiplier.firstOrNull() ?: props.backoffMultiplier,
+                        retryAction.backoffMaxInterval.firstOrNull() ?: props.backoffMaxInterval,
+                        retryAction.idempotent.firstOrNull() ?: props.idempotent
+                    )
+                }
+        }
+
+        return props
     }
 }

embabel-agent-api/src/main/kotlin/com/embabel/agent/core/Retry.kt

@@ -0,0 +1,27 @@
+/*
+ * Copyright 2024-2025 Embabel Software, Inc.
+ *
+ * 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
+ *
+ * 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 com.embabel.agent.core
+
+/**
+ * Used as the first priority in overriding retry behavior for a particular method Action.
+ */
+annotation class Retry(
+    val maxAttempts: IntArray = [],
+    val backoffMillis: LongArray = [],
+    val backoffMultiplier: DoubleArray = [],
+    val backoffMaxInterval: LongArray = [],
+    val idempotent: BooleanArray = [],
+)

embabel-agent-api/src/main/kotlin/com/embabel/agent/spi/config/spring/AgentPlatformProperties.kt

@@ -15,6 +15,7 @@
  */
 package com.embabel.agent.spi.config.spring
 
+import com.embabel.agent.core.ActionQos
 import org.springframework.boot.context.properties.ConfigurationProperties
 import org.springframework.boot.context.properties.NestedConfigurationProperty
 
@@ -67,6 +68,9 @@ class AgentPlatformProperties {
     @field:NestedConfigurationProperty
     var test: TestConfig = TestConfig()
 
+    @field:NestedConfigurationProperty
+    var actionQos: ActionQosProperties = ActionQosProperties()
+
     /**
      * Agent Process Type
      */
@@ -282,4 +286,40 @@ class AgentPlatformProperties {
          */
         var mockMode: Boolean = true
     }
+
+    /**
+     * Configuration of retry by @Action
+     */
+    @ConfigurationProperties(prefix = "embabel.agent.platform.action-qos")
+    class ActionQosProperties {
+
+        data class ActionProperties(
+            var maxAttempts: Int? = null,
+            var backoffMillis: Long? = null,
+            var backoffMultiplier: Double? = null,
+            var backoffMaxInterval: Long? = null,
+            var idempotent: Boolean? = null,
+        ) {
+            fun toActionQos(defaultAction : ActionQos = ActionQos()): ActionQos {
+                return ActionQos(
+                    maxAttempts = maxAttempts ?: defaultAction.maxAttempts,
+                    backoffMillis = backoffMillis ?: defaultAction.backoffMillis,
+                    backoffMultiplier = backoffMultiplier ?: defaultAction.backoffMultiplier,
+                    backoffMaxInterval = backoffMaxInterval ?: defaultAction.backoffMaxInterval,
+                    idempotent = idempotent ?: defaultAction.idempotent
+                )
+            }
+        }
+
+        /**
+         * Fallback retry properties for @Action
+         */
+        var default: ActionProperties = ActionProperties()
+
+        /**
+         * Retry properties keyed by agent name and then @Action method name
+         */
+        var agents: Map<String, Map<String, ActionProperties>> = LinkedHashMap()
+
+    }
 }

embabel-agent-api/src/test/java/com/embabel/agent/api/annotation/support/RetryActionAnnotationJavaTest.java

@@ -0,0 +1,135 @@
+/*
+ * Copyright 2024-2025 Embabel Software, Inc.
+ *
+ * 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
+ *
+ * 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 com.embabel.agent.api.annotation.support;
+
+import com.embabel.agent.api.annotation.AchievesGoal;
+import com.embabel.agent.api.annotation.Action;
+import com.embabel.agent.api.annotation.Agent;
+import com.embabel.agent.api.common.PlannerType;
+import com.embabel.agent.core.ProcessOptions;
+import com.embabel.agent.core.Retry;
+import com.embabel.agent.test.integration.IntegrationTestUtils;
+import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.Test;
+
+import java.util.Map;
+import java.util.concurrent.atomic.AtomicInteger;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+/**
+ * Java tests for @Retry annotation.
+ */
+class RetryAnnotationJavaTest {
+
+    @Test
+    void retryMethodFailsOnlyOnceSucceedsSecond() {
+        var reader = new AgentMetadataReader();
+        var instance = new JavaAgentWithTwoRetryActions();
+        var metadata = reader.createAgentMetadata(instance);
+
+        assertNotNull(metadata);
+        var agent = (com.embabel.agent.core.Agent) metadata;
+
+        var ap = IntegrationTestUtils.dummyAgentPlatform();
+        var agentProcess = ap.createAgentProcess(
+                agent,
+                ProcessOptions.DEFAULT.withPlannerType(PlannerType.UTILITY),
+                Map.of(
+                        "input", new JavaRetryTestInput("test")
+                )
+        );
+
+
+        Assertions.assertDoesNotThrow(() -> agentProcess.run().resultOfType(JavaRetryTestOutput.class));
+
+        assertEquals(2, instance.retryInvocations.get(), "Retryable method should have been invoked");
+    }
+
+    @Test
+    void retryMethodFailsOnlyOnce() {
+        var reader = new AgentMetadataReader();
+        var instance = new JavaAgentWithRetryMethod();
+        var metadata = reader.createAgentMetadata(instance);
+
+        assertNotNull(metadata);
+        var agent = (com.embabel.agent.core.Agent) metadata;
+
+        var ap = IntegrationTestUtils.dummyAgentPlatform();
+        var agentProcess = ap.createAgentProcess(
+                agent,
+                ProcessOptions.DEFAULT.withPlannerType(PlannerType.UTILITY),
+                Map.of(
+                        "input", new JavaRetryTestInput("test")
+                )
+        );
+
+
+        Assertions.assertThrows(RuntimeException.class, () -> agentProcess.run().resultOfType(JavaRetryTestOutput.class));
+
+        assertEquals(1, instance.retryInvocationCount.get(), "Retryable method should have been invoked");
+    }
+
+}
+
+/**
+ * Simple domain class for testing.
+ */
+record JavaRetryTestInput(String value) {
+}
+
+/**
+ * Simple output class for testing.
+ */
+record JavaRetryTestOutput(String result) {
+}
+
+/**
+ * Agent with @Cost method that uses nullable domain parameter.
+ */
+@Agent(description = "Java agent with 1 retry", planner = PlannerType.UTILITY)
+class JavaAgentWithRetryMethod {
+
+    final AtomicInteger retryInvocationCount = new AtomicInteger(0);
+
+    @Action(retry = @Retry(maxAttempts = 1, backoffMillis = 1L))
+    public JavaRetryTestOutput perform(JavaRetryTestInput input) {
+        retryInvocationCount.incrementAndGet();
+        throw new RuntimeException("Failed on purpose!");
+    }
+}
+
+/**
+ * Agent with two actions with different dynamic costs.
+ */
+@Agent(description = "Java agent with two dynamic cost actions", planner = PlannerType.GOAP)
+class JavaAgentWithTwoRetryActions {
+
+    final AtomicInteger retryInvocations = new AtomicInteger(0);
+
+    @AchievesGoal(description = "Process the input")
+    @Action(retry = @Retry(maxAttempts = 2, backoffMillis = 1L))
+    public JavaRetryTestOutput firstAction(JavaRetryTestInput input) {
+        retryInvocations.incrementAndGet();
+        if (retryInvocations.get() == 1)
+            throw new RuntimeException("Failed!");
+
+        return new JavaRetryTestOutput("Success!");
+
+    }
+
+
+}