Chapter 4: Tool / ToolCollection - Giving Your Agent Skills

In Chapter 3: BaseAgent - The Agent Blueprint, we learned how BaseAgent provides the standard structure for our agents, including a brain (LLM) and memory (Message / Memory). But what if we want our agent to do more than just think and remember? What if we want it to act in the world – like searching the web, running code, or editing files?

This is where Tools come in!

What Problem Do They Solve?

Imagine an agent trying to answer the question: “What’s the weather like in Tokyo right now?”

The agent’s LLM brain has a lot of general knowledge, but it doesn’t have real-time access to the internet. It can’t check the current weather. It needs a specific capability or skill to do that.

Similarly, if you ask an agent to “Write a python script that prints ‘hello world’ and save it to a file named hello.py,” the agent needs the ability to:

  1. Understand the request (using its LLM).
  2. Write the code (using its LLM).
  3. Actually execute code to create and write to a file.

Steps 1 and 2 are handled by the LLM, but step 3 requires interacting with the computer’s file system – something the LLM can’t do directly.

Tools give agents these specific, actionable skills. A ToolCollection organizes these skills so the agent knows what it can do.

Use Case: Let’s build towards an agent that can:

  1. Search the web for today’s date.
  2. Tell the user the date.

This agent needs a “Web Search” tool.

Key Concepts: Tools and Toolboxes

Let’s break down the two main ideas:

1. BaseTool: The Blueprint for a Skill

Think of BaseTool (app/tool/base.py) as the template or design specification for any tool. It doesn’t do anything itself, but it defines what every tool needs to have:

  • name (str): A short, descriptive name for the tool (e.g., web_search, file_writer, code_runner). This is how the agent (or LLM) identifies the tool.
  • description (str): A clear explanation of what the tool does, what it’s good for, and when to use it. This is crucial for the LLM to decide which tool to use for a given task.
  • parameters (dict): A definition of the inputs the tool expects. For example, a web_search tool needs a query input, and a file_writer needs a path and content. This is defined using a standard format called JSON Schema.
  • execute method: An abstract method. This means BaseTool says “every tool must have an execute method”, but each specific tool needs to provide its own instructions for how to actually perform the action.

You almost never use BaseTool directly. You use it as a starting point to create actual, usable tools.

2. Concrete Tools: The Actual Skills

These are specific classes that inherit from BaseTool and provide the real implementation for the execute method. OpenManus comes with several pre-built tools:

  • WebSearch (app/tool/web_search.py): Searches the web using engines like Google, Bing, etc.
  • Bash (app/tool/bash.py): Executes shell commands (like ls, pwd, python script.py).
  • StrReplaceEditor (app/tool/str_replace_editor.py): Views, creates, and edits files by replacing text.
  • BrowserUseTool (app/tool/browser_use_tool.py): Interacts with web pages like a user (clicking, filling forms, etc.).
  • Terminate (app/tool/terminate.py): A special tool used by agents to signal they have finished their task.

Each of these defines its specific name, description, parameters, and implements the execute method to perform its unique action.

3. ToolCollection: The Agent’s Toolbox

Think of a handyman. They don’t just carry one tool; they have a toolbox filled with hammers, screwdrivers, wrenches, etc.

A ToolCollection (app/tool/tool_collection.py) is like that toolbox for an agent.

  • It holds a list of specific tool instances (like WebSearch, Bash).
  • It allows the agent (and its LLM) to see all the available tools and their descriptions.
  • It provides a way to execute a specific tool by its name.

When an agent needs to perform an action, its LLM can look at the ToolCollection, read the descriptions of the available tools, choose the best one for the job, figure out the necessary inputs based on the tool’s parameters, and then ask the ToolCollection to execute that tool with those inputs.

How Do We Use Them?

Let’s see how we can equip an agent with a simple tool. We’ll create a basic “EchoTool” first.

1. Creating a Concrete Tool (Inheriting from BaseTool):

# Import the necessary base class from app.tool.base import BaseTool, ToolResult # Define our simple tool class EchoTool(BaseTool): """A simple tool that echoes the input text.""" name: str = "echo_message" description: str = "Repeats back the text provided in the 'message' parameter." parameters: dict = { "type": "object", "properties": { "message": { "type": "string", "description": "The text to be echoed back.", }, }, "required": ["message"], # Tells the LLM 'message' must be provided  } # Implement the actual action  async def execute(self, message: str) -> ToolResult: """Takes a message and returns it.""" print(f"EchoTool executing with message: '{message}'") # ToolResult is a standard way to return tool output  return ToolResult(output=f"You said: {message}") # Create an instance of our tool echo_tool_instance = EchoTool() print(f"Tool Name: {echo_tool_instance.name}") print(f"Tool Description: {echo_tool_instance.description}")

