tool.go

Overview

The tool.go file defines internal interfaces and fundamental logic for implementing tools within the system. These tools serve as modular components that can be invoked by agents or other parts of the system to perform specialized tasks or computations. This file is part of the internal tooling framework and establishes contracts for how tools should declare their capabilities and execute their logic in the context of agent interactions.

Interfaces

1. FunctionTool

type FunctionTool interface {
    tool.Tool
    Declaration() *genai.FunctionDeclaration
    Run(ctx tool.Context, args any) (result map[string]any, err error)
}

Description

FunctionTool extends the base tool.Tool interface and represents a tool that encapsulates a single function-like operation. It provides a structured declaration of its callable interface and permits execution with input arguments.

Methods

• Declaration()
  Returns a pointer to a genai.FunctionDeclaration, describing the function's signature, including its name, parameters, and documentation. This enables integration with LLMs and other components that require metadata about the tool's callable interface.

• Run(ctx tool.Context, args any) (map[string]any, error)
  Executes the tool's core logic using the supplied context and arguments.

  • ctx (tool.Context): Provides execution context, including logging, cancellation, and other runtime metadata.

  • args (any): Input arguments for the function call, typically unmarshaled from structured data.

  • Returns:

    • result (map[string]any): The output data produced by the tool, represented as a key-value map.

    • err (error): An error object if execution fails, or nil on success.

Usage Example

var myTool FunctionTool
declaration := myTool.Declaration()
// Pass input arguments as a map or structured type
result, err := myTool.Run(ctx, inputArgs)
if err != nil {
    // handle error
}
// process result

2. RequestProcessor

type RequestProcessor interface {
    ProcessRequest(ctx tool.Context, req *model.LLMRequest) error
}

Description

RequestProcessor defines an interface for processing large language model (LLM) requests. Implementers of this interface are responsible for handling or modifying requests before they are sent to the LLM backend or for performing side-effects related to the request.

Methods

• *ProcessRequest(ctx tool.Context, req model.LLMRequest) error
  Processes an incoming LLM request.

  • ctx (tool.Context): Execution context for managing lifecycle and metadata.

  • req (*model.LLMRequest): Pointer to the LLM request object that can be inspected or modified.

  • Returns:

    • error: Non-nil if processing fails, otherwise nil.

Usage Example

var processor RequestProcessor
err := processor.ProcessRequest(ctx, llmRequest)
if err != nil {
    // handle error
}

Implementation Details

• Both interfaces rely on the tool.Context type, which encapsulates runtime metadata and control mechanisms such as cancellation and logging. This aligns with the agent invocation lifecycle and context management described in Agent Invocation Context.

• FunctionTool integrates tightly with genai.FunctionDeclaration from the google.golang.org/genai package, indicating that these tools are designed to expose function signatures compatible with generative AI models, facilitating automatic schema inference and invocation as detailed in Function Tools.

• The RequestProcessor interface works on model.LLMRequest objects, which represent requests to language models. This positions it as a middleware or hook layer that can preprocess or analyze requests before further handling, relating to LLM Integration and Agents.

Interactions with Other Components

• Tool Interface (tool.Tool): Both FunctionTool and RequestProcessor build upon or relate to the broader tool.Tool interface, which defines the common behavior expected of all tools within the system. This interface is part of the tooling framework documented in Tooling System.

• LLM Requests (model.LLMRequest): The RequestProcessor interacts directly with request objects destined for large language models, indicating involvement in the agent workflow for interaction with LLMs, as covered in LLM Integration and Agents.

• Context (tool.Context): Provides the necessary execution context for tools and processors, linking to the lifecycle and callback management described in Agent Invocation Context and Agent Lifecycle and Callbacks.

Mermaid Diagram: Interface Structure for tool.go

classDiagram
class FunctionTool {
+Declaration()
+Run()
}
class RequestProcessor {
+ProcessRequest()
}
FunctionTool <|-- tool.Tool
RequestProcessor ..> model.LLMRequest
FunctionTool ..> genai.FunctionDeclaration
FunctionTool ..> tool.Context
RequestProcessor ..> tool.Context

This diagram illustrates the two main interfaces defined in the file, their key methods, and their relationships to other types such as tool.Tool, genai.FunctionDeclaration, tool.Context, and model.LLMRequest.