Interface CallableTool


public interface CallableTool
A tool exposed to the model: pairs a declarative ToolDescription (sent to the model so it knows how to call the tool) with an invoke(Map) method that executes the call with parsed arguments.

Most authors don't implement this interface directly. Instead, write a class with Tool-annotated methods and call Tools.fromAnnotated(Object...) to get a CallableTool per method — that path builds the parameters JSON Schema for you. Implement this interface directly only when the set of tools — or their behavior — must be assembled dynamically at runtime; you are then responsible for constructing the parameters JsonObject schema yourself.

Example direct implementation:

public class GreetingTool implements CallableTool {

  private static final ToolDescription DESCRIPTION = describe();

  private static ToolDescription describe() {
    JsonObject params = new JsonObject();
    params.addProperty("type", "object");
    JsonObject props = new JsonObject();
    JsonObject name = new JsonObject();
    name.addProperty("type", "string");
    name.addProperty("description", "Name of the user to greet");
    props.add("name", name);
    params.add("properties", props);
    JsonArray required = new JsonArray();
    required.add("name");
    params.add("required", required);
    return new ToolDescription("greet", "Greets a user by name.", params);
  }

  @Override
  public ToolDescription getDescription() {
    return DESCRIPTION;
  }

  @Override
  public PermissionsConfig permissions() {
    return PermissionsConfig.DEFAULT;   // anyone who can reach the agent may greet
  }

  @Override
  public Object invoke(Map<String, Object> arguments) {
    return "Hello, " + arguments.get("name") + "!";
  }
}
  • Method Summary

    Modifier and Type
    Method
    Description
    Description of this tool, used to build the spec sent to the model.
    invoke(Map<String,Object> arguments)
    Execute the tool with arguments parsed from the model's request.
    default @Nullable String
    Identifies the source that contributed this tool, so two sources can each offer a tool with the same simple name.
    Security levels a caller must hold to see or run this tool.
  • Method Details

    • getDescription

      ToolDescription getDescription()
      Description of this tool, used to build the spec sent to the model.
    • namespace

      default @Nullable String namespace()
      Identifies the source that contributed this tool, so two sources can each offer a tool with the same simple name. When non-null, the AgenticHarness qualifies the name it advertises to the model with this value (for example ignition/tags and query become ignition_tags__query); the name in getDescription() stays the simple, user-facing one, and harness events report it unchanged.

      Return null, the default, for a tool whose name is already unique on its own.

    • permissions

      PermissionsConfig permissions()
      Security levels a caller must hold to see or run this tool. The AgenticHarness consults this against the run's AiActor twice: tools the actor fails are left out of what the model is told exists, and the check runs again on each call, so tightening this value takes effect even while a turn is in flight. A change to the caller's own grants lands on the next turn, when the harness re-resolves its actor.

      Read fresh on every consultation rather than captured, so an implementation backed by mutable configuration should resolve it here rather than in its constructor.

      Return PermissionsConfig.DEFAULT for a tool that any caller who can reach the agent may use — that is the right answer for most code-defined tools. There is deliberately no default implementation: an ungated tool should be a decision someone made, not a method someone didn't write, because the ungated value is allow-all and a silent one would ship open.

    • invoke

      Object invoke(Map<String,Object> arguments) throws Exception
      Execute the tool with arguments parsed from the model's request. Keys correspond to property names declared in ToolDescription.parameters(); values are JSON-parsed primitives (String, Number, Boolean). The return value is stringified by the harness for the model — a String is sent verbatim, anything else is JSON-encoded, and null is reported as "Success". Exceptions thrown from this method are caught by the harness and surfaced to the model as a tool-execution failure rather than aborting the conversation.
      Parameters:
      arguments - parsed tool arguments keyed by parameter name.
      Returns:
      the tool's result, to be stringified and sent back to the model.
      Throws:
      Exception - if the tool fails to execute; the harness reports the failure to the model.