Skip to main content
Esprit provides a modular tool system that enables agents to perform security testing operations. Tools are dynamically registered and can execute locally or in isolated sandboxes.

​
Tool Architecture

​
Tool Registry

Tools are registered using the @register_tool decorator (esprit/tools/registry.py): 
from esprit.tools import register_tool

@register_tool(sandbox_execution=True)
async def my_security_tool(target: str, agent_state) -> dict:
    """Perform security assessment on target."""
    # Tool implementation
    return {"success": True, "findings": [...]}

​
Registration Options

  • sandbox_execution=True: Execute in isolated sandbox (default)
  • sandbox_execution=False: Execute in CLI process (for coordination tasks)

​
Tool Schema

Each tool has an XML schema file defining its interface: 
<tool name="my_security_tool">
  <description>Perform security assessment on target</description>
  <parameters>
    <parameter name="target" type="string" required="true">
      <description>Target URL or IP address</description>
    </parameter>
    <parameter name="scan_depth" type="string" required="false">
      <description>Scan depth: quick, standard, or deep</description>
    </parameter>
  </parameters>
</tool>
Schemas are automatically converted to JSON format for native tool calling (OpenAI-compatible).

​
Available Tools

Based on esprit/tools/__init__.py, the following tool modules are available:

​
Browser Tools

Module: esprit/tools/browser/
Sandbox Execution: Yes
Description: Automated browser interactions using Playwright
  • browser_navigate: Navigate to URL
  • browser_click: Click element by selector
  • browser_type: Type text into input field
  • browser_screenshot: Capture page screenshot
  • browser_extract_content: Extract text content from page
  • browser_get_cookies: Retrieve browser cookies
  • browser_close_tab: Close current browser tab
  • browser_new_tab: Open new browser tab
  • browser_execute_js: Execute JavaScript in page context
Key Features:
  • Multi-tab support via TabManager
  • Persistent browser instances per agent
  • Automatic viewport configuration
  • Screenshot support (base64-encoded PNG)

​
Terminal Tools

Module: esprit/tools/terminal/
Sandbox Execution: Yes
Description: Shell command execution in sandbox
  • terminal_run_command: Execute shell command
  • terminal_list_sessions: List active terminal sessions
  • terminal_get_session: Get terminal session info
  • terminal_kill_session: Terminate terminal session
Key Features:
  • Persistent terminal sessions (TerminalSession class)
  • Command timeout enforcement (configurable via ESPRIT_SANDBOX_EXECUTION_TIMEOUT)
  • Working directory management
  • Environment variable support

​
File Edit Tools

Module: esprit/tools/file_edit/
Sandbox Execution: Yes
Description: File system operations and code editing
  • file_read: Read file contents
  • file_write: Write content to file
  • file_edit: Edit file with search/replace
  • file_list: List directory contents
  • file_delete: Delete file or directory
  • file_create: Create new file
  • file_search: Search for pattern in files
Key Features:
  • All operations scoped to /workspace directory
  • Edit tracking for scan diffs
  • Glob pattern support for searches
  • Safety checks to prevent destructive operations outside workspace

​
Proxy Tools

Module: esprit/tools/proxy/
Sandbox Execution: Yes
Description: HTTP/HTTPS traffic interception using mitmproxy
  • proxy_start: Start HTTP interception proxy
  • proxy_stop: Stop proxy
  • proxy_get_requests: Retrieve intercepted requests
  • proxy_get_responses: Retrieve intercepted responses
  • proxy_clear_history: Clear intercepted traffic
  • proxy_export: Export traffic to HAR format
Key Features:
  • Automatic HTTPS certificate handling
  • Request/response modification support
  • Traffic filtering by URL pattern
  • HAR export for external analysis

​
Python Tools

Module: esprit/tools/python/
Sandbox Execution: Yes
Description: Python code execution in isolated interpreter
  • python_exec: Execute Python code
  • python_eval: Evaluate Python expression
  • python_install_package: Install pip package
  • python_list_packages: List installed packages
Key Features:
  • Persistent Python interpreter state per agent
  • Package installation support
  • Stdout/stderr capture
  • Exception handling and traceback reporting

​
Agents Graph Tools

Module: esprit/tools/agents_graph/
Sandbox Execution: No (local only)
Description: Multi-agent coordination and communication
  • agent_create: Create new sub-agent
  • agent_send_message: Send message to another agent
  • agent_get_status: Get agent status
  • agent_list_agents: List all agents
  • agent_finish: Mark sub-agent as completed
  • wait_for_message: Wait for messages from other agents
Key Features:
  • Hierarchical agent relationships tracked in graph
  • Message passing between agents
  • Agent lifecycle management
  • Status tracking (running, waiting, completed, failed)

