execute

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

This is the single dispatch entry point used by the agent runtime. metadata is an additive side channel for cross-cutting context (for example a tracing span id or a correlation id); it is not part of the argument schema and is not exposed to the LLM.

Most tools should extend Tool (which provides a no-metadata execute(args) shape) or ai.koog.agents.core.tools.AgentContextAwareTool (which provides typed access to the live AIAgentContext) rather than overriding this overload directly. Override here only when you need to read raw ToolCallMetadata entries.

In the actual agent implementation, it is not recommended to call tools directly as this might cause issues, such as:

• Bugs with feature pipelines

• Inability to test/mock

Consider using methods like findTool(tool: Class) or similar, to retrieve a SafeTool, and then call execute on it. This ensures that the tool call is delegated properly to the underlying environment object.

Parameters