Toolsets

Toolsets extend agent capabilities by providing access to external functions, APIs, and services. They are bundled with the pantheon-agents package and can be used directly with agents.

Installation

Toolsets are included with the core pantheon-agents package:

pip install pantheon-agents

All toolset dependencies are included:

• Python code execution

• Jupyter notebook integration

• Web browsing and scraping

• File operations

• Code parsing (tree-sitter)

Overview

Pantheon’s toolset system provides a unified interface for extending agent capabilities:

• Local Execution: Tools run in the same process as the agent

• Tool Decorator: Methods decorated with @tool are automatically exposed to agents

• Type Safety: Automatic parameter validation from type hints

• Async Support: Full support for async tool implementations

Architecture

The toolset system consists of:

1. ToolSet Base Class: Base class that all toolsets inherit from

2. Tool Decorator: Marks methods as tools with docstring descriptions

3. Provider System: Handles tool discovery and execution

Built-in Toolsets

File Operations

• FileManagerToolSet - Comprehensive file operations

  • read_file: Read file contents with optional line range

  • write_file: Write/create files

  • update_file: String replacement editing

  • manage_path: Create/delete/move files and directories

  • glob: Pattern-based file search

  • grep: Content search with regex

  • apply_patch: Apply unified diff or V4A patches

  • observe_images: Analyze images with LLM vision

  • read_pdf: Extract text from PDFs

• FileTransferToolSet - Chunked file transfer with streaming support

  • open_file_for_write: Get file handle for writing

  • write_chunk: Write data chunks to open file

  • close_file: Close file handle

  • read_file: Read file with base64 encoding

Code Execution

• PythonInterpreterToolSet - Execute Python code in isolated environment

  • run_python_code: Execute Python with auto session management

  • manage_interpreters: Create, list, delete interpreter sessions

• ShellToolSet - Run shell commands with timeout support

  • run_command: Execute shell commands

  • get_shell_output: Fetch output from background commands

  • close_shell: Close shell sessions

• RInterpreterToolSet - Execute R code with session management

  • run_r_code: Execute R code with auto session management

  • new_interpreter, delete_interpreter: Interpreter management

• JuliaInterpreterToolSet - Execute Julia code with session management

  • run_julia_code: Execute Julia code with interpreter management

  • new_interpreter, delete_interpreter: Interpreter management

• IntegratedNotebookToolSet - Jupyter notebook with kernel management

  • create_notebook: Create or open notebooks

  • add_cell, update_cell, delete_cell: Cell operations

  • execute_cell: Execute cells with output capture

  • manage_kernel: Restart, interrupt, shutdown kernels

Code Analysis

• CodeToolSet - Code navigation with tree-sitter AST analysis

  • view_file_outline: Get structural outline of code files

  • view_code_item: Extract specific code items by name

Web & Search

• WebToolSet - Web search and content retrieval

  • duckduckgo_search: Web search via DuckDuckGo

  • web_crawl: Fetch and extract content from URLs as markdown

• Scraper API - Advanced web scraping with JavaScript rendering

  • scrape_url: Scrape with CSS/XPath selectors

  • Supports pagination, infinite scroll, screenshots

Knowledge & RAG

• KnowledgeToolSet - Knowledge base management with hybrid search

  • search_knowledge: Semantic + keyword search with Qdrant

  • create_collection, delete_collection: Collection management

  • add_source, remove_source: Document source management

  • index_source: Index documents into vector store

• Vector RAG - Vector-based retrieval augmented generation

  • Vector store integration

  • Document indexing and retrieval

Media

• ImageGenerationToolSet - AI image generation

  • generate_image: Create images with DALL-E, Gemini, or other providers

  • Supports text prompts and image references

Database

• DatabaseAPIQueryToolSet - Biological database queries (26+ databases)

  • query: Query any supported database

  • list_databases: List available databases

  • database_info: Get database schema and examples

Workflow & Learning

• TaskToolSet - Modal workflow management

  • task_boundary: Track task progress and mode transitions

  • notify_user: User communication with confidence scoring

• SkillbookToolSet - Skill management for learning agents

  • add_skill, update_skill, remove_skill: Skill CRUD

  • tag_skill: Track skill effectiveness (helpful/harmful)

  • list_skills: Search and filter skills

