agents-core/ai.koog.agents.core.agent.tools/AgentContextAwareTool

AgentContextAwareTool

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

A tool whose execute receives the live AIAgentContext driving the current call.

The framework injects the context under AgentContextKey in ToolCallMetadata before dispatch (see ai.koog.agents.core.environment.ContextualAgentEnvironment). This subclass reads that entry and forwards it to the user-facing overload, so implementors get a typed AIAgentContext parameter rather than a Map lookup.

Use this when a tool needs the agent's full state (LLM context, run id, configuration, storage, ...). For tools that only need the typed arguments, extend Tool instead; for tools that read raw ToolCallMetadata entries contributed by features (for example a trace span id), extend ToolBase directly.

Invoking an AgentContextAwareTool outside an agent run is a programming error: with no AgentContextKey entry in the metadata, execute throws IllegalStateException naming the tool. Tests that need to exercise such a tool can construct metadata via ToolCallMetadata.of(AgentContextAwareTool.AgentContextKey to context) or call execute(args, context) directly.

Type Parameters

TArgs

The type of arguments the tool accepts.

TResult

The type of result the tool returns.

Constructors

AgentContextAwareTool

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.