Embabel Agent Documentation/com.embabel.agent.core.hitl/AwaitableTypedTool

AwaitableTypedTool

abstract class AwaitableTypedTool<I : Any, O : Any, P : Any> constructor(name: String, description: String, inputType: Class<I>, outputType: Class<O>, metadata: Tool.Metadata = Tool.Metadata.DEFAULT, objectMapper: <Error class: unknown class> = jacksonObjectMapper()) : TypedTool<I, O>

Abstract typed tool that supports Human-in-the-Loop (HITL) interactions.

Before executing the main tool logic, this tool checks if human input is required via createAwaitable. If an Awaitable is returned, the tool throws AwaitableResponseException to pause execution and wait for user response.

Example usage:

data class DeleteRequest(val path: String, val force: Boolean = false)
data class DeleteResult(val deleted: Boolean, val path: String)

class ConfirmingDeleteTool : AwaitableTypedTool<DeleteRequest, DeleteResult, DeleteRequest>(
    name = "delete_file",
    description = "Delete a file with confirmation",
    inputType = DeleteRequest::class.java,
    outputType = DeleteResult::class.java,
) {
    override fun createAwaitable(input: DeleteRequest): Awaitable<DeleteRequest, *>? {
        // Only confirm for non-force deletes
        return if (!input.force) {
            ConfirmationRequest(input, "Delete ${input.path}?")
        } else null
    }

    override fun execute(input: DeleteRequest): DeleteResult {
        val success = Files.deleteIfExists(Path.of(input.path))
        return DeleteResult(deleted = success, path = input.path)
    }
}

Parameters

I

Input type - will be deserialized from JSON

O

Output type - will be serialized to JSON

P

Payload type for the awaitable (often same as I)

name

Tool name for LLM consumption

description

Tool description for LLM consumption

inputType

Class of the input type for JSON deserialization

outputType

Class of the output type

metadata

Optional tool metadata

objectMapper

ObjectMapper for JSON serialization/deserialization

Constructors

AwaitableTypedTool

constructor(name: String, description: String, inputType: Class<I>, outputType: Class<O>, metadata: Tool.Metadata = Tool.Metadata.DEFAULT, objectMapper: <Error class: unknown class> = jacksonObjectMapper())

Properties

open override val definition: Tool.Definition

Tool definition for LLM

open override val metadata: Tool.Metadata

Functions

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

Execute the tool with JSON input and out-of-band context.

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

Executes the tool by deserializing input JSON, calling typedCall, and serializing the result.

createAwaitable

abstract fun createAwaitable(input: I): Awaitable<P, *>?

Check if this tool invocation requires human input.

abstract fun execute(input: I): O

Execute the tool logic after any awaitable has been resolved.

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.

override fun typedCall(input: I): O

Execute the tool with strongly typed input. Calls the function provided at construction time. Can be overridden in subclasses for custom behavior.

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

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

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.

withDefinitionMetadata

open fun withDefinitionMetadata(entries: Map<String, Any>): Tool

Create a new tool with additional definition metadata entries merged in. Existing keys are overwritten by the new values.

open fun withDefinitionMetadata(key: String, value: Any): Tool

Create a new tool with a single definition metadata entry added.

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.

open fun withName(newName: String): Tool

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

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.