​
Finish Tools

Module: esprit/tools/finish/
Sandbox Execution: No
Description: Scan completion and result reporting
  • finish_scan: Complete security scan (root agent only)
Key Features:
  • Triggers scan completion and cleanup
  • Generates final report
  • Only callable by root agent

​
Thinking Tools

Module: esprit/tools/thinking/
Sandbox Execution: No
Description: Internal reasoning and planning
  • think: Record internal reasoning (not visible to user)
Key Features:
  • Supports extended thinking mode
  • Helps agents organize complex reasoning
  • Not included in final output

​
Todo Tools

Module: esprit/tools/todo/
Sandbox Execution: No
Description: Task planning and tracking
  • todo_create: Create new todo item
  • todo_update: Update todo status
  • todo_list: List all todos
  • todo_delete: Delete todo
Key Features:
  • Helps agents organize multi-step tasks
  • Status tracking (pending, in_progress, completed)
  • Priority management

​
Reporting Tools

Module: esprit/tools/reporting/
Sandbox Execution: No
Description: Generate structured security reports
  • report_finding: Report security finding
  • report_get_findings: Get all reported findings
  • report_update_finding: Update existing finding
Key Features:
  • Structured finding format (title, severity, description, remediation)
  • CVSS scoring support
  • Deduplication of similar findings

​
Notes Tools

Module: esprit/tools/notes/
Sandbox Execution: No
Description: Agent note-taking and memory
  • note_create: Create note
  • note_list: List all notes
  • note_get: Retrieve specific note
  • note_delete: Delete note
Key Features:
  • Persistent memory across iterations
  • Key-value storage
  • Useful for tracking state across long scans

​
Web Search Tools

Module: esprit/tools/web_search/
Sandbox Execution: No
Description: External web search via Perplexity API
  • web_search: Search the web for information
Requirements:
  • Perplexity API key (PERPLEXITY_API_KEY environment variable)
  • Only available when API key is configured

​
Tool Execution Flow

​
Sandbox Execution

For tools with sandbox_execution=True (esprit/tools/executor.py:31-101):
  1. Agent calls tool via execute_tool(tool_name, **kwargs)
  2. Tool executor retrieves sandbox URL from agent state
  3. HTTP POST request sent to {sandbox_url}/execute: 
    {
  "agent_id": "agent-123",
  "tool_name": "terminal_run_command",
  "kwargs": {"command": "ls -la"}
}
  4. Tool server in sandbox executes tool function
  5. Result returned as JSON: 
    {
  "result": "<command output>",
  "error": null
}
  6. Result added to conversation as tool result message

​
Local Execution

For tools with sandbox_execution=False (esprit/tools/executor.py:103-117):
  1. Tool function retrieved from registry
  2. Arguments validated against schema
  3. Function called directly in CLI process
  4. Result returned immediately

​
Tool Validation

The tool executor performs validation (esprit/tools/executor.py:132-165):
  • Checks for unknown parameters
  • Ensures required parameters are present
  • Validates parameter types (string, boolean, number, list, dict)
  • Returns detailed error messages with schema hints
  • Verifies tool exists in registry
  • Lists available tools if requested tool not found
  • Handles conditional tool loading (e.g., web_search only with API key)

​
Result Formatting

Tool results are wrapped in XML for LLM consumption (executor.py:253-258): 
<tool_result>
  <tool_name>terminal_run_command</tool_name>
  <result>
    total 48
    drwxr-xr-x  3 pentester pentester 4096 Mar  3 23:00 .
    drwxr-xr-x  1 pentester pentester 4096 Mar  3 23:00 ..
  </result>
</tool_result>
For native tool calling mode (OpenAI format), XML is stripped and only the <result> content is returned.

​
Tool Server

The tool server (esprit/runtime/tool_server.py) runs inside each sandbox:
  • FastAPI-based HTTP server on port 48081
  • Bearer token authentication
  • Executes tools in sandbox environment
  • Maintains per-agent tool instances (browser, terminal, python)
  • Tracks file edits for diff extraction

​
Creating Custom Tools

To add a new tool:
  1. Create module in esprit/tools/my_tool/
  2. Define tool function: 
    @register_tool(sandbox_execution=True)
async def my_tool_action(param1: str, agent_state) -> dict:
    """Tool description."""
    # Implementation
    return {"success": True}
  3. Create XML schema file my_tool_actions_schema.xml
  4. Import in esprit/tools/__init__.py: 
    from .my_tool import *

​
Next Steps

Agent System

Learn how agents use tools

Docker Sandbox

Understand tool execution environments

Build docs developers (and LLMs) love

Get started for freeTalk to us