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

Tool

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

A tool with a no-metadata execute shape. The runtime dispatches it through ToolBase.execute; this subclass's final override forwards to execute and discards any per-call ToolCallMetadata supplied by the caller or contributed by features.

Existing tool implementations subclass this type. Implementations that need typed access to the live AIAgentContext should extend ai.koog.agents.core.agent.tools.AgentContextAwareTool (in agents-core) instead; implementations that need raw ToolCallMetadata entries (for example a tracing span id contributed by a feature) should extend ToolBase directly.

Type Parameters

TArgs

The type of arguments the tool accepts.

TResult

The type of result the tool returns.

Inheritors

SimpleTool

ToolFromCallable

Constructors

Tool

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): TResult

Executes the tool's logic with the provided arguments.

suspend override 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.