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

AgenticTool

data class ~~AgenticTool~~(val definition: Tool.Definition, val metadata: Tool.Metadata = Tool.Metadata.DEFAULT, val llm: <Error class: unknown class> = LlmOptions(), val tools: List<Tool> = emptyList(), val systemPromptCreator: SystemPromptCreator = { defaultSystemPrompt(definition.description) }, val captureNestedArtifacts: Boolean = false) : Tool

Deprecated

Use SimpleAgenticTool for flat tool orchestration, or PlaybookTool/StateMachineTool for controlled disclosure

Replace with

import com.embabel.agent.api.tool.agentic.simple.SimpleAgenticTool

SimpleAgenticTool

An agentic tool that uses an LLM to orchestrate other tools.

Unlike a regular Tool which executes deterministic logic, an AgenticTool tool uses an LLM to decide which sub-tools to call based on a prompt.

Parameters

definition

Tool definition (name, description, input schema)

metadata

Optional tool metadata

llm

Llm to use for orchestration

tools

Sub-tools available for the LLM to orchestrate

systemPromptCreator

Create prompt for the LLM to use. Specify to customize behavior

captureNestedArtifacts

Whether to capture artifacts from nested AgenticTools. Default is false, meaning only artifacts from leaf tools are captured. Set to true to capture all artifacts including those from nested agentic sub-tools.

Constructors

AgenticTool

constructor(name: String, description: String)

Create an agentic tool that will need to be customized to add tools (and possibly specify an LLM) to be useful.

constructor(definition: Tool.Definition, metadata: Tool.Metadata = Tool.Metadata.DEFAULT, llm: <Error class: unknown class> = LlmOptions(), tools: List<Tool> = emptyList(), systemPromptCreator: SystemPromptCreator = { defaultSystemPrompt(definition.description) }, captureNestedArtifacts: Boolean = false)

Types

Companion

object Companion

Properties

captureNestedArtifacts

val captureNestedArtifacts: Boolean = false

definition

open override val definition: Tool.Definition

llm

val llm: <Error class: unknown class>

metadata

open override val metadata: Tool.Metadata

systemPromptCreator

val systemPromptCreator: SystemPromptCreator

tools

val tools: List<Tool>

Functions

call

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

Execute the tool with JSON input.

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.

withCaptureNestedArtifacts

fun withCaptureNestedArtifacts(capture: Boolean): AgenticTool

Create a copy with different captureNestedArtifacts setting. When false (default), artifacts from nested AgenticTools are not captured. When true, all artifacts are captured including those from nested agentic sub-tools.

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.

withLlm

fun withLlm(llm: <Error class: unknown class>): AgenticTool

Create a copy with different model.

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.

withParameter

fun withParameter(parameter: Tool.Parameter): AgenticTool

withSystemPrompt

fun withSystemPrompt(prompt: String): AgenticTool

Create a copy with fixed syste prompt. The system prompt describes the supervisor behavior.

withSystemPromptCreator

fun withSystemPromptCreator(promptCreator: SystemPromptCreator): AgenticTool

withToolObject

fun withToolObject(toolObject: Any): AgenticTool

Create a copy with tools extracted from an object with @LlmTool methods. If the object has no @LlmTool methods, returns this unchanged.

withToolObjects

fun withToolObjects(vararg toolObjects: Any): AgenticTool

Create a copy with tools extracted from multiple objects with @LlmTool methods. Objects without @LlmTool methods are silently ignored.

withTools

fun withTools(vararg additionalTools: Tool): AgenticTool

Create a copy with additional tools.