Embabel Agent Documentation/com.embabel.agent.api.tool.agentic.playbook/PlaybookTool

PlaybookTool

data class PlaybookTool : AgenticTool<PlaybookTool>

A tool with conditional tool unlocking that uses an LLM to orchestrate sub-tools.

Unlike com.embabel.agent.api.tool.agentic.simple.SimpleAgenticTool which makes all tools available immediately, a PlaybookTool allows tools to be progressively unlocked based on conditions such as:

Prerequisites: unlock after other tools have been called
Artifacts: unlock when certain artifact types are produced
Blackboard: unlock based on process state
Custom predicates: unlock based on arbitrary conditions

This provides more predictable LLM behavior by guiding it through a structured sequence of available tools.

Usage

// Kotlin curried syntax
PlaybookTool("researcher", "Research and analyze topics")
    .withTools(searchTool, fetchTool)           // always available
    .withTool(analyzeTool)(searchTool)          // unlocks after search
    .withTool(summarizeTool)(analyzeTool)       // unlocks after analyze

// Java fluent syntax
new PlaybookTool("researcher", "Research and analyze topics")
    .withTools(searchTool, fetchTool)
    .withTool(analyzeTool).unlockedBy(searchTool)
    .withTool(summarizeTool).unlockedBy(analyzeTool);

Parameters

definition

Tool definition (name, description, input schema)

metadata

Optional tool metadata

llm

LLM to use for orchestration. It is good practice to provide

unlockedTools

Tools that are always available

lockedTools

Tools with unlock conditions

systemPromptCreator

Create prompt for the LLM to use, given context and input

maxIterations

Maximum number of tool loop iterations

Constructors

PlaybookTool

constructor(name: String, description: String)

Create a playbook tool with the given name and description.

Types

Companion

object Companion

Properties

definition

open override val definition: Tool.Definition

llm

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

lockedToolCount

val lockedToolCount: Int

Number of conditionally-locked tools.

maxIterations

open override val maxIterations: Int

metadata

open override val metadata: Tool.Metadata

systemPromptCreator

val systemPromptCreator: AgenticSystemPromptCreator

unlockedToolCount

val unlockedToolCount: Int

Number of always-unlocked tools.

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.

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

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

Create a copy with different LLM options.

withMaxIterations

open override fun withMaxIterations(maxIterations: Int): PlaybookTool

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): PlaybookTool

Create a copy with an additional parameter in the definition.

withSystemPrompt

open fun withSystemPrompt(prompt: String): PlaybookTool

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): PlaybookTool

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

withTool

fun withTool(tool: Tool): ToolRegistration

Begin registration of a tool with unlock conditions. Returns a ToolRegistration that can be used with curried syntax or fluent API.

withToolChainingFrom

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

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(): PlaybookTool

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): PlaybookTool

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

withToolChainingFromAny

open override fun withToolChainingFromAny(): PlaybookTool

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

withToolObject

open override fun withToolObject(toolObject: Any): PlaybookTool

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

withTools

fun withTools(vararg tools: Tool): PlaybookTool

Add tools that are always available (no unlock conditions).