agents-tools/ai.koog.agents.core.tools/ToolBase

ToolBase

abstract class ToolBase<TArgs, TResult>(val argsType: TypeToken, val resultType: TypeToken, val descriptor: ToolDescriptor, val metadata: Map<String, String> = emptyMap())(source)

The runtime contract that every tool dispatched by the agent satisfies.

The agent runtime invokes execute uniformly, threading caller- and feature-supplied ToolCallMetadata alongside the typed TArgs. Subclasses define what that overload means:

Tool is the conventional shape with an Tool.execute taking only the arguments. Existing subclasses keep working unchanged.
ai.koog.agents.core.agent.tools.AgentContextAwareTool (in agents-core) gives the implementation typed access to the live AIAgentContext driving the current call.

A subclass that needs raw ToolCallMetadata (for example to read a trace span id contributed by a feature) can extend ToolBase directly and override execute. Splitting that concern from the agent-context concern keeps agents-tools free of any agents-core dependency.

Type Parameters

TArgs

The type of arguments the tool accepts.

TResult

The type of result the tool returns.

Inheritors

Tool

Constructors

ToolBase

constructor(argsType: TypeToken, resultType: TypeToken, descriptor: ToolDescriptor, metadata: Map<String, String> = emptyMap())

constructor(argsType: TypeToken, resultType: TypeToken, name: String, description: String, jsonSchemaConfig: JsonSchemaConfig = defaultJsonSchemaConfig)

Convenience constructor that generates ToolDescriptor from the provided name, description and argsType.

Properties

argsType

val argsType: TypeToken

Type token representing arguments type TArgs.

descriptor

val descriptor: ToolDescriptor

A ToolDescriptor representing the tool's schema, including its name, description, and parameters.

metadata

val metadata: Map<String, String>

A map of static metadata associated with the tool. Distinct from the per-call ToolCallMetadata threaded into execute; this field describes the tool, not the invocation.

name

val name: String

The name of the tool from the descriptor.

resultType

val resultType: TypeToken

Type token representing result type TResult.

Functions

decodeArgs

open fun decodeArgs(rawArgs: JSONObject, serializer: JSONSerializer): TArgs

Decodes the provided raw JSON arguments into an instance of the specified arguments type.

decodeResult

open fun decodeResult(rawResult: JSONElement, serializer: JSONSerializer): TResult

Decodes the provided raw JSON element into an instance of the specified result type.

encodeArgs

open fun encodeArgs(args: TArgs, serializer: JSONSerializer): JSONObject

Encodes the given arguments into a JSON representation.

encodeArgsToString

fun encodeArgsToString(args: TArgs, serializer: JSONSerializer): String

Encodes the provided arguments into a JSON string representation.

encodeArgsToStringUnsafe

fun encodeArgsToStringUnsafe(args: Any?, serializer: JSONSerializer): String

Encodes the provided arguments into a JSON string representation without type safety checks.

encodeArgsUnsafe

fun encodeArgsUnsafe(args: Any?, serializer: JSONSerializer): JSONObject

Encodes the given arguments into a JSON representation without type safety checks.

encodeResult

open fun encodeResult(result: TResult, serializer: JSONSerializer): JSONElement

Encodes the given result into a JSON representation.

encodeResultToString

open fun encodeResultToString(result: TResult, serializer: JSONSerializer): String

Encodes the given result of type TResult to its string representation. This is used to provide the LLM with the result of the tool execution. It can be overridden to customize the string representation the LLM will see.

encodeResultToStringUnsafe

fun encodeResultToStringUnsafe(result: Any?, serializer: JSONSerializer): String

Encodes the provided result object into a JSON string representation without type safety checks.

encodeResultUnsafe

fun encodeResultUnsafe(result: Any?, serializer: JSONSerializer): JSONElement

Encodes the given result object into a JSON representation without type safety checks.

execute

abstract suspend fun execute(args: TArgs, metadata: ToolCallMetadata): TResult

Executes the tool's logic with the provided arguments and per-call metadata.

executeUnsafe

suspend fun executeUnsafe(args: Any?): TResult

Executes the tool with the provided arguments without type safety checks.

suspend fun executeUnsafe(args: Any?, metadata: ToolCallMetadata): TResult

Executes the tool with the provided arguments and metadata without type safety checks.