Embabel Agent Documentation/com.embabel.agent.api.tool/DelegatingTool

DelegatingTool

Interface for tool decorators that wrap another tool. Enables unwrapping to find the underlying tool implementation. Thus, it is important that tool wrappers implement this interface to allow unwrapping.

Canonical call method

call (String, ToolCallContext) is the single canonical entry point for decorator logic. Decorators should override only this method. The single-arg call (String) routes through it automatically via ToolCallContext.EMPTY, so both call paths execute the same decorator behavior.

This eliminates a class of bugs where a decorator overrides call (String) but the two-arg variant (used by com.embabel.agent.spi.loop.support.DefaultToolLoop) bypasses the decorator entirely.

Inheritors

ConfirmingTool

ConditionalAwaitingTool

TypeRequestingTool

ArtifactSinkingTool

ReplanningTool

ConditionalReplanningTool

ObservabilityTool

OutputTransformingTool

MetadataEnrichingTool

EventPublishingTool

ExceptionSuppressingTool

AgentProcessBindingTool

AssetAddingTool

Properties

definition

abstract val definition: Tool.Definition

Tool definition for LLM

delegate

abstract val delegate: Tool

The underlying tool being delegated to.

metadata

open val metadata: Tool.Metadata

Optional metadata

Functions

call

open override fun call(input: String): Tool.Result

Routes single-arg calls through the canonical two-arg method, ensuring decorator logic in call (String, ToolCallContext) is always executed regardless of which overload the caller uses.

open override fun call(input: String, context: ToolCallContext): Tool.Result

Canonical entry point for decorator logic. Override this method to add behavior while preserving context propagation to delegate.

requireType

inline fun <T : Any> Tool.requireType(message: String? = null): Tool

Wrap this tool to require a value of type T before execution (reified).

fun <T : Any> Tool.requireType(type: Class<T>, messageProvider: (String) -> String? = { null }): Tool

Wrap this tool to require a value of type T before execution.

toSpringToolCallback

fun Tool.toSpringToolCallback(): <Error class: unknown class>

Extension function to convert an Embabel Tool to a Spring AI ToolCallback.

unwrapAs

inline fun <T : Tool> Tool.unwrapAs(): T?

Unwrap a tool to find a specific type, or return null if not found.

withAwaiting

fun Tool.withAwaiting(decider: AwaitDecider): Tool

Wrap this tool to conditionally await before execution.

withConfirmation

fun Tool.withConfirmation(messageProvider: (String) -> String): Tool

fun Tool.withConfirmation(message: String): Tool

Wrap this tool to always require confirmation before execution.

withDescription

open fun withDescription(newDescription: String): Tool

Create a new tool with a different description. Useful for providing context-specific descriptions while keeping the same functionality.

withEventPublication

fun Tool.withEventPublication(agentProcess: AgentProcess, action: Action?, llmOptions: <Error class: unknown class>): Tool

Extension function to wrap a Tool with event publication.

withName

open fun withName(newName: String): Tool

Create a new tool with a different name. Useful for namespacing tools when combining multiple tool sources.

withNote

open fun withNote(note: String): Tool

Create a new tool with an additional note appended to the description. Useful for adding context-specific hints to an existing tool.