• PackageToolSet - Package and tool discovery

  • search_tools: Keyword or semantic search for tools

  • search_packages: List and filter available packages

Evolution & Evaluation

• EvolutionToolSet - Evolutionary code optimization

  • evolve_code: Optimize single code files

  • evolve_codebase: Optimize multi-file projects

  • get_evolution_status: Monitor evolution progress

• EvaluatorToolSet - Code evaluation and quality assessment

  • evaluate_code: Run custom evaluators on code

  • evaluate_codebase: Evaluate entire projects

  • compute_code_metrics: Static code metrics

  • get_llm_code_review: AI-powered code review

Quick Start

Using Built-in Toolsets

Method 1: In Constructor

from pantheon.agent import Agent
from pantheon.toolsets import FileManagerToolSet, ShellToolSet

# Create toolsets
file_tools = FileManagerToolSet(name="files")
shell_tools = ShellToolSet(name="shell")

# Create agent and add toolsets at runtime
agent = Agent(
    name="developer",
    instructions="You are a developer assistant."
)
await agent.toolset(file_tools)
await agent.toolset(shell_tools)

await agent.chat()

Alternative: Chained calls

from pantheon.agent import Agent
from pantheon.toolsets import FileManagerToolSet, ShellToolSet

# Create agent first
agent = Agent(
    name="developer",
    instructions="You are a developer assistant."
)

# Add toolsets dynamically
await agent.toolset(FileManagerToolSet(name="files"))
await agent.toolset(ShellToolSet(name="shell"))

await agent.chat()

Creating Custom Tools

from pantheon.toolset import ToolSet, tool

class MyToolSet(ToolSet):
    @tool
    def calculate(self, expression: str) -> float:
        """Evaluate a mathematical expression.

        Args:
            expression: The mathematical expression to evaluate

        Returns:
            The result of the calculation
        """
        return eval(expression)

    @tool
    async def fetch_data(self, url: str) -> str:
        """Fetch data from a URL asynchronously."""
        import aiohttp
        async with aiohttp.ClientSession() as session:
            async with session.get(url) as response:
                return await response.text()

# Use with agent
agent = Agent(
    name="assistant",
    instructions="You are a helpful assistant."
)
await agent.toolset(MyToolSet(name="my_tools"))

Tool Decorator Options

from pantheon.toolset import tool

class AdvancedToolSet(ToolSet):
    @tool
    def cpu_intensive_task(self, data: str) -> str:
        """CPU-intensive work."""
        # Heavy computation here
        return result

    @tool
    def io_bound_task(self, path: str) -> str:
        """I/O operations."""
        # I/O operations here
        return result

Creating Custom ToolSets

Need specialized functionality? Create custom toolsets by extending the base ToolSet class. See Creating Custom ToolSets for a complete guide with examples including:

• Session management for multi-user scenarios

• Accessing execution context

• Lifecycle methods (setup/cleanup)

• Calling the LLM from within tools

from pantheon.toolset import ToolSet, tool

class TodoToolSet(ToolSet):
    def __init__(self, name: str):
        super().__init__(name)
        self.todos = {}

    @tool
    async def add_todo(self, title: str, priority: str = "medium") -> dict:
        """Add a new todo item.

        Args:
            title: The todo item title
            priority: Priority level (low, medium, high)
        """
        session_id = self.get_session_id()
        # Per-session storage
        if session_id not in self.todos:
            self.todos[session_id] = []
        todo = {"id": len(self.todos[session_id]) + 1, "title": title}
        self.todos[session_id].append(todo)
        return {"success": True, "todo": todo}

Best Practices

1. Clear Docstrings: Write descriptive docstrings - they become the tool description for the LLM

2. Type Hints: Always use type hints for parameters and return values

3. Error Handling: Handle errors gracefully and return informative error messages

4. Async When Possible: Use async for I/O-bound operations

5. Resource Cleanup: Implement cleanup in toolset lifecycle methods

MCP Integration

Toolsets can be exposed as MCP (Model Context Protocol) servers:

from pantheon.endpoint.mcp import MCPGateway
from pantheon.toolsets import FileManagerToolSet

gateway = MCPGateway()
gateway.add_toolset(FileManagerToolSet("files"))
await gateway.serve()

See Utils Module for more details on MCP integration.