AI Abstractions

Tool Boxes

A tool box is a set of callable tools exposed to a model. It is the mechanism by which an agent can do something other than talk — retrieve knowledge, read memory, show a UI element, call an external system.

The abstraction lives in common (ai.promethist.ai); the concrete tool boxes an agent gets are assembled in the engine — see Engine AI Layer.

The Contract

interface ToolBox {
    val specifications: Flux<ToolSpecification>
    fun callbacks(handler: ToolHandler = ToolHandler.empty): Flux<ToolCallback>
    fun call(toolName: String, parameters: Map<String, Any?>, toolHandler: ToolHandler = ToolHandler.empty): Mono<out Any>
    fun close(): Mono<Void> = Mono.empty()
}

Member Role

Member	Role
`specifications`	What the model is told exists: each tool’s name, description and parameter schema. This is what goes into the prompt or the provider’s function declarations.
`callbacks(handler)`	The same tools as callbacks for the underlying AI framework, so a chat model can invoke them during a completion.
`call(name, parameters, handler)`	Invokes one tool by name. This is the path a realtime provider takes when the model emits a tool call.
`close()`	Releases whatever the box holds open — a connection to an external server, for example. Called when the conversation ends.

specifications

What the model is told exists: each tool’s name, description and parameter schema. This is what goes into the prompt or the provider’s function declarations.

callbacks(handler)

The same tools as callbacks for the underlying AI framework, so a chat model can invoke them during a completion.

call(name, parameters, handler)

Invokes one tool by name. This is the path a realtime provider takes when the model emits a tool call.

close()

Releases whatever the box holds open — a connection to an external server, for example. Called when the conversation ends.

The ToolHandler passed to callbacks and call is the observation hook: it is notified on start, success and error of every invocation, which is how tool activity becomes visible to the client as tool-start, tool-success and tool-error commands.

Types of Tool Box

Structural

These do not provide tools of their own — they compose, adapt or stand in for other boxes.

Type Behaviour

Type	Behaviour
`EmptyToolBox`	No tools at all. The default an interaction manager returns when the agent should not call anything.
`MultiToolBox`	Merges several named boxes into one. Tool names are prefixed with the box name (`{box}_{tool}`) and a call is demultiplexed back to the owning box by that prefix, so two boxes can expose a tool of the same name. Closing it closes every child.
`AnnotatedToolBox`	Derives specifications from an annotated object by reflection and dispatches a call to the matching member function, injecting `Context`-typed parameters automatically. This is what makes a tool an ordinary described Kotlin function rather than a registration.

EmptyToolBox

No tools at all. The default an interaction manager returns when the agent should not call anything.

MultiToolBox

Merges several named boxes into one. Tool names are prefixed with the box name ({box}_{tool}) and a call is demultiplexed back to the owning box by that prefix, so two boxes can expose a tool of the same name. Closing it closes every child.

AnnotatedToolBox

Derives specifications from an annotated object by reflection and dispatches a call to the matching member function, injecting Context-typed parameters automatically. This is what makes a tool an ordinary described Kotlin function rather than a registration.

Decorating

A tool box can also wrap another one to change what happens around a call, without adding tools. The engine’s RelationalToolBox is the example: it detects a call to a tool the speaking model does not have, answers that results will follow, and records the attempt for the planner — see The Realtime Tool Box.

Editing a document

A tool box does not have to serve a conversation. The engine’s DevelopmentProfileToolBox exposes edit-in-place tools over an in-memory working copy of a document: the model sets one section per call, each call answers with the section as it now stands or with the reason it was rejected, and a final finishProfile call reports the outstanding validation errors so the model can fix them before it stops. Nothing is persisted by the box itself — the caller reads the working copy once the loop ends. It takes no Context, because there is no conversation to take one from.

Capability

The tool boxes that actually do something are implemented in the engine, one per capability — knowledge retrieval, the user’s memory, multimodal display, agent handover, in-app navigation, web search and Model Context Protocol servers. They are listed in Engine AI Layer.

Supporting Types

Type Role

Type	Role
`ToolSpecification`	A tool’s name, description and parameter schema — the description the model reads.
`ToolCall`, `ToolResponse`	One invocation and its result. A response may carry an element to emit to the client alongside the value returned to the model.
`ToolHandler`	The start, success and error hook described above.
`ToolCondition`, `AlwaysTrueCondition`	Whether a tool is offered in the current context at all, so a box can hide tools that make no sense for a given agent or device.
`ToolBoxCallback`, `RecordedToolCallbackFactory`	Bridge a tool box to the AI framework’s callback model, and to recorded replay — the second is what lets the session debugger re-run a turn without executing its tool calls again.

ToolSpecification

A tool’s name, description and parameter schema — the description the model reads.

ToolCall, ToolResponse

One invocation and its result. A response may carry an element to emit to the client alongside the value returned to the model.

ToolHandler

The start, success and error hook described above.

ToolCondition, AlwaysTrueCondition

Whether a tool is offered in the current context at all, so a box can hide tools that make no sense for a given agent or device.

ToolBoxCallback, RecordedToolCallbackFactory

Bridge a tool box to the AI framework’s callback model, and to recorded replay — the second is what lets the session debugger re-run a turn without executing its tool calls again.