Package com.embabel.agent.api.tool

Object Tool.Companion

    • Constructor Detail

    • Method Detail

      • create

         final static Tool create(String name, String description, Tool.Handler handler)

        Create a tool with no parameters (Java-friendly). This method is easier to call from Java as it uses the Handler interface.

        Example:

        Tool tool = Tool.create("greet", "Greets user", input -> Tool.Result.text("Hello!"));
        Parameters:
        name - Tool name
        description - Tool description
        handler - Handler that processes input and returns a result
        Returns:

        A new Tool instance

      • create

         final static Tool create(String name, String description, Tool.Metadata metadata, Tool.Handler handler)

        Create a tool with custom metadata (Java-friendly).

        Parameters:
        name - Tool name
        description - Tool description
        metadata - Tool metadata (e.g.
        handler - Handler that processes input and returns a result
        Returns:

        A new Tool instance

      • create

         final static Tool create(String name, String description, Tool.InputSchema inputSchema, Tool.Handler handler)

        Create a tool with input schema (Java-friendly).

        Parameters:
        name - Tool name
        description - Tool description
        inputSchema - Schema describing the input parameters
        handler - Handler that processes input and returns a result
        Returns:

        A new Tool instance

      • create

         final static Tool create(String name, String description, Tool.InputSchema inputSchema, Tool.Metadata metadata, Tool.Handler handler)

        Create a fully configured tool (Java-friendly).

        Parameters:
        name - Tool name
        description - Tool description
        inputSchema - Schema describing the input parameters
        metadata - Tool metadata
        handler - Handler that processes input and returns a result
        Returns:

        A new Tool instance

      • fromFunction

         static <I extends Any, O extends Any> Tool fromFunction(String name, String description, Class<I> inputType, Class<O> outputType, Function<I, O> function)

        Create a tool with strongly typed input and output (Java-friendly).

        Parameters:
        name - Tool name
        description - Tool description
        inputType - Class of the input type
        outputType - Class of the output type
        function - Function that processes typed input and returns typed output
        Returns:

        A new Tool instance

      • fromFunction

         static <I extends Any, O extends Any> Tool fromFunction(String name, String description, Class<I> inputType, Class<O> outputType, Tool.Metadata metadata, Function<I, O> function)

        Create a tool with strongly typed input and output with custom metadata (Java-friendly).

        Parameters:
        name - Tool name
        description - Tool description
        inputType - Class of the input type
        outputType - Class of the output type
        metadata - Tool metadata
        function - Function that processes typed input and returns typed output
        Returns:

        A new Tool instance

      • fromFunction

         static <I extends Any, O extends Any> Tool fromFunction(String name, String description, Class<I> inputType, Class<O> outputType, Tool.Metadata metadata, ObjectMapper objectMapper, Function<I, O> function)

        Create a tool with strongly typed input and output with custom ObjectMapper (Java-friendly).

        Parameters:
        name - Tool name
        description - Tool description
        inputType - Class of the input type
        outputType - Class of the output type
        metadata - Tool metadata
        objectMapper - ObjectMapper for JSON serialization/deserialization
        function - Function that processes typed input and returns typed output
        Returns:

        A new Tool instance

      • fromInstance

         static List<Tool> fromInstance(Object instance, ObjectMapper objectMapper)

        Create Tools from all methods annotated with LlmTool on an instance.

        If the instance's class is annotated with UnfoldingTools or MatryoshkaTools, returns a single UnfoldingTool containing all the inner tools. Otherwise, returns individual tools for each annotated method.

        Parameters:
        instance - The object instance to scan for annotated methods
        objectMapper - ObjectMapper for JSON parsing (optional)
        Returns:

        List of Tools, one for each annotated method (or single UnfoldingTool if @UnfoldingTools/@MatryoshkaTools present)

      • safelyFromInstance

         static List<Tool> safelyFromInstance(Object instance, ObjectMapper objectMapper)

        Safely create Tools from an instance, returning empty list if no annotated methods found. This is useful when you want to scan an object that may or may not have tool methods.

        Parameters:
        instance - The object instance to scan for annotated methods
        objectMapper - ObjectMapper for JSON parsing (optional)
        Returns:

        List of Tools, or empty list if no annotated methods found

      • replanAlways

         static Tool replanAlways(Tool tool)

        Make this tool always replan after execution, adding the artifact to the blackboard.

      • conditionalReplan

         static <T extends Any> DelegatingTool conditionalReplan(Tool tool, Function2<T, ReplanContext, ReplanDecision> decider)

        When the decider returns a ReplanDecision, replan after execution, adding the artifact to the blackboard along with any additional updates from the decision. The decider receives the artifact cast to type T and the replan context. If the artifact is null or cannot be cast to T, the decider is not called.

      • replanWhen

         static <T extends Any> DelegatingTool replanWhen(Tool tool, Function1<T, Boolean> predicate)

        When the predicate matches the tool result artifact, replan, adding the artifact to the blackboard. The predicate receives the artifact cast to type T. If the artifact is null or cannot be cast to T, returns normally.

      • replanAndAdd

         static <T extends Any> DelegatingTool replanAndAdd(Tool tool, Function1<T, Object> valueComputer)

        Replan and add the object returned by the valueComputer to the blackboard.

        Parameters:
        tool - The tool to wrap
        valueComputer - Function that takes the artifact of type T and returns an object to add to the blackboard, or null to not replan

      • formatToolTree

         final static String formatToolTree(String name, List<Tool> tools)

        Format a list of tools as an ASCII tree structure. UnfoldingTools are expanded recursively to show their inner tools.

        Parameters:
        name - The name to display at the root of the tree
        tools - The list of tools to format
        Returns:

        A formatted tree string, or a message if no tools are present

      • sinkArtifacts

         static <T extends Any> Tool sinkArtifacts(Tool tool, Class<T> clazz, ArtifactSink sink)

        Wrap a tool to sink artifacts of the specified type to the given sink. Handles both single artifacts and Iterables.

        Parameters:
        tool - The tool to wrap
        clazz - The class of artifacts to capture
        sink - Where to send captured artifacts

      • sinkArtifacts

         static <T extends Any> Tool sinkArtifacts(Tool tool, Class<T> clazz, ArtifactSink sink, Function1<T, Boolean> filter, Function1<T, Object> transform)

        Wrap a tool to sink artifacts of the specified type to the given sink, with optional filtering and transformation.

        Parameters:
        tool - The tool to wrap
        clazz - The class of artifacts to capture
        sink - Where to send captured artifacts
        filter - Predicate to filter which artifacts to capture
        transform - Function to transform artifacts before sinking

      • publishToBlackboard

         static Tool publishToBlackboard(Tool tool)

        Wrap a tool to publish all artifacts to the blackboard.

        Parameters:
        tool - The tool to wrap

      • publishToBlackboard

         static <T extends Any> Tool publishToBlackboard(Tool tool, Class<T> clazz)

        Wrap a tool to publish artifacts of the specified type to the blackboard.

        Parameters:
        tool - The tool to wrap
        clazz - The class of artifacts to publish

      • publishToBlackboard

         static <T extends Any> Tool publishToBlackboard(Tool tool, Class<T> clazz, Function1<T, Boolean> filter, Function1<T, Object> transform)

        Wrap a tool to publish artifacts of the specified type to the blackboard, with optional filtering and transformation.

        Parameters:
        tool - The tool to wrap
        clazz - The class of artifacts to publish
        filter - Predicate to filter which artifacts to publish
        transform - Function to transform artifacts before publishing