Package org.machanism.machai.process.tools
The package is intentionally divided into three cooperating layers:
- Declarations:
Tool,Prompt, andResourceare runtime-retained method annotations.Paramsupplies runtime-retained parameter metadata, andRoleidentifies the participant associated with a prompt. - Registration:
FunctionToolsis the marker service-provider interface for a capability bundle. Implementations are discovered byFunctionToolsLoaderthroughServiceLoaderand registered with aProcessProvider. - Execution and failures:
ToolFunctionis the callback contract for programmatic invocation.ParamDescriptorrepresents equivalent parameter metadata outside annotations, whileErrorResultException,ToolExecutionException, andSpecialExceptioncommunicate structured errors, checked tool failures, and intentional task completion respectively.
Declaring capabilities
Annotate public or otherwise discoverable methods with Tool for
invokable operations, Prompt for prompt-producing methods, or
Resource for content identified by one or more URIs. Each annotation
requires a description. Names and MIME types use a package-defined
NOT_DEFINED sentinel when omitted; integrations should interpret that
sentinel according to their own naming and schema rules rather than exposing it
to consumers. A Prompt also declares a Role, defaulting to
Role.USER. Annotate method parameters with Param when their
names, descriptions, or default values must be published as input metadata.
ParamDescriptor is the programmatic counterpart to Param.
Its ParamDescriptor.getDescription() and
ParamDescriptor.getDefaultValue() methods translate the
Param.NULL and Param.NOT_DEFINED string sentinels to
null where applicable. Providers remain responsible for validating
declarations, converting input values, invoking methods, and serializing
returned values.
Discovery and compatibility
Implement FunctionTools in a class that groups related annotated
methods, then publish the implementation's fully qualified class name in
META-INF/services/org.machanism.machai.process.tools.FunctionTools.
FunctionToolsLoader also accepts the legacy descriptor name used by
earlier releases. When FunctionToolsLoader.applyTools(org.machanism.machai.process.provider.ProcessProvider, String[], Class) is
called, compatible implementations are passed to the provider for tool,
prompt, and resource registration in discovery order. The loader does not
deduplicate implementations.
SupportedFor narrows registration to application classes. With no
annotation, or with an empty SupportedFor.value() array, an
implementation is compatible with every application class. Otherwise, the
requested application class must be assignable to at least one included class.
A class assignable from the requested application class in
SupportedFor.excludes() vetoes an otherwise valid match. The
value and excludes arrays therefore allow both positive and
negative compatibility rules.
Executing tools and handling outcomes
Use ToolFunction when a provider needs a programmatic callback
rather than reflective method invocation. Its
ToolFunction.apply(com.fasterxml.jackson.databind.JsonNode, Object[])
method receives a JSON parameter tree and optional context objects, such as a
working-directory File or a
Configurator, and may
throw an exception. ToolFunction.SESSION_ID_PARAM_NAME defines the
standard session identifier key.
Throw ErrorResultException when a structured payload should be
returned through an exception message; non-string payloads are serialized as
JSON when possible. Use ToolExecutionException for a checked failure
from tool execution. Use SpecialException when the current task should
finish while the host application remains running. The provider integration is
responsible for catching these exceptions and mapping them to its protocol.
Example
public final class ProjectTools implements FunctionTools {
@Tool(description = "Reads a project resource by relative path.")
public String readResource(
@Param(description = "Path relative to the project root.") String path) {
return loadProjectResource(path);
}
}
Keep published tool names, resource URI identifiers, and descriptions
stable when clients depend on them. Document the context object types expected
by each ToolFunction, and package every service descriptor with its
implementation.
-
ClassDescriptionSignals that the current task has ended without terminating the application.A runtime exception used to signal a tool or processing error, with a structured error payload that is serialized to JSON and included in the exception message.Service-provider interface (SPI) for installing host-provided function tools.Discovers and applies
FunctionToolsimplementations using Java'sServiceLoadermechanism.Descriptor for a parameter used in tool or prompt definitions within the AI provider framework.Annotation to mark a method as a prompt within the AI provider framework.Annotation used to declare a method as an executable resource provider within the generative-AI tools system.Enumeration representing participant roles in an AI interaction context.Exception used to signal the end of a task without terminating the application.Indicates which application classes aFunctionToolsimplementation supports.Annotation to mark a method as a tool function within the AI provider framework.Indicates that a tool callback could not complete its requested operation.Functional interface representing a tool callable by a provider during a run.