mai-bot/agentlite/docs/tools.md

AgentLite Tool Suite

A comprehensive tool suite for AgentLite, inspired by kimi-cli's tools, with configuration support for enabling/disabling individual tools.

Overview

This tool suite provides:

• File Operations: Read, write, edit, search files
• Shell Execution: Execute shell commands
• Web Access: Fetch URLs and search the web
• Multi-Agent: Task delegation and subagent creation
• Utilities: Todo lists and thinking tools
• Configuration: Fine-grained control over which tools are available

Installation

The tool suite is included with AgentLite. No additional installation required.

Quick Start

from agentlite.tools import ConfigurableToolset, ToolSuiteConfig
from agentlite import Agent, OpenAIProvider

# Create toolset with default config (all tools enabled)
toolset = ConfigurableToolset()

# Create agent with tools
provider = OpenAIProvider(api_key="your-key", model="gpt-4")
agent = Agent(
    provider=provider,
    system_prompt="You are a helpful assistant.",
    tools=toolset.tools,
)

Configuration

Basic Configuration

from agentlite.tools import (
    ToolSuiteConfig,
    FileToolsConfig,
    ShellToolsConfig,
)

# Disable specific tools
config = ToolSuiteConfig(
    file_tools=FileToolsConfig(
        tools={"WriteFile": False, "StrReplaceFile": False}
    )
)
toolset = ConfigurableToolset(config)

Disable Entire Tool Groups

# Disable all shell tools
config = ToolSuiteConfig(
    shell_tools=ShellToolsConfig(enabled=False)
)
toolset = ConfigurableToolset(config)

Custom Tool Settings

config = ToolSuiteConfig(
    file_tools=FileToolsConfig(
        max_lines=500,
        max_bytes=50 * 1024,  # 50KB
        allow_write_outside_work_dir=False,
    ),
    shell_tools=ShellToolsConfig(
        timeout=60,
        blocked_commands=["rm -rf", "sudo"],
    ),
)

Dynamic Configuration

# Create toolset
config = ToolSuiteConfig()
toolset = ConfigurableToolset(config)

# Disable tools and reload
config.file_tools.disable_tool("WriteFile")
config.shell_tools.enabled = False
toolset.reload()

Available Tools

File Tools

Tool	Description	Config Options
ReadFile	Read text files with line numbers	max_lines, max_bytes
WriteFile	Write or append to files	allow_write_outside_work_dir
StrReplaceFile	Edit files using string replacement	allow_write_outside_work_dir
Glob	Search files using glob patterns	max_glob_matches
Grep	Search file contents with regex	-
ReadMediaFile	Read images and videos	max_size_mb

Shell Tools

Tool	Description	Config Options
Shell	Execute shell commands	timeout, blocked_commands

Web Tools

Tool	Description	Config Options
FetchURL	Fetch web page content	timeout, user_agent
SearchWeb	Search the web	timeout

Multi-Agent Tools

Tool	Description	Config Options
Task	Delegate tasks to subagents	max_steps
CreateSubagent	Create custom subagents	-

Utility Tools

Tool	Description
SetTodoList	Manage todo lists
Think	Record thinking steps

Safety Features

Path Security

• Files outside the working directory require absolute paths
• Optional restriction on writing outside working directory
• Path traversal protection

Shell Security

• Configurable command timeout
• Blocked command list
• No shell injection (uses execve style execution)

Resource Limits

• File size limits
• Line count limits
• Glob match limits
• HTTP content size limits

Examples

Safe Configuration for Untrusted Agents

from agentlite.tools import ToolSuiteConfig, FileToolsConfig, ShellToolsConfig

# Safe config - read-only file access, no shell
safe_config = ToolSuiteConfig(
    file_tools=FileToolsConfig(
        allow_write_outside_work_dir=False,
    ),
    shell_tools=ShellToolsConfig(enabled=False),
)

toolset = ConfigurableToolset(safe_config)

Using Individual Tools

from agentlite.tools.file import ReadFile, Glob
from pathlib import Path

# Create tools directly
read_tool = ReadFile(work_dir=Path("."))
glob_tool = Glob(work_dir=Path("."))

# Use tools
result = await read_tool.read({"path": "README.md"})
if not result.is_error:
    print(result.output)

result = await glob_tool.glob({"pattern": "*.py"})
if not result.is_error:
    print(result.output)

Configuration from File

import json
from agentlite.tools import ToolSuiteConfig

# Load config from file
with open("tool_config.json") as f:
    config_dict = json.load(f)

config = ToolSuiteConfig.model_validate(config_dict)
toolset = ConfigurableToolset(config)

API Reference

Config Classes

ToolSuiteConfig

Main configuration class for all tools.

class ToolSuiteConfig(BaseModel):
    file_tools: FileToolsConfig
    shell_tools: ShellToolsConfig
    web_tools: WebToolsConfig
    multiagent_tools: MultiAgentToolsConfig
    misc_tools: ToolGroupConfig

FileToolsConfig

class FileToolsConfig(ToolGroupConfig):
    max_lines: int = 1000
    max_line_length: int = 2000
    max_bytes: int = 100 * 1024
    allow_write_outside_work_dir: bool = False
    max_glob_matches: int = 1000

ShellToolsConfig

class ShellToolsConfig(ToolGroupConfig):
    timeout: int = 60
    max_timeout: int = 300
    blocked_commands: list[str] = []

WebToolsConfig

class WebToolsConfig(ToolGroupConfig):
    timeout: int = 30
    user_agent: str = "Mozilla/5.0 ..."
    max_content_length: int = 1024 * 1024

ConfigurableToolset

class ConfigurableToolset(SimpleToolset):
    def __init__(
        self,
        config: ToolSuiteConfig | None = None,
        work_dir: str | None = None,
    )
    
    def reload(self, config: ToolSuiteConfig | None = None) -> None

License

MIT License - same as AgentLite.