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 | write_tool 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 patch_tool |
| 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
send_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_*)
Drop a Python / Node.js / shell script under extensions/scripts/<name>/ along with a tool.json descriptor. Agenvoy auto-registers it as script_<name> at startup.
extensions/scripts/my-tool/
├── tool.json # name, description, parameter schema, command
└── run.py # actual script
API tools (api_*)
Drop a JSON file under extensions/apis/<name>.json (or ~/.config/agenvoy/tools/api/<name>.json) describing a REST endpoint. It auto-registers as api_<name>.
Confirm gate — api_* tools are not prefix-exempt from confirmation. Users may define destructive endpoints (DELETE / POST writes), so agen cli confirms each call. Use agen run for batch auto-approval.
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.