Interface CallableTool
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 TypeMethodDescriptionDescription of this tool, used to build the spec sent to the model.Execute the tool with arguments parsed from the model's request.default @Nullable StringIdentifies 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
Identifies the source that contributed this tool, so two sources can each offer a tool with the same simple name. When non-null, theAgenticHarnessqualifies the name it advertises to the model with this value (for exampleignition/tagsandquerybecomeignition_tags__query); the name ingetDescription()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. TheAgenticHarnessconsults this against the run'sAiActortwice: 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.DEFAULTfor 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
Execute the tool with arguments parsed from the model's request. Keys correspond to property names declared inToolDescription.parameters(); values are JSON-parsed primitives (String,Number,Boolean). The return value is stringified by the harness for the model — aStringis sent verbatim, anything else is JSON-encoded, andnullis 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.
-