Tools Reference

Tools Reference

OpenBotX is an AI assistant platform. Tools are Python functions the AI agent can call during conversations. This document provides a complete reference for all built-in tools, their parameters, and access rules.

Overview

All tools are registered in openbotx/tools/. The ToolRegistry manages them and generates OpenAI-compatible function definitions for the LLM. Tools are registered via build_registry() in openbotx/tools/registry.py, which is called during agent initialization.

The registry:

1. Stores tool instances.
2. Generates OpenAI-compatible function definitions (sent to the LLM).
3. Executes tool calls by name with arguments.
4. Returns string results back to the agent loop.

Path Resolution

All file-based tools (read_file, write_file, edit_file, list_dir, http_client) use the PathResolver class (openbotx/helpers/path.py) for path resolution and directory restriction enforcement.

How it works:

1. Relative paths are resolved against the agent's workspace directory.
2. ~ (home directory) is expanded via Path.expanduser().
3. When tools.general.restrict_to_workspace is enabled in the config, each agent is restricted to its own workspace directory and the shared public directory. Any path outside these directories raises a PermissionError.
4. When tools.general.restrict_to_workspace is disabled, all paths on the filesystem are accessible.

class PathResolver:
    def __init__(self, workspace: Path | None = None, allowed_dirs: list[Path] | None = None):
        ...

    @property
    def is_restricted(self) -> bool:
        """Returns True when directory restrictions are active."""
        return self._allowed_dirs is not None

    def resolve(self, path: str) -> Path:
        """Resolve a path string to an absolute Path, enforcing allowed directories."""
        # 1. expand ~, resolve relative to workspace
        # 2. if allowed_dirs is set, verify path is inside one of them
        # 3. raise PermissionError if outside allowed directories
        ...

ProjectContext.create_resolver(agent_cfg) creates a PathResolver per agent. This is called inside build_registry() during tool registration:

# In ProjectContext (openbotx/config/project.py):
def create_resolver(self, agent_cfg: AgentConfig) -> PathResolver:
    workspace = agent_cfg.resolve_workspace(self.project_path)
    allowed_dirs = (
        [workspace, self.public_dir]
        if self.tools.general.restrict_to_workspace
        else None
    )
    return PathResolver(workspace=workspace, allowed_dirs=allowed_dirs)

The resolver is created internally by build_registry() and passed to all file-based tools.

Agent-Specific Tool Whitelisting

Each agent can optionally define a tools list in its configuration. When set, only tools whose name appears in this list are registered for that agent. Tools not in the whitelist are silently skipped during build_registry(). When the list is empty (default), all tools are registered.

agents:
  crypto:
    tools: [read_file, write_file, exec, web_search, web_fetch, http_client, rss_reader, browser, message, spawn, cron, memory_save, memory_read, memory_search]

Built-in Tools

File Operations

Source: openbotx/tools/filesystem.py

All file tools receive a PathResolver instance at construction. When tools.general.restrict_to_workspace is enabled, operations are sandboxed to the agent's workspace directory and the shared public directory.

read_file

Read the contents of a file. Supports line-based pagination for large files.

Output limit: Each read returns up to 50 KB of content. When a file exceeds this limit, the output includes the line range shown and the offset value needed to continue reading the next chunk. The agent can call read_file multiple times with increasing offsets to read the full file.

write_file

Create or overwrite a file. Creates parent directories automatically.

edit_file

Search and replace within a file. The old_text must match exactly once. If it appears multiple times, the tool returns a warning asking for more context to make it unique. If not found, it shows a best-match diff with the closest similar text.

list_dir

List the contents of a directory. Items are prefixed with [dir] or [file].

Shell

Source: openbotx/tools/shell.py

exec

Execute a shell command.

The command runs with a configurable timeout (tools.exec.timeout, default 60 seconds). When tools.general.restrict_to_workspace is enabled (detected via PathResolver.is_restricted), the working directory is locked to the workspace.

Output limit: Output larger than 200 KB is truncated using tail-based truncation — only the last 200 KB of output is kept, prefixed with a warning: [Output truncated: showing last 200000 of N chars]. This preserves the most recent output (where errors and results typically appear) while discarding older output.

Web

Source: openbotx/tools/web.py

web_search

Search the web using the Brave Search API.

Requires a Brave Search API key to be configured via a credential (tools.web_search.credential in config.yml).

web_fetch

