Interface Tool<I,O>

Type Parameters:

I - Input type - a POJO for structured input

O - Output type - a POJO for structured output

All Superinterfaces:

GuardedExecution, Identifiable, Job<O>

All Known Subinterfaces:

Doer<I,O>, ModelDependentTool<I,O>, Orchestrator<I,O>, Thinker<I,O>

All Known Implementing Classes:

AbstractDoer, AbstractEPOTool, AbstractModelDependentTool, AbstractOrchestrator, AbstractThinker, AbstractTool, AbstractToollessThinker, AnalyzeViolationTool, Benchmark, BioRxivFetchTool, BioRxivSearchTool, CanonicalizeProductsTool, CaseAgent, ChatThinker, ClassifyFileTool, CurrentTimeTool, CustomerOrdersTool, CustomerOrderTool, CustomerReportDoer, DateCalculatorTool, DecideProductGroupsTool, DecisionCall, DecisionThinker, DecisionTool, DemoAgent, DemoBenchmark, DeterministicExtractTool, DisputeDoer, DurationCalculatorTool, EmailShiftDoer, EmbedTextTool, EPOBiblioTool, EPOClaimsTool, EPODescriptionTool, EPOFamilyTool, EPOFullTextTool, EPOImagesTool, EPOLegalStatusTool, EPONumberConversionTool, EPOSearchTool, EPOThinker, ExtractDirectoryDoer, ExtractPricesTool, ExtractPricingDoer, FileNoteTool, GenericMCPToolAdapter, GetArtifactFieldTool, JudgeTool, ListFolderTool, LiteratureAggregator, OrderAgent, OrderStatusTool, PdfVisionExtractTool, PMCFullTextTool, PoiDeterministicExtractTool, PriceChangeFinder, PubMedFetchTool, PubMedSearchTool, QuickLLMQuestionTool, ReactiveThinker, ReadDocumentTool, RemoteOrderStatusTool, RequestSkillTool, RequestToolsTool, SearchArtifactContentTool, SelectingAgent, SingleObjectiveThinker, SplitStatementsTool, SubThinker, SummarizationTool, UnitRateCalculatorTool, UsptoOdpContinuityTool, UsptoOdpFetchTool, UsptoOdpForeignPriorityTool, UsptoOdpFullTextTool, UsptoOdpLegalEventsTool, UsptoOdpSearchTool, UsptoOdpThinker, VisionExtractTool, WebFetchTool

public interface Tool<I,O>
extends Job<O>, GuardedExecution

Interface for executable tools that can be invoked by Thinkers.

Tools are specialized jobs that accept structured input and produce structured output. They declare their own resource requirements and can perform database operations, LLM calls, or any other work. Tools are identified by ToolName and ToolDescription annotations.

Every tool is a GuardedExecution: it may declare its own content, auth and admission guardrails, and the framework enforces them at dispatch on every route. The input-phase target is the tool's own input.

Since:

0.1 (2025-09-19)

Author:

Andrey Santrosyan

Field Summary

Fields

Modifier and Type	Field	Description
static final String	OBS_INPUT	Metadata key for serialized tool/thinker input.
static final String	OBS_OUTPUT	Metadata key for serialized tool/thinker output.

Fields inherited from interface Job

DEFAULT_UPSTREAM_RETRIES

Method Summary

Modifier and Type	Method	Description
O	execute(JobResources resources, JobContext<O> context)	Executes this tool with provided resources.
I	getInput()	Gets the structured input that was set for this tool.
default Object	guardedInputTarget()	The input-phase guardrail target is the tool's typed input.
void	setInput(I input)	Sets the structured input for this tool before execution.

Methods inherited from interface GuardedExecution

declareAdmissionGuardrails, declareAuthGuardrails, declareContentGuardrails

Methods inherited from interface Identifiable

getParentJobId, getUserId, getWorkflowId

Methods inherited from interface Job

getDisplayName, getId, getJobId, getJobType, getName, getPriority, getRequirements, getTimeout, getUpstreamRetries, postExecute, preExecute

Field Details

OBS_INPUT

static final String OBS_INPUT

Metadata key for serialized tool/thinker input.

See Also:

• Constant Field Values

OBS_OUTPUT

static final String OBS_OUTPUT

Metadata key for serialized tool/thinker output.

See Also:

• Constant Field Values

Method Details

execute

O execute(JobResources resources,
 JobContext<O> context)
   throws LLMReadableCheckedException

Executes this tool with provided resources.

Narrows the throws clause from Job.execute(JobResources, JobContext)'s throws Exception to throws LLMReadableCheckedException. This enforces at compile time that all tool implementations (including Thinkers and Doers) communicate errors through the typed LLM-readable exception hierarchy, never through raw exceptions.

Specified by:

execute in interface Job<I>

Parameters:

resources - the allocated resources

context - the job context

Returns:

the tool result

Throws:

LLMReadableCheckedException - if execution fails

setInput

void setInput(I input)

Sets the structured input for this tool before execution.

Parameters:

input - Structured input parameters that this tool requires

getInput

I getInput()

Gets the structured input that was set for this tool.

Returns:

Structured input parameters, null if not yet set

guardedInputTarget

default Object guardedInputTarget()

The input-phase guardrail target is the tool's typed input.

Specified by:

guardedInputTarget in interface GuardedExecution