Skip to content

tools.md

Latest commit

 

History

History
202 lines (128 loc) · 8.07 KB

tools.md

File metadata and controls

202 lines (128 loc) · 8.07 KB
Raw

tools — Built-in Tool Implementations

Package path: offdev/micro-agent-go/internal/tools (re-exports implementations from filesystem, shell, web, memorytool, telegramtool)
Last updated: 2026-03-26

Overview

The tools package provides the built-in core.Tool implementations for filesystem access, shell execution, web access, long-term memory, and Telegram. All tools satisfy the core.Tool interface and are safe for concurrent use.

Filesystem Tools

read_file

Reads file contents. Use optional offset and max_bytes to read large files in chunks without loading the whole file into one tool result.

{ "path": "/path/to/file" }
{ "path": "/path/to/file", "offset": 0, "max_bytes": 50000 }

Returns the file contents (or a chunk). If the read is truncated, a trailing line reports total file size and bytes shown. Errors on missing file or permission denied.

write_file

Writes content to a file, creating the file and any missing parent directories. For very large content, prefer multiple append_file calls to avoid huge tool payloads.

{ "path": "/path/to/file", "content": "file contents" }

Returns "wrote N bytes to /path/to/file" on success.

append_file

Appends content to a file. Creates the file (and parent directories) if it does not exist. Use repeatedly to write large files in chunks so the LLM does not send one huge payload.

{ "path": "/path/to/file", "content": "chunk to append" }

Returns "appended N bytes to path" on success.

edit_file

Replaces the first occurrence of old_text with new_text in an existing file.

{ "path": "/path/to/file", "old_text": "before", "new_text": "after" }

Errors if old_text is not found in the file. Does not create new files.

list_dir

Lists the entries of a directory, showing file sizes.

{ "path": "/path/to/dir" }

Returns one entry per line: name/ for directories, name (N bytes) for files.

Shell Tool

shell_exec

Executes a shell command via sh -c and returns combined stdout + stderr.

{ "command": "ls -la", "timeout": 10 }

Disabled by default (SHELL_EXEC / default.shell_exec in config). Construct with NewShellExec(true) to enable. When disabled, returns an error without executing anything.

Timeout: Defaults to 30 seconds. The timeout parameter caps to the minimum of the requested value and the tool's maxTimeout. Use WithMaxTimeout to change the maximum.

Approval gate: The shell tool does not implement its own approval UI. Use a BeforeToolExecution callback to implement human-in-the-loop approval.

tools.NewShellExec(false)                    // disabled (default for production)
tools.NewShellExec(true)                     // enabled
tools.NewShellExec(true).WithMaxTimeout(60*time.Second)

Browserless Browsing Tools

When a Browserless Chromium service is available (see BROWSERLESS_URL / tools.browserless_url in config), the agent can use browser-based fetching. browser_search requires Browserless (it is not a separate search API).

browser_search

Runs a web search through Browserless (configured base URL).

{ "query": "micro-agent golang" }

Returns result lines derived from the Browserless response. If BROWSERLESS_URL is unset, the tool returns a clear configuration error.

browser_content

Fetches fully rendered page content via Browserless, including JavaScript-rendered text.

{ "url": "https://example.com" }

Returns plain text extracted from the rendered HTML, truncated similarly to web_fetch. Use this for JS-heavy sites where web_fetch may miss content.

browser_screenshot

Captures a PNG screenshot of a page via Browserless.

{ "url": "https://example.com", "full_page": true }

Returns a data:image/png;base64,... string. Use full_page=true for a full scrollable page; otherwise only the viewport is captured.

The default supervisor in internal/app does not register browser_screenshot, and the sub-agent loader does not map the browser_screenshot tool name. Only browser_search, browser_content, and web_fetch are wired for the default supervisor; use NewBrowserScreenshot manually if you extend the app.

If BROWSERLESS_URL is unset or Browserless is unreachable, Browserless-backed tools fail fast with a clear error and the agent can fall back to web_fetch where applicable.

web_fetch

Downloads a URL over HTTP and returns extracted plain text (no JavaScript). The implementation limits the raw body to 512 KiB before extraction and caps returned text at 10 000 Unicode code points (internal/tools/web/web_fetch.go). Default HTTP client timeout is 10 seconds.

{ "url": "https://example.com" }

Messaging Tools

telegram_send

Sends a Telegram message via the Bot API. Format (HTML, Markdown, or plain) is chosen automatically from the message content on each request.

{ "chat_id": "123456789", "text": "Hello!" }
Field Type Required Description
chat_id string no* Numeric chat ID as a string (supports negative group IDs). Required when no default is configured.
text string yes Message content; used as the message body or as the caption when sending an attachment. Truncated to Telegram limits.
photo_url string no Optional HTTPS URL of an image to send as a photo. When set (and photo_path is empty), the tool calls sendPhoto with this URL and uses text as the caption (truncated to 1024 characters).
photo_path string no Optional local filesystem path of an image to upload as a photo. When set (and photo_url is empty), the tool uploads the file via multipart/form-data to sendPhoto and uses text as the caption (truncated to 1024 characters).
document_url string no Optional HTTPS URL of a file to send as a document. When set (and photo_* and document_path are empty), the tool calls sendDocument with this URL and uses text as the caption (truncated to 1024 characters).
document_path string no Optional local filesystem path of a file to upload as a document. When set (and photo_* and document_url are empty), the tool uploads the file via multipart/form-data to sendDocument and uses text as the caption (truncated to 1024 characters).

chat_id becomes optional when TELEGRAM_CHAT_ID (or telegram.chat_id in config) is set; omitting it sends to the configured default chat.

At most one photo field (photo_url or photo_path) and at most one document field (document_url or document_path) may be set. Exactly one of the photo fields or one of the document fields may be provided; providing both a photo and a document in a single call is an error. When neither is set, the tool behaves as a plain sendMessage helper.

When using *_path fields, the path is interpreted on the agent host and the file is uploaded to Telegram using multipart/form-data, as required by the Telegram Bot API sending files documentation. When using *_url fields, the tool sends JSON and lets Telegram fetch the file by URL.

Returns "message sent to chat <chat_id>" on success. Only registered when TELEGRAM_BOT_TOKEN is set in the environment or config.

tools.NewTelegramSend(os.Getenv("TELEGRAM_BOT_TOKEN"), defaultChatID)

Long-term memory tools

See docs/memory.md. memory_save, memory_search, and memory_delete are registered when Milvus-backed storage is available (MEMORY_EMBED + working MILVUS_ADDR).

Registering Tools

Pass tools as a []core.Tool slice to core.Agent.Tools:

agent := &core.Agent{
    Tools: []core.Tool{
        tools.NewReadFile(),
        tools.NewWriteFile(),
        tools.NewAppendFile(),
        tools.NewEditFile(),
        tools.NewListDir(),
        tools.NewShellExec(false),
    },
}