Tool Controller

Tool Controller#

Overview#

We also support dynamically managing the activation status of tools through ToolController, so that the Agent framework can, under certain circumstances, turn off or on certain tools with minimal changes.

Core Functions#

ToolController provides a rule-based tool status management system. Core functions include:

  1. Dynamic Control of Tool Activation Status - Activate/deactivate tools by rule-based pattern matching of tool names.

  2. Default Behavior Configuration - Set the default tool behavior when no rules are matched

  3. Rule Priority - Supports applying rules in priority order, with the first matched rule taking effect.

  4. Pattern Matching - Supports wildcard pattern matching (e.g., math_* matches all math server tools)

  5. Dynamic Tool Management - provides an API to activate/disable specific tools at runtime

Create tool controller#

The following is an example of creating and configuring a basic tool controller:

from evofabric.core.tool import ToolController

# Create tool controller
controller = ToolController(
    default_mode="deactivate",  # default_mode: deactivate all tools by default
    rules=[
        {
            "mode": "activate",
            "pattern": "math_*"  # activate all tools from the math server
        },
        {
            "mode": "deactivate",
            "pattern": "calc_*"   # deactivate tools from the calc server
        }
    ]
)

# After validation, rules will be automatically converted to objects
print(controller.rules)
# [ToolControlPattern(mode='activate', pattern='math_*'),
#  ToolControlPattern(mode='deactivate', pattern='calc_*')]

Rule Details#

Rules are the core of ToolController, and each rule consists of two parts:

Rule = {
    "mode": "activate" | "deactivate",
    "pattern": "glob_wildcard_string"
}

Pattern matching rules follow the Unix shell wildcard specification:

# Example patterns
"math_*"         # Matches all tools from the math server
"text_*"         # Matches all tools from the text server
"math_calculator" # Matches the tool with exact name
"*_calculator"   # Matches any tool ending with _calculator
"upload_*"       # Matches all tools starting with upload

Rule Priority Example#

Rules are matched in order, the first matched rule takes effect:

controller = ToolController(
    default_mode="deactivate",
    rules=[
        {"mode": "activate", "pattern": "math_*"},    # First priority
        {"mode": "deactivate", "pattern": "math_add"}, # Second priority
    ]
)

# For tool name "math_add":
# 1. First matches rule #1 -> activate
# 2. Although rule #2 also matches, it has lower priority and is ignored
print(controller.check_tool_status("math_add"))  # True

Dynamic Tool Management#

You can activate or disable specific tools at runtime. These adjustments will take effect immediately and have the highest priority.

from evofabric.core.tool import ToolManager

# Create a tool manager with controller
controller = ToolController(default_mode="deactivate")
tool_manager = ToolManager(tools=[], tool_controller=controller)

# Create some tools
# ... (tool definitions) ...

# Dynamically activate specific tools
controller.activate_tool("text_translator")

# Dynamically deactivate specific tools
controller.deactivate_tool("math_complex")

# Check tool status
print(controller.check_tool_status("text_translator"))  # True
print(controller.check_tool_status("math_complex"))     # False

Filter Tool List#

ToolController provides a tool list filtering function to ensure that only active tools are returned:

# Original tool list
all_tools = [
    {"name": "math_add"},
    {"name": "math_subtract"},
    {"name": "text_translate"}
]

# Filter active tools based on rules
active_tools = controller.filter_tool_list(all_tools)

# Assume rules:
# - default_mode="deactivate"
# - rules=[{"mode": "activate", "pattern": "math_*"}]
# Result: Only math tools are activated
print([tool["name"] for tool in active_tools])
# Output: ['math_add', 'math_subtract']

Best Practices#

  1. Rule Order Optimization: Place exact match rules before general rules.

  2. Default Mode Selection：

    • activate: Suitable for whitelist scenarios (to disable only specific tools).

    • deactivate: Suitable for blacklist scenarios (only controlling the activation of specific tools).

  3. Mode Naming：

    • Use server name prefixes, such as math_*, to organize rules.

    • Avoid overly broad wildcard characters (e.g., *_* will match all tools).

  4. Dynamic Priority Management: Implement an emergency switch through activate_tool() and deactivate_tool()

Contents