tool.go

Overview

The tool.go file defines the foundational interfaces and types for the modular tooling system within the agent framework. It specifies abstractions for tools—discrete functional components callable by an agent—and their associated invocation context and grouping constructs.

Tools encapsulate specific tasks or operations that an agent can invoke during execution, enabling extensible integration of functionalities such as external API calls, sub-agent invocation, artifact loading, or other domain-specific capabilities.

This file provides the core contracts that all tools and tool collections must implement to participate in the agent's tooling ecosystem, establishing the interaction patterns between tools, the agent's runtime context, and session state.

Detailed Explanations

Interfaces

Tool

type Tool interface {
	Name() string
	Description() string
	IsLongRunning() bool
}

• Purpose: Represents a callable unit of work or functionality that an agent can invoke.

• Methods:

  • Name() string
    Returns the unique identifier of the tool. Used for referencing and invocation.

  • Description() string
    Provides a human-readable explanation of the tool's purpose.

  • IsLongRunning() bool
    Indicates whether the tool execution is long-running. Long-running tools typically return a resource or operation ID initially and complete asynchronously later.

• Usage Example:
  A Google Search tool would implement this interface, returning "GoogleSearch" as the name, a description like "Performs Google web search", and false for IsLongRunning() since it executes quickly.

Context

type Context interface {
	agent.CallbackContext
	FunctionCallID() string
	Actions() *session.EventActions
	SearchMemory(context.Context, string) (*memory.SearchResponse, error)
}

• Purpose: Provides the runtime invocation context passed to tools when executed. It extends from agent.CallbackContext and adds tool-specific context capabilities.

• Methods:

  • FunctionCallID() string
    Returns the unique identifier for the function call triggering this tool invocation, enabling correlation and tracking within the agent lifecycle.

  • Actions() *session.EventActions
    Returns a modifiable object representing actions that the tool can perform on the current event, such as state modifications, agent transfers, or escalation.

  • SearchMemory(context.Context, string) (*memory.SearchResponse, error)
    Allows tools to perform semantic searches against the agent's persistent memory store, enabling context-aware information retrieval.

• Implementation Note:
  This interface tightly integrates with other core components such as session state (session.EventActions), memory management, and agent callbacks, allowing tools to modify or query the agent's environment dynamically.

Toolset

type Toolset interface {
	Name() string
	Tools(ctx agent.ReadonlyContext) ([]Tool, error)
}

• Purpose: Defines a collection or group of related tools that can be provided to an agent as a unified set.

• Methods:

  • Name() string
    Returns the toolset's name, useful for identification, logging, or configuration.

  • Tools(ctx agent.ReadonlyContext) ([]Tool, error)
    Returns the list of tools contained in the toolset. The method receives a read-only invocation context, allowing dynamic filtering or tool selection based on the current agent state or permissions.

• Usage Example:
  A "Standard Tools" toolset may bundle tools like Google Search, Artifact Loader, and Function Tools, exposing them collectively to the agent.

Predicate and StringPredicate

type Predicate func(ctx agent.ReadonlyContext, tool Tool) bool

• Purpose: A function type that determines whether a specific tool should be exposed or allowed in the current invocation context.

• Usage:
  Predicates are used for dynamic filtering of tools based on runtime conditions such as user permissions, session state, or configuration flags.

func StringPredicate(allowedTools []string) Predicate

• Purpose: Helper function that creates a Predicate based on an explicit allowlist of tool names.

• Parameters:

  • allowedTools []string — Slice of tool names permitted.

• Returns:
  A Predicate function that returns true if the tool's name is in the allowed list, otherwise false.

• Example Usage:

  allowed := []string{"GoogleSearch", "LoadArtifact"}
  pred := StringPredicate(allowed)
  // pred can then be used to filter tools in a Toolset implementation
  

Important Implementation Details

• The Tool interface is minimalistic, intentionally abstracting the implementation details of tools. This supports wide variety of tool types, including synchronous functions, asynchronous long-running operations, and external service proxies.

• Context extends agent.CallbackContext, thus inheriting invocation lifecycle hooks and allowing rich interaction with agent state and memory.

• Toolset returns tools dynamically, enabling context-dependent exposure of tool capabilities.

• Predicates provide a flexible mechanism for tool gating without hardcoding logic inside tool implementations.

• The semantic memory search method in Context allows tools to access and leverage the agent's accumulated knowledge, integrating external information retrieval tightly with tool execution.

Interaction with Other System Components

• Tools are invoked by agents based on LLM function call detection or workflow logic (LLM Integration and Agents).

• The Context interface integrates with session management and event processing (Agent Invocation Context, Session Management).

• Tools can trigger state changes or agent transfers via session.EventActions, impacting agent lifecycle and workflows (Agent Lifecycle and Callbacks, Agent Workflow Management).

• Toolsets organize tools for agents, supporting modular composition and dynamic capability exposure (Tooling System).

• Predicates filter tools exposed to LLMs or agents, ensuring security and contextual appropriateness (LLM Integration and Agents).

Visual Diagram: Tooling System Structure in tool.go

classDiagram
class Tool {
+Name()
+Description()
+IsLongRunning()
}
class Context {
+FunctionCallID()
+Actions()
+SearchMemory()
}
class Toolset {
+Name()
+Tools()
}
class Predicate
class StringPredicate
Tool <|.. Toolset : provides >
Context <|.. Tool : passed to >
Predicate <.. StringPredicate : creates >

This diagram illustrates the core interfaces and their relationships:

• Tool is the primary interface implemented by all tools.

• Context is passed to tools during invocation, providing runtime information and actions.

• Toolset groups multiple Tool instances and provides them based on context.

• Predicate functions are used to filter or gate tools, with StringPredicate as a helper constructor.

Usage Examples and Scenarios

Implementing a Custom Tool

To implement a custom tool, define a struct satisfying the Tool interface:

type MyTool struct {}

func (t *MyTool) Name() string {
    return "MyCustomTool"
}

func (t *MyTool) Description() string {
    return "Performs a specialized operation."
}

func (t *MyTool) IsLongRunning() bool {
    return false
}

This tool can then be included in a Toolset or registered directly with an agent.

Filtering Tools with StringPredicate

When providing tools dynamically, a Predicate can be used to restrict exposure:

allowed := []string{"MyCustomTool", "GoogleSearch"}
filter := StringPredicate(allowed)

tools, err := toolset.Tools(ctx)
filtered := []Tool{}
for _, tool := range tools {
    if filter(ctx, tool) {
        filtered = append(filtered, tool)
    }
}

Accessing Invocation Context in a Tool

Within long-running or stateful tools, the Context interface allows:

• Obtaining the function call ID for logging or tracking.

• Modifying the agent's event actions for state changes or workflow control.

• Querying agent memory with semantic searches to inform tool logic.

References to Related Topics

• The runtime Context and its integration with agent lifecycle and session management is detailed in Agent Invocation Context.

• Tool grouping and filtering using Toolset and Predicate relate to the broader Tooling System.

• Agent and LLM interaction with tools is described in LLM Integration and Agents.

• Session and event action integration with tools is covered under Session Management and Agent Lifecycle and Callbacks.