Package com.google.genkit.ai

Class Tool<I,O>

java.lang.Object
com.google.genkit.ai.Tool<I,O>
Type Parameters:
I - the input type
O - the output type
All Implemented Interfaces:
Action<I,O,Void>, Registerable
public class Tool<I,O> extends Object implements Action<I,O,Void>
Tool represents a function that can be called by an AI model. Tools allow models to interact with external systems and perform actions during generation.

  • Constructor Details

    • Tool

      public Tool(String name, String description, Map<String,Object> inputSchema, Map<String,Object> outputSchema, Class<I> inputClass, BiFunction<ActionContext,I,O> handler)
      Creates a new Tool.
      Parameters:
      name - the tool name
      description - the tool description
      inputSchema - the input JSON schema
      outputSchema - the output JSON schema
      inputClass - the input class for JSON deserialization
      handler - the tool handler function

  • Method Details

    • builder

      public static <I, O> Tool.Builder<I,O> builder()
      Creates a builder for Tool.
      Type Parameters:
      I - the input type
      O - the output type
      Returns:
      a new builder

    • getName

      public String getName()
      Description copied from interface: Action
      Returns the name of the action.
      Specified by:
      getName in interface Action<I,O,Void>
      Returns:
      the action name

    • getType

      public ActionType getType()
      Description copied from interface: Action
      Returns the type of the action.
      Specified by:
      getType in interface Action<I,O,Void>
      Returns:
      the action type

    • getDesc

      public ActionDesc getDesc()
      Description copied from interface: Action
      Returns the descriptor of the action containing metadata, schemas, etc.
      Specified by:
      getDesc in interface Action<I,O,Void>
      Returns:
      the action descriptor

    • run

      public O run(ActionContext ctx, I input) throws GenkitException
      Description copied from interface: Action
      Runs the action with the given input.
      Specified by:
      run in interface Action<I,O,Void>
      Parameters:
      ctx - the action context
      input - the input to the action
      Returns:
      the output of the action
      Throws:
      GenkitException - if the action fails

    • run

      public O run(ActionContext ctx, I input, Consumer<Void> streamCallback) throws GenkitException
      Description copied from interface: Action
      Runs the action with the given input and streaming callback.
      Specified by:
      run in interface Action<I,O,Void>
      Parameters:
      ctx - the action context
      input - the input to the action
      streamCallback - callback for receiving streaming chunks, may be null
      Returns:
      the output of the action
      Throws:
      GenkitException - if the action fails

    • runJson

      public com.fasterxml.jackson.databind.JsonNode runJson(ActionContext ctx, com.fasterxml.jackson.databind.JsonNode input, Consumer<com.fasterxml.jackson.databind.JsonNode> streamCallback) throws GenkitException
      Description copied from interface: Action
      Runs the action with JSON input and returns JSON output.
      Specified by:
      runJson in interface Action<I,O,Void>
      Parameters:
      ctx - the action context
      input - the JSON input
      streamCallback - callback for receiving streaming JSON chunks, may be null
      Returns:
      the JSON output
      Throws:
      GenkitException - if the action fails

    • runJsonWithTelemetry

      public ActionRunResult<com.fasterxml.jackson.databind.JsonNode> runJsonWithTelemetry(ActionContext ctx, com.fasterxml.jackson.databind.JsonNode input, Consumer<com.fasterxml.jackson.databind.JsonNode> streamCallback) throws GenkitException
      Description copied from interface: Action
      Runs the action with JSON input and returns the result with telemetry information.
      Specified by:
      runJsonWithTelemetry in interface Action<I,O,Void>
      Parameters:
      ctx - the action context
      input - the JSON input
      streamCallback - callback for receiving streaming JSON chunks, may be null
      Returns:
      the action result including telemetry data
      Throws:
      GenkitException - if the action fails

    • getInputSchema

      public Map<String,Object> getInputSchema()
      Description copied from interface: Action
      Returns the JSON schema for the action's input type.
      Specified by:
      getInputSchema in interface Action<I,O,Void>
      Returns:
      the input schema as a map, or null if not defined

    • getOutputSchema

      public Map<String,Object> getOutputSchema()
      Description copied from interface: Action
      Returns the JSON schema for the action's output type.
      Specified by:
      getOutputSchema in interface Action<I,O,Void>
      Returns:
      the output schema as a map, or null if not defined

    • getMetadata

      public Map<String,Object> getMetadata()
      Description copied from interface: Action
      Returns additional metadata for the action.
      Specified by:
      getMetadata in interface Action<I,O,Void>
      Returns:
      the metadata map

    • register

      public void register(Registry registry)
      Description copied from interface: Registerable
      Registers this primitive with the given registry.
      Specified by:
      register in interface Registerable
      Parameters:
      registry - the registry to register with

    • getDescription

      public String getDescription()
      Gets the tool description.
      Returns:
      the description

    • getInputClass

      public Class<I> getInputClass()
      Gets the input class for JSON deserialization.
      Returns:
      the input class, or null if not specified

    • getDefinition

      public ToolDefinition getDefinition()
      Gets the tool definition for use in model requests.
      Returns:
      the tool definition

    • respond

      public Part respond(Part interrupt, O output)
      Constructs a tool response for an interrupted tool request.

      This method is used when resuming generation after an interrupt. It creates a tool response part that can be passed to ResumeOptions.getRespond().

      Example usage: 

      
 // Get interrupt from response
 Part interrupt = response.getInterrupts().get(0);
 
 // Create response with user-provided data
 Part responseData = tool.respond(interrupt, userConfirmation);
 
 // Resume generation
 ModelResponse resumed = genkit.generate(GenerateOptions.builder().messages(response.getMessages())
 		.resume(ResumeOptions.builder().respond(responseData).build()).build());
      Parameters:
      interrupt - the interrupted tool request part
      output - the output data to respond with
      Returns:
      a tool response part

    • respond

      public Part respond(Part interrupt, O output, Map<String,Object> metadata)
      Constructs a tool response for an interrupted tool request with metadata.
      Parameters:
      interrupt - the interrupted tool request part
      output - the output data to respond with
      metadata - optional metadata to include in the response
      Returns:
      a tool response part

    • restart

      public Part restart(Part interrupt, Map<String,Object> resumedMetadata)
      Constructs a restart request for an interrupted tool.

      This method creates a tool request that will cause the tool to be re-executed. The resumed metadata will be passed to the tool handler.

      Example usage: 

      
 // Get interrupt from response
 Part interrupt = response.getInterrupts().get(0);
 
 // Create restart request with confirmation metadata
 Part restartRequest = tool.restart(interrupt, Map.of("confirmed", true));
 
 // Resume generation
 ModelResponse resumed = genkit.generate(GenerateOptions.builder().messages(response.getMessages())
 		.resume(ResumeOptions.builder().restart(restartRequest).build()).build());
      Parameters:
      interrupt - the interrupted tool request part
      resumedMetadata - metadata to pass to the tool handler's resumed context
      Returns:
      a tool request part for restart

    • restart

      public Part restart(Part interrupt, Map<String,Object> resumedMetadata, I replaceInput)
      Constructs a restart request with replacement input.
      Parameters:
      interrupt - the interrupted tool request part
      resumedMetadata - metadata to pass to the tool handler's resumed context
      replaceInput - optional new input to use instead of the original
      Returns:
      a tool request part for restart