The documentation on Toolsets does not render working code

[agherasim]

Describe the Bug:
The documentation at https://adk.dev/tools-custom/#using-toolsets-with-agents, describing how to define Toolsets does not result in working code. A few problems:

• there is no name attribute to FunctionTool declaration, as the name is derived from the function or class __name__;
• the toolset is never called by the agent, and no get_tools method calls happen. This causes in the tools defined in toolset to not be found by agent and results in a fatal error.

Steps to Reproduce:
Please provide a numbered list of steps to reproduce the behavior:

1. Install google-akd
2. Create a new toolset, as described in the example
3. Create a new agent using agent.yaml definition, load agent in runner using from_config;
4. Import the toolset in the agent, using agent.yaml for definition

Expected Behavior:
The tools in the Toolset should be accessible to the agent defined in an agent.yaml.

Observed Behavior:
The tools defined in the Toolset cannot be found. When imported individually, the tools can be found and work as expected.

Environment Details:

• ADK Library Version (pip show google-adk): 1.31.1
• Desktop OS: macOS
• Python Version (python -V): Python 3.13.5

Model Information:

• Are you using LiteLLM: Yes
• Which model is being used: gemini-3.1-flash-lite-preview

---

🟡 Optional Information

Providing this information greatly speeds up the resolution process.

Minimal Reproduction Code:
Please provide a code snippet or a link to a Gist/repo that isolates the issue.

• see https://adk.dev/tools-custom/#example-a-simple-math-toolset

How often has this issue occurred?:

• Always (100%)

[AlejandroBlanco2001]

Hi @agherasim, after reviewing your issue, I can confirm the following:

• In the newer versions of the ADK, the code you shared does not work as expected. It contains some outdated imports and parameters that are no longer supported.
• Additionally, even if you have a working implementation for that ToolSet, the from_config method is currently not supported.

You can verify this in the base_toolset.py file:

@classmethod
def from_config(
    cls: Type[SelfToolset], config: ToolArgsConfig, config_abs_path: str
) -> SelfToolset:
    """Creates a toolset instance from a config.

    Args:
        config: The config for the tool.
        config_abs_path: The absolute path to the config file that contains the
            tool config.

    Returns:
        The toolset instance.
    """
    raise ValueError(f"from_config() not implemented for toolset: {cls}")

However, if you use the Python approach with agent.py, it works correctly. For example:

from google.adk.agents.llm_agent import Agent
from google.adk.models.lite_llm import LiteLlm
from google.adk.tools.function_tool import FunctionTool
from google.adk.tools.base_toolset import BaseToolset
from google.adk.tools.base_tool import BaseTool
from google.adk.tools.tool_context import ToolContext
from google.adk.agents.readonly_context import ReadonlyContext
import asyncio
from typing import List, Dict, Any, Optional

# 1. Define the individual tool functions
def add_numbers(a: int, b: int, tool_context: ToolContext) -> Dict[str, Any]:
    """Adds two integer numbers.
    Args:
        a: The first number.
        b: The second number.
    Returns:
        A dictionary with the sum, e.g., {'status': 'success', 'result': 5}
    """
    print(f"Tool: add_numbers called with a={a}, b={b}")
    result = a + b
    # Example: Storing something in tool_context state
    tool_context.state["last_math_operation"] = "addition"
    return {"status": "success", "result": result}


def subtract_numbers(a: int, b: int) -> Dict[str, Any]:
    """Subtracts the second number from the first.
    Args:
        a: The first number.
        b: The second number.
    Returns:
        A dictionary with the difference, e.g., {'status': 'success', 'result': 1}
    """
    print(f"Tool: subtract_numbers called with a={a}, b={b}")
    return {"status": "success", "result": a - b}


