Tooling System

The Tooling System provides a modular framework defining various tools callable by AI agents or large language models (LLMs). It enables agents to extend their capabilities by invoking specialized functionalities such as executing Go functions, loading artifacts, performing web searches, or integrating with external protocols like MCP (Model Context Protocol). This modularity allows flexible composition of AI workflows and enriches the agent's interaction with external data and services.

Core Concepts and Purpose

At its core, the Tooling System abstracts "tools" as callable units of functionality that agents or LLMs can invoke during their operation. Each tool encapsulates a specific task or interface to an external system. The framework supports diverse tool types, including:

• Function Tools: Wrap native Go functions with typed inputs and outputs, exposing them as callable tools with JSON schema validation.

• Artifact Loading Tool: Enables agents to load and access artifacts (files, blobs) stored in the system, informing the LLM about available artifacts and retrieving their content on demand.

• Google Search Tool: Leverages Gemini 2 LLM native capabilities to perform web searches.

• MCP Toolset Integration: Integrates Model Context Protocol tools over MCP servers, extending agent capabilities with external MCP tools.

• Agent Tools: Compose sub-agents as tools, allowing hierarchical agent invocation.

• Exit Loop Tool: Provides a mechanism for agents to exit iterative workflows or loops.

This system solves the problem of connecting AI agents with external data, services, and sub-agents in a clean, extensible, and schema-validated manner, enabling dynamic, context-aware AI workflows.

Structure and Functionality

Tool Interface and Context

All tools implement the tool.Tool interface defining:

• Name() — tool identifier.

• Description() — human-readable description.

• IsLongRunning() — flag indicating if the tool involves long-running operations.

Tools receive a tool.Context when invoked, which provides:

• Access to invocation-specific data.

• Methods to interact with session state, artifacts, and memory.

• Facilities to modify agent state or trigger workflow actions.

Toolsets

A tool.Toolset is a collection of related tools, allowing grouping and dynamic exposure of tools based on the current invocation context.

Function Tools

Function tools wrap Go functions, providing a seamless way to expose typed functionality to agents and LLMs.

• Defined in the functiontool package.

• Use Go generics to specify input (TArgs) and output (TResults) types.

• Automatically infer or accept JSON schema for input/output validation.

• Provide function declarations used for LLM function call integration.

• Support synchronous or long-running operations.

Example usage includes creating a tool that sums two integers or retrieves weather information based on city input.

The function tool implementation handles:

• Marshaling/unmarshaling arguments according to JSON schema.

• Running the underlying Go function.

• Returning results in a map format suitable for LLM consumption.

This pattern enables robust, schema-driven tooling with minimal boilerplate.

Artifact Loading Tool

The artifact loading tool (loadartifactstool package) allows agents and LLMs to interact with stored artifacts such as files or blobs.

Key features include:

• Informing the LLM about available artifacts via appended instructions in the request.

• Handling LLM function calls (load_artifacts) to fetch artifact contents dynamically.

• Concurrently loading multiple artifact contents using goroutines for efficiency.

• Appending artifact contents back into the LLM request to provide context for downstream processing.

This tool tightly integrates with the artifact service and session management, enabling agents to answer queries or perform reasoning based on persistent external data.

Google Search Tool

The geminitool package provides access to Google Search as a built-in tool for Gemini 2 models.

• The GoogleSearch tool is automatically invoked by Gemini models for web search.

• It does not require local code execution; rather, it leverages native model capabilities.

• The tool is added to the LLM request's toolset configuration to enable search functionality.

This tool provides external knowledge retrieval without explicit API calls in the agent code.

MCP Toolset Integration

The MCP toolset (mcptoolset package) bridges the ADK with external MCP servers, allowing agents to call MCP tools as if they were native.

• Lazily creates and maintains an MCP client session.

• Retrieves MCP tools from the server and converts them into ADK tools.

• Filters tools based on configurable predicates.

• Supports invoking MCP tools via the MCP protocol, handling sessions and responses.

