Added cache control support

Author: dosier

agents/agents-core/src/commonMain/kotlin/ai/koog/agents/core/agent/context/AIAgentLLMContext.kt

@@ -17,27 +17,6 @@ import ai.koog.prompt.processor.ResponseProcessor
 import kotlin.time.Clock
 import kotlin.jvm.JvmName
 
-/**
- * Annotation for marking APIs as detached prompt executors within the `AIAgentLLMContext`.
- *
- * Using APIs annotated with this requires opting in, as calls to `PromptExecutor` will be disconnected
- * from the agent logic. This means these calls will not affect the agent's state or adhere to the
- * `ToolsConversionStrategy`.
- *
- * This API should be used with caution, as it provides functionality that operates outside the
- * standard agent lifecycle and processing logic.
- */
-@MustBeDocumented
-@Retention(AnnotationRetention.BINARY)
-@RequiresOptIn(
-    level = RequiresOptIn.Level.ERROR,
-    message = "Calls to PromptExecutor used from `AIAgentLLMContext` will not be connected to the agent logic, " +
-        "and will not impact the agent's state. " +
-        "Other than that, `ToolsConversionStrategy` will not be applied. " +
-        "Please be cautious when using this API."
-)
-public annotation class DetachedPromptExecutorAPI
-
 /**
  * Represents the context for an AI agent LLM, managing tools, prompt handling, and interaction with the
  * environment and execution layers. It provides mechanisms for concurrent read and write operations

agents/agents-tools/src/commonMain/kotlin/ai/koog/agents/core/tools/Tool.kt

@@ -2,6 +2,7 @@ package ai.koog.agents.core.tools
 
 import ai.koog.agents.core.tools.annotations.InternalAgentToolsApi
 import ai.koog.agents.core.tools.serialization.ToolJson
+import ai.koog.prompt.params.LLMParams
 import kotlinx.serialization.KSerializer
 import kotlinx.serialization.Serializable
 import kotlinx.serialization.json.Json
@@ -262,3 +263,53 @@ public abstract class Tool<TArgs, TResult>(
     @Serializable
     public data object EmptyArgs : Args
 }
+
+/**
+ * A wrapper tool that delegates all operations to the original tool but uses a modified descriptor
+ * with cache control settings.
+ *
+ * This class enables adding cache control to existing tools without modifying their implementation.
+ * When cache control is set on a tool, LLM providers like Anthropic will cache tool definitions
+ * up to and including this tool, reducing latency and cost for repeated requests.
+ *
+ * @param TArgs The type of arguments the tool accepts.
+ * @param TResult The type of result the tool returns.
+ * @param delegate The original tool to wrap.
+ * @param cacheControl The cache control setting to apply to this tool's descriptor.
+ */
+public class CachedTool<TArgs, TResult>(
+    private val delegate: Tool<TArgs, TResult>,
+    cacheControl: LLMParams.CacheControl,
+) : Tool<TArgs, TResult>(
+    argsSerializer = delegate.argsSerializer,
+    resultSerializer = delegate.resultSerializer,
+    descriptor = delegate.descriptor.copy(cacheControl = cacheControl),
+) {
+    override suspend fun execute(args: TArgs): TResult = delegate.execute(args)
+
+    override fun encodeResultToString(result: TResult): String = delegate.encodeResultToString(result)
+}
+
+/**
+ * Creates a new tool with the specified cache control setting.
+ *
+ * This extension function wraps the original tool in a [CachedTool] that delegates all operations
+ * to the original but uses a modified descriptor with cache control.
+ *
+ * When cache control is set on a tool, LLM providers like Anthropic will cache tool definitions
+ * up to and including this tool, reducing latency and cost for repeated requests.
+ *
+ * Usage example:
+ * ```kotlin
+ * val registry = ToolRegistry {
+ *     tool(myTool)
+ *     tool(expensiveTool.withCacheControl(LLMParams.CacheControl.Ephemeral))
+ * }
+ * ```
+ *
+ * @param cacheControl The cache control setting to apply to this tool.
+ * @return A new tool with the cache control setting applied.
+ */
+public fun <TArgs, TResult> Tool<TArgs, TResult>.withCacheControl(
+    cacheControl: LLMParams.CacheControl
+): Tool<TArgs, TResult> = CachedTool(this, cacheControl)