# 2. Create the Toolset by implementing BaseToolset
class SimpleMathToolset(BaseToolset):
    def __init__(self, prefix: str = "math_"):
        self.prefix = prefix
        super().__init__(tool_name_prefix=self.prefix)

        # Create FunctionTool instances once
        self._add_tool = FunctionTool(
            func=add_numbers,
        )
        self._subtract_tool = FunctionTool(
            func=subtract_numbers,
        )

        print(f"SimpleMathToolset initialized with prefix '{self.prefix}'")

    async def get_tools(
        self, readonly_context: Optional[ReadonlyContext] = None
    ) -> List[BaseTool]:
        print("SimpleMathToolset.get_tools() called.")
        # Example of dynamic behavior:
        # Could use readonly_context.state to decide which tools to return
        # For instance, if readonly_context.state.get("enable_advanced_math"):
        #    return [self._add_tool, self._subtract_tool, self._multiply_tool]

        # For this simple example, always return both tools
        tools_to_return = [self._add_tool, self._subtract_tool]
        print(f"SimpleMathToolset providing tools: {[t.name for t in tools_to_return]}")
        return tools_to_return # type: ignore

    async def close(self) -> None:
        # No resources to clean up in this simple example
        print(f"SimpleMathToolset.close() called for prefix '{self.prefix}'.")
        await asyncio.sleep(0)  # Placeholder for async cleanup if needed


# 3. Define an individual tool (not part of the toolset)
def greet_user(name: str = "User") -> Dict[str, str]:
    """Greets the user."""
    print(f"Tool: greet_user called with name={name}")
    return {"greeting": f"Hello, {name}!"}


greet_tool = FunctionTool(func=greet_user)

# 4. Instantiate the toolset
math_toolset_instance = SimpleMathToolset(prefix="calculator_")

# 5. Define an agent that uses both the individual tool and the toolset
root_agent = Agent(
    name="CalculatorAgent",
    model=model,
    instruction="You are a helpful calculator and greeter. "
    "Use 'greet_user' for greetings. "
    "Use 'calculator_add_numbers' to add and 'calculator_subtract_numbers' to subtract. "
    "Announce the state of 'last_math_operation' if it's set.",
    tools=[greet_tool, math_toolset_instance],  # Individual tool  # Toolset instance
)

A couple of important notes:

• Calling the parent class constructor helps resolve issues related to missing attributes.
• Passing tool_name_prefix ensures that tool names are automatically prefixed when registered within the toolset.

I will submit a PR to update the documentation accordingly. Thanks for raising this

[AlejandroBlanco2001]

PR with the docs updated: google/adk-docs#1697

[llalitkumarrr]

Hello @agherasim ,
Thank you for raising this issue. We were able to reproduce it and observed the same behavior. The solution shared by @AlejandroBlanco2001 should solve the problem. Please give it a try and feel free to reach out if you need any further assistance.

@AlejandroBlanco2001, thank you for your input and contribution.👍

[agherasim]

thanks @AlejandroBlanco2001 for updating the docs. Indeed, the main problem seems to be the config loader, that does not instantiate properly the tools -- same effect was observed with MCPToolset.

The yaml config loader is super useful to separate agent configuration / definition from application logic, and it's unfortunate it doesn't support all use cases. Additionally, dropping yaml config loader means I need to drop support for the agent visual builder UI, something a non-engineering person could use to further develop the agents. I built a custom agent loader that preserves the yaml file configuration while ensuring all instances for callbacks, tools and toolsets are instantiated correctly.

Would this be of interest for the framework?

[llalitkumarrr]

Hello @agherasim ,

If you wish to contribute, we recommend opening a new issue. From my understanding, this current issue can now be closed as we already have a solution for the mentioned problem. Please let us know if you need any additional support with this specific topic.

[adk-bot]

This issue has been automatically marked as stale because it has not had recent activity for 7 days after a maintainer requested clarification. It will be closed if no further activity occurs within 7 days.

[adk-bot]

This has been automatically closed because it has been marked as stale for over 7 days.