Relevant source files

The following files were used as context for generating this wiki page: - [esprit/tools/registry.py](https://github.com/esprit-cli/Esprit/blob/main/esprit/tools/registry.py) - [esprit/tools/executor.py](https://github.com/esprit-cli/Esprit/blob/main/esprit/tools/executor.py) - [esprit/interface/tool_components/proxy_renderer.py](https://github.com/esprit-cli/Esprit/blob/main/esprit/interface/tool_components/proxy_renderer.py) - [esprit/tools/reporting/reporting_actions_schema.xml](https://github.com/esprit-cli/Esprit/blob/main/esprit/tools/reporting/reporting_actions_schema.xml) - [esprit/tools/notes/notes_actions_schema.xml](https://github.com/esprit-cli/Esprit/blob/main/esprit/tools/notes/notes_actions_schema.xml) - [esprit/tools/finish/finish_actions_schema.xml](https://github.com/esprit-cli/Esprit/blob/main/esprit/tools/finish/finish_actions_schema.xml)

# Developing Custom Tools Custom tools in Esprit are the primary mechanism for extending agent capabilities, allowing AI agents to interact with the environment, perform specialized security tests, and report findings. The system relies on a central registry to manage tool definitions, a schema-driven validation layer, and a flexible execution engine that supports both local and sandboxed environments. ## Tool Architecture and Registration The tool system is built around a centralized registry that maps Python functions to specific metadata and schemas required by Large Language Models (LLMs). Registration is handled via the `@register_tool` decorator, which captures the function's signature and associates it with an XML-based schema file. ### Tool Registration Lifecycle When a tool is decorated, the system performs several automated steps: 1. **Metadata Extraction**: Identifies the module name and function name. 2. **Schema Loading**: Locates and parses the corresponding `_schema.xml` file. 3. **JSON Conversion**: Converts XML definitions into OpenAI-compatible JSON schemas for native tool calling. 4. **Registry Insertion**: Adds the tool to the global `tools` list and internal lookup dictionaries. Sources: [esprit/tools/registry.py:209-253](), [esprit/tools/registry.py:121-157]() ```mermaid flowchart TD Func[Python Function] --> Decorator[@register_tool] Decorator --> Metadata[Extract Metadata] Metadata --> SchemaLoad[Load XML Schema] SchemaLoad --> JSONConv[Convert to JSON Schema] JSONConv --> Registry[Store in _tools_by_name] Registry --> ParamMap[Store in _tool_param_schemas] ``` The diagram above illustrates the sequence of operations during the registration of a new tool. Sources: [esprit/tools/registry.py:214-250]() ### Schema Definition Tools must have an associated XML schema file located in the same directory as the tool implementation, named `_schema.xml`. This schema defines the tool's description, parameters, and examples. | Component | Description | Requirement | | :--- | :--- | :--- | | `` | High-level summary of tool purpose for the LLM. | Required | | `` | Defines name, type (string, boolean, integer, etc.), and if it is required. | Optional | | `

` | Additional technical nuances or implementation details. | Optional | | `` | XML-formatted function calls to guide LLM behavior. | Optional | Sources: [esprit/tools/registry.py:53-93](), [esprit/tools/reporting/reporting_actions_schema.xml:3-23]() ## Execution Engine The execution engine manages the invocation of tools based on LLM requests. It supports two primary modes: local execution and sandboxed execution. ### Local vs. Sandbox Execution The system determines where to execute a tool based on the `sandbox_execution` flag defined during registration. By default, most tools are executed in a sandbox for security. * **Local Execution**: The function is called directly within the Esprit process. * **Sandbox Execution**: The request is serialized and sent to a remote tool server (typically a Docker container) via HTTP POST to the `/execute` endpoint. Sources: [esprit/tools/executor.py:27-33](), [esprit/tools/executor.py:48-61]() ```mermaid sequenceDiagram participant Agent as Agent State participant Exec as Executor participant Sandbox as Sandbox Tool Server Exec->>Exec: check should_execute_in_sandbox() alt Sandbox Mode Exec->>Sandbox: POST /execute (JSON Payload) Sandbox-->>Exec: Return result/error else Local Mode Exec->>Exec: tool_func(**kwargs) end Exec-->>Agent: Return formatted result ``` The sequence diagram shows the decision logic for tool execution pathways. Sources: [esprit/tools/executor.py:35-95]() ### Argument Validation Before execution, tool arguments are validated against the parameters defined in the tool's XML schema. This ensures that: * All required parameters are present. * No unknown parameters are passed. * Parameters meet the expected types. Sources: [esprit/tools/executor.py:126-146]() ## UI and Rendering Custom tools often require specialized visualization in the Esprit Terminal. This is achieved through "Tool Renderers" which convert raw tool results into formatted Rich text components for the dashboard. ### Proxy and Sitemap Rendering The `proxy_renderer.py` provides examples of complex UI components for tools like `send_request` or `list_sitemap`. These renderers use specific icons (e.g., `PROXY_ICON = "<~>"`) and color-coded status codes to improve readability. | Tool Name | Icon | Rendering Focus | | :--- | :--- | :--- | | `list_requests` | `<~>` | Method, Host, Path, and HTTP Status colors. | | `send_request` | `<~>` | Request headers (>>) and Response body (<<). | | `list_sitemap` | `<~>` | Resource kind (DOMAIN, DIRECTORY, REQUEST). | Sources: [esprit/interface/tool_components/proxy_renderer.py:10-25](), [esprit/interface/tool_components/proxy_renderer.py:175-210]() ```python # Example of a tool renderer implementation @register_tool_renderer class SendRequestRenderer(BaseToolRenderer): tool_name: ClassVar[str] = "send_request" @classmethod def render(cls, tool_data: dict[str, Any]) -> Static: # Processes args and results to build a Rich Text object text = Text() text.append(PROXY_ICON, style="dim") # ... logic for headers and status codes ... return Static(text) ``` Sources: [esprit/interface/tool_components/proxy_renderer.py:175-212]() ## Best Practices for Custom Tools 1. **Deduplication**: Tools like `create_vulnerability_report` implement LLM-based deduplication to prevent redundant reporting of the same finding. Sources: [esprit/tools/reporting/reporting_actions_schema.xml:5-15]() 2. **State Management**: Tools that require access to the current agent's context (like `agent_id` or `sandbox_token`) must include `agent_state` in their function signature. Sources: [esprit/tools/registry.py:269-274]() 3. **Professional Reporting**: Output from reporting tools should be vendor-neutral, formal, and objective, suitable for customer-facing deliverables. Sources: [esprit/tools/finish/finish_actions_schema.xml:33-45]() 4. **Error Handling**: Execution failures are caught by the executor, truncated if they are too long, and returned as a standard error string to the agent. Sources: [esprit/tools/executor.py:164-170]() The Esprit tool system provides a robust framework for building secure, observable, and highly capable security agents by enforcing strict schemas and flexible execution environments.