agentsociety.agent.toolbox

Enhanced AgentToolbox with support for custom tools.

This module provides an extensible AgentToolbox that allows users to add custom tools while maintaining backward compatibility with the existing API.

Module Contents

Classes

CustomTool	Represents a custom tool that can be added to AgentToolbox.
AgentToolbox	Enhanced toolbox for agents with support for custom tools.

Data

__all__

API

agentsociety.agent.toolbox.__all__

[‘AgentToolbox’, ‘CustomTool’]

class agentsociety.agent.toolbox.CustomTool

Bases: pydantic.BaseModel

Represents a custom tool that can be added to AgentToolbox.

• Description: A Pydantic model for custom tools that provides metadata and access methods. The underlying tool can be any callable object (function, method, class, etc.).

• Args:

  • name (str): Unique name for the tool

  • tool (Any): The actual tool object (can be function, class, method, etc.)

  • description (str): Description of what the tool does

  • category (ToolCategory): Category of the tool (MCP or NORMAL)

  • metadata (Dict[str, Any]): Additional metadata about the tool

name: str

‘Field(…)’

tool: Any

‘Field(…)’

description: str

‘Field(…)’

class Config

Pydantic configuration for CustomTool.

arbitrary_types_allowed

True

__call__(*args, **kwargs)

Call the underlying tool.

• Description: Delegates the call to the underlying tool object. If the tool is callable, it calls it directly. If the tool is a class, it returns the class for instantiation.

• Args:

  • *args: Positional arguments to pass to the tool

  • **kwargs: Keyword arguments to pass to the tool

• Returns:

  • Any: Result from the tool execution

get_info() → Dict[str, Any]

Get information about the tool.

• Description: Returns metadata about the tool for documentation and introspection.

• Returns:

  • Dict[str, Any]: Tool information dictionary

get_tool() → Any

Get the underlying tool object.

• Description: Returns the actual tool object for direct access.

• Returns:

  • Any: The underlying tool object

classmethod create_mcp_tool(name: str, tool: Any, description: str, metadata: Optional[Dict[str, Any]] = None) → agentsociety.agent.toolbox.CustomTool

Create an MCP category tool.

• Description: Convenience method to create a tool with MCP category.

• Args:

  • name (str): Unique name for the tool

  • tool (Any): The actual tool object

  • description (str): Description of what the tool does

  • metadata (Optional[Dict[str, Any]]): Additional metadata

• Returns:

  • CustomTool: The created MCP tool

classmethod create_normal_tool(name: str, tool: Any, description: str, metadata: Optional[Dict[str, Any]] = None) → agentsociety.agent.toolbox.CustomTool

Create a NORMAL category tool.

• Description: Convenience method to create a tool with NORMAL category.

• Args:

  • name (str): Unique name for the tool

  • tool (Any): The actual tool object

  • description (str): Description of what the tool does

  • metadata (Optional[Dict[str, Any]]): Additional metadata

• Returns:

  • CustomTool: The created NORMAL tool

class agentsociety.agent.toolbox.AgentToolbox

Bases: pydantic.BaseModel

Enhanced toolbox for agents with support for custom tools.

• Description: An extensible toolbox that provides core agent functionality and allows users to add custom tools. Maintains backward compatibility with the original NamedTuple-based implementation.

• Args:

  • llm (LLM): Language model interface

  • environment (Environment): Simulation environment

  • messager (Messager): Message handling system

  • embedding (SparseTextEmbedding): Text embedding system

  • database_writer (Optional[DatabaseWriter]): Database writing interface

llm: agentsociety.llm.llm.LLM

‘Field(…)’

environment: Optional[agentsociety.environment.environment.Environment]

‘Field(…)’

messager: Optional[agentsociety.message.Messager]

‘Field(…)’

embedding: fastembed.SparseTextEmbedding

‘Field(…)’

database_writer: Optional[agentsociety.storage.DatabaseWriter]

‘Field(…)’

custom_tools: Dict[str, agentsociety.agent.toolbox.CustomTool]

‘Field(…)’

class Config

Pydantic configuration for AgentToolbox.

arbitrary_types_allowed

True

add_tool(tool: agentsociety.agent.toolbox.CustomTool) → None

Add a custom tool to the toolbox.

• Description: Registers a custom tool with the toolbox. The tool will be accessible via the toolbox instance.

• Args:

  • tool (CustomTool): The custom tool to add

• Raises:

  • ValueError: If a tool with the same name already exists

add_custom_tool(tool: agentsociety.agent.toolbox.CustomTool) → None

Add a custom tool to the toolbox.

• Description: Adds a CustomTool object directly to the toolbox.

• Args:

  • tool (CustomTool): The custom tool object to add

get_tool(name: str) → Optional[agentsociety.agent.toolbox.CustomTool]

Get a custom tool by name.

• Description: Retrieves a custom tool from the toolbox.

• Args:

  • name (str): Name of the tool to retrieve

• Returns:

  • Optional[CustomTool]: The tool if found, None otherwise

get_tool_object(name: str) → Optional[Any]

Get the underlying tool object by name.

• Description: Retrieves the actual tool object from the toolbox.

• Args:

  • name (str): Name of the tool to retrieve

• Returns:

  • Optional[Any]: The tool object if found, None otherwise

remove_tool(name: str) → bool

Remove a custom tool from the toolbox.

• Description: Removes a custom tool from the toolbox.

• Args:

  • name (str): Name of the tool to remove

• Returns:

  • bool: True if tool was removed, False if not found

list_tools() → Dict[str, agentsociety.agent.toolbox.CustomTool]

List all custom tools.

• Description: Returns a dictionary of custom tools.

• Returns:

  • Dict[str, CustomTool]: Dictionary of tools

get_tool_info(name: str) → Optional[Dict[str, Any]]

Get information about a custom tool.

• Description: Returns metadata about a specific custom tool.

• Args:

  • name (str): Name of the tool

• Returns:

  • Optional[Dict[str, Any]]: Tool information if found

get_all_tools_info() → Dict[str, Dict[str, Any]]

Get information about all custom tools.

• Description: Returns metadata about all custom tools in the toolbox.

• Returns:

  • Dict[str, Dict[str, Any]]: Dictionary of tool information

has_tool(name: str) → bool

Check if a custom tool exists.

• Description: Checks whether a custom tool with the given name exists.

• Args:

  • name (str): Name of the tool to check

• Returns:

  • bool: True if tool exists, False otherwise

__getattr__(name: str) → Any

Allow direct access to custom tools as attributes.

• Description: Enables accessing custom tools as attributes of the toolbox. Returns the underlying tool object.

• Args:

  • name (str): Name of the attribute/tool

• Returns:

  • Any: The tool object

• Raises:

  • AttributeError: If the tool doesn’t exist

__contains__(name: str) → bool

Check if a tool exists in the toolbox.

• Description: Enables using ‘in’ operator to check for tool existence.

• Args:

  • name (str): Name of the tool to check

• Returns:

  • bool: True if tool exists, False otherwise

__len__() → int

Get the number of custom tools.

• Description: Returns the number of custom tools in the toolbox.

• Returns:

  • int: Number of custom tools