Fetch and extract content from a URL.

Uses readability-lxml for content extraction.

Communication

Source: openbotx/tools/message.py

message

Send a message to the user via the current channel.

Only available to the main agent (not subagents).

Background Tasks

Source: openbotx/tools/spawn.py

spawn

Launch a subagent for independent background tasks.

Only available to the main agent. Creates a child task on the task board.

Scheduling

Source: openbotx/tools/cron.py

cron

Schedule reminders and recurring tasks.

Only available to the main agent.

Memory

Source: openbotx/tools/memory_tool.py

memory_save

Save conversation history and updated long-term memory. Used during memory consolidation.

memory_read

Read memory files on demand.

memory_search

Search across memory and history files for specific information.

Returns matching lines with 1 line of context before/after, prefixed with the source file and line number.

Browser

Source: openbotx/tools/browser.py CDP Library: openbotx/cdp/ (vendored from python-cdp)

browser

Chrome automation via the Chrome DevTools Protocol (CDP). Requires Google Chrome installed on the host system.

Architecture: A singleton _ChromeInstance manages the Chrome process (launched with --remote-debugging-port=9222 and a persistent profile at ~/.openbotx/chrome-profile). Each BrowserTool instance gets its own tab via target.create_target, enabling concurrent use by the main agent and subagents. The Chrome process starts lazily on the first tool call and is terminated on server shutdown.

Actions:

Click mechanism: The _click method uses a multi-step pure CDP approach:

1. Resolve — runtime.evaluate to get a RemoteObjectId handle for the CSS selector.
2. Scroll — dom.scroll_into_view_if_needed to ensure the element is in the viewport.
3. Position — dom.get_content_quads to get the element's bounding quad, then compute the center point.
4. Click — Dispatch CDP mouse events at the coordinates (mouseMoved → mousePressed → mouseReleased).

HTTP Client

Source: openbotx/tools/http_client.py

http_client

Full HTTP client with download, upload, and authentication support. Uses a PathResolver for file path resolution and CredentialConfig for authentication via credentials.

Content type mapping:

Response format: Returns JSON with status, headers, body, and truncated fields. Response bodies larger than 50,000 characters (50 KB) are truncated.

Download mode: When download_path is set, the file is saved and the response returns status, path, size, and content_type instead of the body.

Upload mode: When upload_file is set, the file is sent as multipart form data. The MIME type is auto-detected from the file extension. Additional form fields can be passed as JSON in the body parameter.

Authentication: When auth is set, the tool looks up the named credential from credentials in the config and applies the appropriate Authorization header. The http_client automatically has access to all credentials with compatible types (oauth1, basic, simple):

Config example:

credentials:
  twitter:
    type: oauth1
    consumer_key: ${TWITTER_CONSUMER_KEY}
    consumer_secret: ${TWITTER_CONSUMER_SECRET}
    access_token: ${TWITTER_ACCESS_TOKEN}
    access_token_secret: ${TWITTER_ACCESS_TOKEN_SECRET}
  my_api:
    type: simple
    key: ${MY_API_TOKEN}

RSS Reader

Source: openbotx/tools/rss.py

rss_reader

Read RSS and Atom feeds and return the latest entries.

Supports both RSS 2.0 and Atom feed formats. Automatically detects the format by trying RSS first, then Atom. HTML tags are stripped from summary fields.

Response format: Returns JSON with url, count, and entries array. Each entry has title, link, published, and summary fields.

Image Generation

Source: openbotx/tools/image.py

generate_image

Generate images using AI models.

Requires image generation configuration. The image.model field uses the same provider/model format as agents (e.g. openai/dall-e-3). Only registered when the model's provider prefix matches a configured provider with a valid credential.

Tool Access by Agent Type

Not all tools are available to every agent type. The main agent has full access, while subagents have a focused subset. Additionally, individual agents can restrict their tool set via the tools whitelist in their configuration.

* generate_image and browser are available to subagents only when their dependencies are satisfied (Chrome installed for browser, image API key configured for generate_image).

Subagents have access to file operations, shell execution, web tools, the HTTP client, RSS reader, browser automation, and image generation. Tools that interact with the user (message), manage other agents (spawn), schedule tasks (cron), or access memory (memory_save, memory_read, memory_search) are restricted to the main agent.

Both main agents and subagents share the same PathResolver instance, so they have identical directory access restrictions.