Tool Extension
Agenvoy supports four ways to add tools beyond the built-in set: auto-generation from a capability gap, script tools, API tools, and MCP tools. Tools installed by an extension land under ~/.config/agenvoy/tools/.extension/ and register with the ext_ prefix.
Auto-generation (Capability Gap)
When a user request needs live external data (weather, currency, stock, geocoding, translation, etc.) and no existing tool covers it, the agent creates the tool on the spot, then runs it to answer. No programming required.
reasoning_guide(topic=tool_generate) carries the build contract; the same text is exposed to external agents through the MCP server as tool_generate_guide. The sequence:
| Step | Action |
|---|---|
| 1. Find a suitable API | api_public_api_list(type=category) to pick relevant categories, select the best candidate (prefer no-auth + HTTPS), then fetch_page the docs |
| 2. Decide the tool type | Multi-step logic or computation → script tool (tool.json + script.py); a single REST endpoint with no computation → API tool (one JSON file) |
| 3. Write it | edit_tool(mode=write) with tag=json + tag=script, or tag=api for the declarative form |
| 4. Verify | test_tool runs script.py in the sandbox; failures are fixed with edit_tool(mode=patch) |
| 5. Answer | Call the new tool and answer from its output |
After creation, the tool persists under ~/.config/agenvoy/tools/script/<name>/ (or tools/api/<name>.json) and is available in all future sessions and to every connected MCP agent. Credentials are never hardcoded: the naming convention is {BRAND}_API_KEY, captured with store_secret and read back from the local keychain endpoint GET http://localhost:17989/v1/key?key=<KEY_NAME>.
Key constraints:
- The agent must never answer with raw
http_requestor an inlinepython3 -c; it must write a reusable tool to disk fetch_pageis allowed only for reading API documentation, not for fetching answer data- Names are
snake_caseverb + noun (fetch_weather,calculate_rsi) with no prefix — the runtime addsscript_orapi_
Script tools (script_*)
Put a tool.json descriptor and a script.py (Python) or script.js (JavaScript) under ~/.config/agenvoy/tools/script/<name>/, or the project-local <cwd>/.config/agenvoy/tools/script/<name>/. Agenvoy auto-registers it as script_<name>. The former extensions/scripts/<name>/ + run.py layout is not scanned; extension-installed scripts under tools/.extension/script/ register as ext_<name>.
~/.config/agenvoy/tools/script/my_tool/
├── tool.json # name, description, parameter schema
└── script.py # actual script (or script.js)
API tools (api_*)
Drop a JSON file under ~/.config/agenvoy/tools/api/<name>.json (or the project-local <cwd>/.config/agenvoy/tools/api/) describing a REST endpoint. It auto-registers as api_<name>. extensions/apis/*.json is compiled into the binary as built-in API tools (e.g. public-api-list.json → api_public_api_list).
Confirm gate — api_* tools are not prefix-exempt from confirmation. Users may define destructive endpoints (DELETE / POST writes), so each call is confirmed under the active permission mode unless its descriptor sets "always_allow": true. For batch auto-approval, turn on auto mode (Shift+Tab) or send allow_all: true on the request.
MCP tools (mcp__*)
Tools exposed by an MCP server are auto-registered as mcp__<server>__<tool>. MCP tool output is capped at 1 MiB per call to keep tool results within provider limits.