agents/agents-tools/src/commonMain/kotlin/ai/koog/agents/core/tools/ToolDescriptor.kt

@@ -1,5 +1,7 @@
 package ai.koog.agents.core.tools
 
+import ai.koog.prompt.params.LLMParams
+
 /**
  * Represents a descriptor for a tool that contains information about the tool's name, description, required parameters,
  * and optional parameters.
@@ -10,12 +12,18 @@ package ai.koog.agents.core.tools
  * @property description The description of the tool.
  * @property requiredParameters A list of ToolParameterDescriptor representing the required parameters for the tool.
  * @property optionalParameters A list of ToolParameterDescriptor representing the optional parameters for the tool.
+ * @property cacheControl Optional cache control setting for this tool definition.
+ * When set, signals to LLM providers (like Anthropic) that tool definitions up to and including
+ * this tool should be cached. This is useful for reducing latency and cost when the same tools
+ * are used across multiple requests. Cache control is applied per-tool, allowing fine-grained
+ * control over which tools act as cache breakpoints.
  */
 public open class ToolDescriptor(
     public val name: String,
     public val description: String,
     public val requiredParameters: List<ToolParameterDescriptor> = emptyList(),
     public val optionalParameters: List<ToolParameterDescriptor> = emptyList(),
+    public val cacheControl: LLMParams.CacheControl? = null,
 ) {
     /**
      * Creates a copy of the current ToolDescriptor with the option to modify specific attributes.
@@ -26,19 +34,22 @@ public open class ToolDescriptor(
      * Defaults to the current required parameters if not provided.
      * @param optionalParameters A list of ToolParameterDescriptor representing the optional parameters for the tool.
      * Defaults to the current optional parameters if not provided.
+     * @param cacheControl Optional cache control setting for this tool. Defaults to the current cache control if not provided.
      * @return A new instance of ToolDescriptor with the updated attributes.
      */
     public fun copy(
         name: String = this.name,
         description: String = this.description,
         requiredParameters: List<ToolParameterDescriptor> = this.requiredParameters.toList(),
         optionalParameters: List<ToolParameterDescriptor> = this.optionalParameters.toList(),
+        cacheControl: LLMParams.CacheControl? = this.cacheControl,
     ): ToolDescriptor {
         return ToolDescriptor(
             name = name,
             description = description,
             requiredParameters = requiredParameters,
             optionalParameters = optionalParameters,
+            cacheControl = cacheControl,
         )
     }
 
@@ -50,19 +61,34 @@ public open class ToolDescriptor(
         if (description != other.description) return false
         if (requiredParameters != other.requiredParameters) return false
         if (optionalParameters != other.optionalParameters) return false
+        if (cacheControl != other.cacheControl) return false
 
         return true
     }
 
     override fun toString(): String {
-        return "ToolDescriptor(name=$name, description=$description, requiredParameters=$requiredParameters, optionalParameters=$optionalParameters)"
+        return "ToolDescriptor(name=$name, description=$description, requiredParameters=$requiredParameters, optionalParameters=$optionalParameters, cacheControl=$cacheControl)"
     }
 
     override fun hashCode(): Int {
         var result = name.hashCode()
         result = 31 * result + description.hashCode()
         result = 31 * result + requiredParameters.hashCode()
         result = 31 * result + optionalParameters.hashCode()
+        result = 31 * result + (cacheControl?.hashCode() ?: 0)
         return result
     }
 }
+
+/**
+ * Creates a copy of this ToolDescriptor with the specified cache control setting.
+ *
+ * This is a convenience extension function for setting cache control on tool definitions.
+ * When cache control is set, LLM providers like Anthropic will cache tool definitions
+ * up to and including this tool, reducing latency and cost for repeated requests.
+ *
+ * @param cacheControl The cache control setting to apply to this tool.
+ * @return A new ToolDescriptor with the cache control setting applied.
+ */
+public fun ToolDescriptor.withCacheControl(cacheControl: LLMParams.CacheControl): ToolDescriptor =
+    copy(cacheControl = cacheControl)

build.gradle.kts

@@ -77,7 +77,7 @@ version = run {
         }
     }
 
-    "0.6.0-flopiq-1"
+    "0.6.0-flopiq-3"
 }
 
 fun isCustomReleaseBranch(branchName: String): Boolean = branchName.matches(Regex("""^\d+\.\d+\.\d+$"""))