tool.go

Overview

The tool.go file in the geminitool package provides a lightweight wrapper enabling integration of Gemini-native tools, specifically those defined via the genai API, into the agent tooling framework. It exposes a factory function New to create tools compatible with the generic tool.Tool interface, allowing Gemini tools such as Google Search or data retrieval endpoints to be seamlessly included in LLM requests.

This file’s primary purpose is to bridge Gemini tools (genai.Tool) with the broader agent tooling system by wrapping them in a struct that implements the tool.Tool interface. The wrapped tools can then be attached to LLM generation requests, making their capabilities available during LLM execution without requiring local implementation of the tool logic.

Entities and Functions

New(name string, t *genai.Tool) tool.Tool

• Purpose:
  Factory function creating a new Gemini tool wrapper implementing the tool.Tool interface.

• Parameters:

  • name (string): Identifier/name of the tool instance.

  • t (*genai.Tool): Pointer to a Gemini-native tool definition.

• Returns:
  An instance of tool.Tool wrapping the given Gemini tool.

• Usage Example:

  geminiRetrieval := &genai.Tool{
      Retrieval: &genai.Retrieval{
          ExternalAPI: &genai.ExternalAPI{
              Endpoint: "https://api.example.com/data",
              AuthConfig: someAuthConfig,
          },
      },
  }
  tool := geminitool.New("data_retrieval", geminiRetrieval)
  

type geminiTool

• Description:
  Private struct wrapping a genai.Tool instance and implementing the tool.Tool interface.

• Fields:

  • name string: Tool name as identifier.

  • value *genai.Tool: Pointer to the underlying Gemini tool configuration.

• Methods:

  • ProcessRequest(ctx tool.Context, req *model.LLMRequest) error
    Adds the wrapped Gemini tool configuration into the LLM request’s toolset.

    • Parameters:

      • ctx (tool.Context): Invocation context providing lifecycle data and utilities.

      • req (*model.LLMRequest): Pointer to the LLM request being built.

    • Returns:

      • error: Non-nil if the request is invalid (e.g., nil request).

    This method ensures that the Gemini tool is registered with the LLM request so that the Gemini model can invoke it natively during generation.

  • Name() string
    Returns the tool’s name.

  • Description() string
    Returns a fixed description string indicating it performs Google search to retrieve information from the web. Note that despite the generic wrapper, this description is static and may be specific to the Google Search tool use case.

  • IsLongRunning() bool
    Returns false, indicating the tool does not represent a long-running operation.

func setTool(req *model.LLMRequest, t *genai.Tool) error

• Description:
  Helper function that appends a Gemini tool configuration to the Tools slice in the LLM request’s generate content config.

• Parameters:

  • req (*model.LLMRequest): The LLM request to which the tool will be added.

  • t (*genai.Tool): Gemini tool configuration to append.

• Returns:

  • error: If req is nil, returns an error indicating the request is invalid.

• Implementation Details:

  • Initializes req.Config if nil to ensure safe appending.

  • Appends the tool to req.Config.Tools.

Important Implementation Details

• The geminiTool struct acts as an adapter allowing Gemini-native genai.Tool instances to be used wherever the tool.Tool interface is expected by the agent system.

• The ProcessRequest method is the key integration point: it injects the Gemini tool configuration directly into the LLM request's toolset, enabling Gemini models to utilize the tool during generation.

• The wrapper provides static metadata such as the tool’s name and description to comply with the tool.Tool interface, even though the underlying tool behavior is handled natively by Gemini.

• The IsLongRunning method returns false to indicate that invoking this tool does not require special asynchronous or long-duration handling by the agent system.

• Error handling in setTool validates that the LLM request is non-nil before injection to prevent runtime panics.

Interaction with Other System Components

• The geminitool package depends on the genai package (Gemini API client definitions) for its underlying tool representations.

• It imports model for the LLM request structure and tool for the tool.Tool interface definitions.

• This package is designed to be used by agents or workflows that construct LLM requests (model.LLMRequest) and want to include Gemini-native tools such as Google Search or custom retrieval APIs.

• When an agent calls ProcessRequest on a geminiTool instance during request preparation, the Gemini tool configuration is attached, enabling the Gemini LLM to invoke that tool seamlessly during the generation phase.

• This design integrates tightly with the broader Tooling System and supports Gemini-specific tooling capabilities, complementing function tools, artifact loaders, and other tool types.

Diagram: Class Structure and Method Overview

classDiagram
class geminiTool {
- name: string
- value: *genai.Tool
+ ProcessRequest(ctx, req) error
+ Name() string
+ Description() string
+ IsLongRunning() bool
}
geminiTool ..> genai.Tool : wraps
geminiTool ..|> tool.Tool : implements

Summary

• tool.go provides a minimal adapter that wraps Gemini-native tools (genai.Tool) for use with the agent tooling framework's tool.Tool interface.

• It allows tools to be added to LLM requests, letting Gemini models invoke these tools natively during text generation.

• The static description and non-long-running flag indicate this wrapper is primarily intended for direct Gemini tool integration like Google Search.

• This file is a fundamental bridge between Gemini's native tooling ecosystem and the agent’s modular tooling system, facilitating expanded capabilities with minimal local logic.

For more on how tools integrate with agent workflows and LLM requests, see the Tooling System and LLM Integration and Agents topics. For specific tool types, the Google Search Tool subtopic provides context on Gemini’s native search tooling.