Embabel Agent Documentation/com.embabel.agent.api.tool.agentic.state/StateMachineTool

StateMachineTool

data class StateMachineTool<S : Enum<S>> : AgenticTool<StateMachineTool<S>> , StateMachineToolOperations<S>

A tool that manages state transitions, with tools available based on the current state.

Unlike com.embabel.agent.api.tool.playbook.PlaybookTool which uses unlock conditions, StateMachineTool uses explicit states defined by an enum. Tools are registered with specific states where they're available, and can trigger transitions to other states.

Usage

enum class OrderState { DRAFT, CONFIRMED, SHIPPED, DELIVERED }

StateMachineTool("orderProcessor", "Process orders", OrderState::class.java)
    .withInitialState(OrderState.DRAFT)
    .inState(OrderState.DRAFT)
        .withTool(addItemTool)
        .withTool(confirmTool).transitionsTo(OrderState.CONFIRMED)
    .inState(OrderState.CONFIRMED)
        .withTool(shipTool).transitionsTo(OrderState.SHIPPED)
    .inState(OrderState.SHIPPED)
        .withTool(deliverTool).transitionsTo(OrderState.DELIVERED)
    .inState(OrderState.DELIVERED)
        .withTool(reviewTool)

Parameters

The enum type defining the states

definition

Tool definition (name, description, input schema)

stateType

The enum class for states

initialState

The starting state

stateTools

Map of state to tools available in that state

llm

LLM options for orchestration

systemPromptCreator

Create prompt for the LLM, given context, input, and current state

maxIterations

Maximum iterations before stopping

Constructors

StateMachineTool

constructor(name: String, description: String, stateType: Class<S>)

Create a state machine tool with name, description and state enum type.

Types

Companion

object Companion

Properties

definition

open override val definition: Tool.Definition

initialState

val initialState: S?

llm

open override val llm: <Error class: unknown class>

maxIterations

open override val maxIterations: Int

metadata

open override val metadata: Tool.Metadata

Optional metadata

stateToolCounts

val stateToolCounts: Map<S, Int>

Count of tools registered for each state.

stateType

val stateType: Class<S>

systemPromptCreator

val systemPromptCreator: (ExecutingOperationContext, String, S) -> String

totalStateTools

val totalStateTools: Int

Total count of state-specific tools.

Functions

call

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

Execute the tool with JSON input.

inState

fun inState(state: S): StateBuilder<S>

Begin configuring tools for a specific state.

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.

startingIn

open override fun startingIn(state: S): Tool

Create a version of this tool that starts in the specified state. Useful when the starting state depends on runtime context.

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.

withGlobalTool

fun withGlobalTool(tool: Tool): StateMachineTool<S>

Add a tool available in all states.

withGlobalTools

fun withGlobalTools(vararg tools: Tool): StateMachineTool<S>

Add tools available in all states.

withInitialState

fun withInitialState(state: S): StateMachineTool<S>

Set the initial state.

withLlm

open override fun withLlm(llm: <Error class: unknown class>): StateMachineTool<S>

Create a copy with different LLM options.

withMaxIterations

open override fun withMaxIterations(maxIterations: Int): StateMachineTool<S>

Create a copy with a different max iterations limit.

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

open override fun withParameter(parameter: Tool.Parameter): StateMachineTool<S>

Create a copy with an additional parameter in the definition.

withStateAwareSystemPrompt

fun withStateAwareSystemPrompt(creator: (ExecutingOperationContext, String, S) -> String): StateMachineTool<S>

Set a custom system prompt creator that also receives the current state. This is useful for state machines where the prompt needs to reflect the current state.

withSystemPrompt

open fun withSystemPrompt(prompt: String): StateMachineTool<S>

Create a copy with a fixed system prompt. This is a convenience method that delegates to withSystemPrompt with a creator.

open override fun withSystemPrompt(creator: AgenticSystemPromptCreator): StateMachineTool<S>

Create a copy with a dynamic system prompt creator. The creator receives the execution context and input string.

withToolChainingFrom

open fun <T : Any> withToolChainingFrom(type: Class<T>): StateMachineTool<S>

Register a class whose @LlmTool methods become available as tools when a single instance of that type is returned as an artifact.

inline fun <T : Any> withToolChainingFrom(): StateMachineTool<S>

Register a class that can contribute @LlmTool methods when a single instance is retrieved. Kotlin-friendly version using reified type parameter.

inline fun <T : Any> withToolChainingFrom(noinline predicate: (T, AgentProcess?) -> Boolean): StateMachineTool<S>

open override fun <T : Any> withToolChainingFrom(type: Class<T>, predicate: DomainToolPredicate<T>): StateMachineTool<S>

withToolChainingFromAny

open override fun withToolChainingFromAny(): StateMachineTool<S>

Enable auto-discovery of chained tools from any returned artifact.

withToolObject

open override fun withToolObject(toolObject: Any): StateMachineTool<S>

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