toolutils.go

Overview

The toolutils.go file provides internal utility functionality for managing and consolidating tool definitions within requests to large language model (LLM) integrations. It focuses on handling multiple function-based tools by aggregating their function declarations into a single tool representation compatible with the underlying LLM configuration. This consolidation ensures that multiple tools exposing functions can coexist without conflicts in the LLM request configuration.

The file defines the Tool interface and the key function PackTool which modifies an LLMRequest to register and merge tools' function declarations.

Package and Imports

• Package: toolutils — defines internal-only interfaces and logic for tools.

• Imports:

  • fmt for error formatting.

  • google.golang.org/genai — provides types related to function declarations and tool configurations for LLM generation.

  • google.golang.org/adk/model — defines the LLMRequest type used to structure requests to the LLM.

Types

Tool Interface

type Tool interface {
	Name() string
	Declaration() *genai.FunctionDeclaration
}

• Purpose: Represents a generic tool that can be attached to an LLM request.

• Methods:

  • Name() returns the unique string identifier for the tool.

  • Declaration() returns a pointer to a genai.FunctionDeclaration representing the tool's function schema for LLM integration. May return nil if the tool does not provide any function declaration.

Functions

PackTool

func PackTool(req *model.LLMRequest, tool Tool) error

• Purpose: Integrates a given Tool into the provided LLMRequest. Manages consolidation of multiple function-based tools into a single genai.Tool with aggregated function declarations.

• Parameters:

  • req *model.LLMRequest: The LLM request object to update with the tool.

  • tool Tool: The tool to add to the request.

• Returns:

  • error if a tool with the same name already exists in the request or if any internal error occurs.

  • nil on success.

Detailed Behavior

1. Initialize Tool Map: If req.Tools is nil, it initializes it as a map to hold registered tools keyed by their name.

2. Duplicate Check: Checks if a tool with the same name already exists in req.Tools. If yes, returns an error to prevent duplicates.

3. Register Tool: Adds the tool to the req.Tools map.

4. Initialize Config: Ensures req.Config is initialized (of type genai.GenerateContentConfig) for LLM tool configuration.

5. Function Declaration Handling:

   • If the tool's Declaration() returns nil, no further action is taken.

   • Searches existing tools in req.Config.Tools for one that already contains function declarations.

   • If none exist, creates a new genai.Tool with the function declaration from the tool and appends it to req.Config.Tools.

   • If a function tool exists, appends the tool's function declaration to its FunctionDeclarations slice.

Usage Example

var req model.LLMRequest
myTool := NewMyFunctionTool() // implements Tool interface
err := PackTool(&req, myTool)
if err != nil {
    log.Fatalf("Failed to pack tool: %v", err)
}
// req now contains the packed tool with function declarations merged

Implementation Details and Algorithms

• The logic avoids conflicts by ensuring no duplicate tools with the same name are registered.

• It consolidates multiple function-based tools into a single genai.Tool to comply with the expected LLM interface, which requires function declarations to be grouped.

• Uses simple linear search to find the existing genai.Tool with function declarations, as typically the number of tools per request is small.

• Defensive initialization of maps and pointers ensures the caller does not have to prepare the request fully before calling PackTool.

Interaction with Other System Components

• LLMRequest (model.LLMRequest): This file operates on the request object sent to the LLM, injecting tools and their function declarations into the request configuration.

• genai Package: Utilizes genai.FunctionDeclaration and genai.GenerateContentConfig structs to build the tool declarations understood by the LLM backend.

• Tools implementing the Tool interface are expected to be defined elsewhere in the system, potentially wrapping various functional capabilities or sub-agent logic.

• This utility supports higher-level agent and tool management workflows described in the broader Tooling System and LLM Integration and Agents topics by enabling multiple function tools to be composed cleanly in a single LLM request.

Mermaid Diagram: Flowchart of PackTool Function Workflow

flowchart TD
Start["Start: PackTool called"]
CheckToolsNil{"req.Tools is nil?"}
InitTools["Initialize req.Tools map"]
CheckDuplicate{"Tool name exists in req.Tools?"}
ReturnError["Return error: duplicate tool"]
AddTool["Add tool to req.Tools"]
CheckConfigNil{"req.Config is nil?"}
InitConfig["Initialize req.Config"]
GetDecl["Get tool.Declaration()"]
DeclNil{"Declaration is nil?"}
FindFuncTool["Search req.Config.Tools for funcTool"]
FuncToolFound{"funcTool found?"}
AppendDecl["Append declaration to funcTool.FunctionDeclarations"]
CreateFuncTool["Create new genai.Tool with declaration and append"]
ReturnNil["Return nil (success)"]
Start --> CheckToolsNil
CheckToolsNil -- Yes --> InitTools --> CheckDuplicate
CheckToolsNil -- No --> CheckDuplicate
CheckDuplicate -- Yes --> ReturnError
CheckDuplicate -- No --> AddTool --> CheckConfigNil
CheckConfigNil -- Yes --> InitConfig --> GetDecl
CheckConfigNil -- No --> GetDecl
GetDecl --> DeclNil
DeclNil -- Yes --> ReturnNil
DeclNil -- No --> FindFuncTool
FindFuncTool --> FuncToolFound
FuncToolFound -- Yes --> AppendDecl --> ReturnNil
FuncToolFound -- No --> CreateFuncTool --> ReturnNil

End of toolutils.go Documentation