Explanation:

  • We import BaseTool and ToolResult (a standard object for wrapping tool outputs).
  • class EchoTool(BaseTool): declares that our EchoTool is a type of BaseTool.
  • We define the name, description, and parameters according to the BaseTool template. The parameters structure tells the LLM what input is expected (message as a string) and that it’s required.
  • We implement async def execute(self, message: str) -> ToolResult:. This is the specific logic for our tool. It takes the message input and returns it wrapped in a ToolResult.

Example Output:

Tool Name: echo_message Tool Description: Repeats back the text provided in the 'message' parameter.

2. Creating a ToolCollection:

Now, let’s put our EchoTool and the built-in WebSearch tool into a toolbox.

# Import ToolCollection and the tools we want from app.tool import ToolCollection, WebSearch # Assume EchoTool class is defined as above # from your_module import EchoTool # Or wherever EchoTool is defined  # Create instances of the tools echo_tool = EchoTool() web_search_tool = WebSearch() # Uses default settings  # Create a ToolCollection containing these tools my_toolbox = ToolCollection(echo_tool, web_search_tool) # See the names of the tools in the collection tool_names = [tool.name for tool in my_toolbox] print(f"Tools in the toolbox: {tool_names}") # Get the parameters needed for the LLM tool_params_for_llm = my_toolbox.to_params() print(f"\nParameters for LLM (showing first tool):") import json print(json.dumps(tool_params_for_llm[0], indent=2))

Explanation:

  • We import ToolCollection and the specific tools (WebSearch, EchoTool).
  • We create instances of the tools we need.
  • my_toolbox = ToolCollection(echo_tool, web_search_tool) creates the collection, holding our tool instances.
  • We can access the tools inside using my_toolbox.tools or iterate over my_toolbox.
  • my_toolbox.to_params() is a crucial method. It formats the name, description, and parameters of all tools in the collection into a list of dictionaries. This specific format is exactly what the agent’s LLM needs (when using its ask_tool method) to understand which tools are available and how to use them.

Example Output:

Tools in the toolbox: ['echo_message', 'web_search'] Parameters for LLM (showing first tool): { "type": "function", "function": { "name": "echo_message", "description": "Repeats back the text provided in the 'message' parameter.", "parameters": { "type": "object", "properties": { "message": { "type": "string", "description": "The text to be echoed back." } }, "required": [ "message" ] } } }

3. Agent Using the ToolCollection:

Now, how does an agent like ToolCallAgent (a specific type of BaseAgent) use this?

Conceptually (the real agent code is more complex):

  1. The agent is configured with a ToolCollection (like my_toolbox).
  2. When the agent needs to figure out the next step, it calls its LLM’s ask_tool method.
  3. It passes the conversation history (Message / Memory) AND the output of my_toolbox.to_params() to the LLM.
  4. The LLM looks at the conversation and the list of available tools (from to_params()). It reads the description of each tool to understand what it does.
  5. If the LLM decides a tool is needed (e.g., the user asked “What’s today’s date?”, the LLM sees the web_search tool is available and appropriate), it will generate a special response indicating:
    • The name of the tool to use (e.g., "web_search").
    • The arguments (inputs) for the tool, based on its parameters (e.g., {"query": "today's date"}).
  6. The agent receives this response from the LLM.
  7. The agent then uses the ToolCollection’s execute method: await my_toolbox.execute(name="web_search", tool_input={"query": "today's date"}).
  8. The ToolCollection finds the WebSearch tool instance in its internal tool_map and calls its execute method with the provided input.
  9. The WebSearch tool runs, performs the actual web search, and returns the results (as a ToolResult or similar).
  10. The agent takes this result, formats it as a tool message, adds it to its memory, and continues its thinking process (often asking the LLM again, now with the tool’s result as context).

The ToolCollection acts as the crucial bridge between the LLM’s decision to use a tool and the actual execution of that tool’s code.

Under the Hood: How ToolCollection.execute Works

Let’s trace the flow when an agent asks its ToolCollection to run a tool:

sequenceDiagram participant Agent as ToolCallAgent participant LLM as LLM (Deciding Step) participant Toolbox as ToolCollection participant SpecificTool as e.g., WebSearch Tool Agent->>+LLM: ask_tool(messages, tools=Toolbox.to_params()) LLM->>LLM: Analyzes messages & available tools LLM-->>-Agent: Response indicating tool call: name='web_search', arguments={'query': '...'} Agent->>+Toolbox: execute(name='web_search', tool_input={'query': '...'}) Toolbox->>Toolbox: Look up 'web_search' in internal tool_map Note right of Toolbox: Finds the WebSearch instance Toolbox->>+SpecificTool: Calls execute(**tool_input) on the found tool SpecificTool->>SpecificTool: Performs actual web search action SpecificTool-->>-Toolbox: Returns ToolResult (output="...", error=None) Toolbox-->>-Agent: Returns the ToolResult Agent->>Agent: Processes the result (adds to memory, etc.)

Code Glimpse:

Let’s look at the ToolCollection itself in app/tool/tool_collection.py:

# Simplified snippet from app/tool/tool_collection.py from typing import Any, Dict, List, Tuple from app.tool.base import BaseTool, ToolResult, ToolFailure from app.exceptions import ToolError class ToolCollection: # ... (Config class) ...  tools: Tuple[BaseTool, ...] # Holds the tool instances  tool_map: Dict[str, BaseTool] # Maps name to tool instance for quick lookup  def __init__(self, *tools: BaseTool): """Initializes with a sequence of tools.""" self.tools = tools # Create the map for easy lookup by name  self.tool_map = {tool.name: tool for tool in tools} def to_params(self) -> List[Dict[str, Any]]: """Formats tools for the LLM API.""" # Calls the 'to_param()' method on each tool  return [tool.to_param() for tool in self.tools] async def execute( self, *, name: str, tool_input: Dict[str, Any] = None ) -> ToolResult: """Finds a tool by name and executes it.""" # 1. Find the tool instance using the name  tool = self.tool_map.get(name) if not tool: # Return a standard failure result if tool not found  return ToolFailure(error=f"Tool {name} is invalid") # 2. Execute the tool's specific method  try: # The 'tool(**tool_input)' calls the tool instance's __call__ method,  # which in BaseTool, calls the tool's 'execute' method.  # The ** unpacks the dictionary into keyword arguments.  result = await tool(**(tool_input or {})) # Ensure the result is a ToolResult (or subclass)  return result if isinstance(result, ToolResult) else ToolResult(output=str(result)) except ToolError as e: # Handle errors specific to tools  return ToolFailure(error=e.message) except Exception as e: # Handle unexpected errors during execution  return ToolFailure(error=f"Unexpected error executing tool {name}: {e}") # ... other methods like add_tool, __iter__ ...

Explanation:

  • The __init__ method takes tool instances and stores them in self.tools (a tuple) and self.tool_map (a dictionary mapping name to instance).
  • to_params iterates through self.tools and calls each tool’s to_param() method (defined in BaseTool) to get the LLM-compatible format.
  • execute is the core method used by agents:
    • It uses self.tool_map.get(name) to quickly find the correct tool instance based on the requested name.
    • If found, it calls await tool(**(tool_input or {})). The ** unpacks the tool_input dictionary into keyword arguments for the tool’s execute method (e.g., message="hello" for our EchoTool, or query="today's date" for WebSearch).
    • It wraps the execution in try...except blocks to catch errors and return a standardized ToolFailure result if anything goes wrong.

Wrapping Up Chapter 4

We’ve learned how Tools give agents specific skills beyond basic language understanding.

  • BaseTool is the abstract blueprint defining a tool’s name, description, and expected parameters.
  • Concrete tools (like WebSearch, Bash, or our custom EchoTool) inherit from BaseTool and implement the actual execute logic.
  • ToolCollection acts as the agent’s toolbox, holding various tools and providing methods (to_params, execute) for the agent (often guided by its LLM) to discover and use these capabilities.

With tools, agents can interact with external systems, run code, access real-time data, and perform complex actions, making them much more powerful.

But how do we coordinate multiple agents, potentially using different tools, to work together on a larger task? That’s where Flows come in.

Let’s move on to Chapter 5: BaseFlow to see how we orchestrate complex workflows involving multiple agents and steps.

Generated by AI Codebase Knowledge Builder