• Converts MCP call results into ADK-compatible map outputs for LLM consumption.

This integration enables seamless extension of agent capabilities through the MCP ecosystem.

Agent Tools

Agent tools (agenttool package) wrap sub-agents as callable tools.

• Allow an agent to invoke another agent as a tool.

• Support input/output validation via agent input/output schemas.

• Run the sub-agent within a new session context, forwarding state as appropriate.

• Collect and return the sub-agent's final output as the tool's result.

• Support configuration flags like skipping summarization after sub-agent execution.

• Add function declarations to LLM requests to expose the sub-agent interface.

This composition pattern supports modular, hierarchical AI workflows.

Exit Loop Tool

The exit loop tool (exitlooptool package) provides a mechanism for agents to exit looping workflows.

• Implemented as a function tool with no input arguments.

• When called, triggers an action (Escalate) to break out of loops.

• Skips unnecessary summarization in the loop context.

• Used primarily with loop workflow agents to control iteration termination.

Interactions and Workflow

Agents invoke tools during LLM generation cycles. The typical interaction sequence is:

1. Tool Inclusion: Each tool registers its function declaration and capabilities into the LLM request (ProcessRequest).

2. LLM Request: The agent sends a prompt with tool declarations to the LLM.

3. Function Call Detection: If the LLM issues a function call (e.g., to a function tool or artifact loader), the agent calls the corresponding tool's Run method.

4. Tool Execution: The tool performs its logic—executing native functions, loading artifacts, querying MCP servers, or invoking sub-agents.

5. Response Handling: The tool returns results, which are appended to the conversation and used to generate further LLM responses.

6. Loop Control: Tools like the exit loop tool can modify session actions to influence agent workflow (e.g., exit loops).

These interactions tightly couple the tooling system with the agent lifecycle, session state, artifact management, and external protocols.

File and Package Relationships

• tool/tool.go: Defines the core Tool and Toolset interfaces and predicates for filtering tools.

• tool/functiontool/: Implements function tools that wrap Go functions with schema-driven interfaces.

• tool/loadartifactstool/: Implements artifact loading tool, interacting with artifact services and LLM requests.

• tool/geminitool/: Provides Gemini-native tools, including the Google Search tool.

• tool/mcptoolset/: Implements MCP toolset integration with MCP servers.

• tool/agenttool/: Wraps agents as tools, enabling agent composition.

• tool/exitlooptool/: Implements exit loop functionality as a function tool.

Each tool package implements the tool.Tool interface and integrates with the agent invocation context (tool.Context) and request lifecycle.

Visualization of Tool Invocation Flow

sequenceDiagram
participant Agent
participant ToolingSystem
participant LLMModel
participant ArtifactService
participant MCPServer
participant SubAgent
Agent->>ToolingSystem: Initialize LLM Request with Tools
ToolingSystem->>LLMModel: Send Request
LLMModel->>Agent: Return Response (may include Function Call)
alt Function Call Detected
Agent->>ToolingSystem: Invoke Tool.Run()
alt Function Tool
ToolingSystem->>Agent: Execute Go Function
Agent-->>ToolingSystem: Return Function Result
else Artifact Loading Tool
ToolingSystem->>ArtifactService: Load Artifact(s)
ArtifactService-->>ToolingSystem: Return Content
else MCP Tool
ToolingSystem->>MCPServer: Call MCP Tool
MCPServer-->>ToolingSystem: Return Result
else Agent Tool
ToolingSystem->>SubAgent: Run Sub-Agent Session
SubAgent-->>ToolingSystem: Return Output
end
ToolingSystem->>Agent: Return Tool Result
Agent->>LLMModel: Append Result and Continue Generation
else No Function Call
Agent->>Agent: Process Final Output
end

Summary of Subtopics

For detailed information on specific tool implementations, refer to:

• Function Tools

• Artifact Loading Tool

• Google Search Tool

• MCP Toolset Integration

• Agent Tools

• Exit Loop Tool