Skip to content

The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.

13.7 KB
Raw Blame

tools

The agent tool layer. This folder assembles the list of tools an agent session runs against, holds the cross-cutting built-in tools (filesystem gate, browser, process and system, generic network, document and presentation generation), and owns the policy around tools: which ones a channel may see, which ones are packed out of the prompt, how long a call may run, and how a failure is described. The agent session builder is the main caller. A small allowlist of tool-like operations is also exposed over JSON-RPC for the desktop shell.

Domain-owned tools (memory, cron, flows, wallet, Composio, skills, voice, agent sub-dispatch) live in their own domains. Each domain supplies an explicit tool factory; ops.rs combines those factories in registry order. Callers import individual tools from their owning domain.

How it works

Building a session's registry

ops::all_tools_with_runtime (ops.rs) is the one place a full registry is assembled. It is called by the session builder (agent/session_host/builder/factory.rs) and at channel startup (channels/runtime/startup/start_channels.rs). The order of work:

 Config, SecurityPolicy, AuditLogger, RuntimeAdapter, action_dir
        |
        v
 host `node` / `python3` commands used through shell
        |
        v
 base vec: shell, file_read, file_write, grep, glob, list, edit,
           apply_patch, csv_export, sub-agent dispatch, todo, plan,
           cron, time, detect/install, retrieve_tool_output, ...
        |
        v
 feature- and config-gated families appended
   flows, web3, voice, skills, mcp, documents, media, hosting,
   memory (memory::engine::is_on), browser (browser.enabled),
   gitbooks (gitbooks.enabled), search, integrations, composio, delegate
        |
        v
 post-filter 1: DomainSet      drop tools whose DomainGroup is off
 post-filter 2: ToolGroups     drop tools in a group set to Off
        |
        v
 append use_skill (toolpacks)
        |
        v
 Vec<Box<dyn Tool>>  --> factory.rs: filter_tools_by_user_preference

Most families gate twice: once at compile time with a Cargo feature (flows, web3, voice, skills, mcp, modules, documents, media, hosting) and once at runtime from config. A tool that cannot work is left out rather than registered and failing, because a model retries a failing tool. For example, the memory tool registers only while a memory engine is usable, gitbooks and the static MCP bridge are skipped when their client cannot be built, and hosting tools register only once a credential resolves.

The two post-filters both default open: with no ambient CoreContext (unit tests, pre-boot) nothing is dropped. tool_group in ops.rs maps a tool name to its DomainGroup, by prefix for families that have one (wallet_, web3_, x402_, media_, mcp_) and by explicit list for the rest (skills, flows, voice). A tool name missing from a list falls through to Platform and stays callable when its family is gated off, so the lists must track the registrations.

default_tools and default_tools_with_runtime build a minimal registry (shell, file_read, file_write) with a disabled audit logger. They are for tests and the lightweight CLI surface.

Orchestrator tools

The orchestrator uses the single spawn_subagent tool, whose agent_id enum is derived from the [subagents] allowlist. integrations::composio::orchestrator_actions::collect_orchestrator_tools only expands a SubagentEntry::Skills wildcard to one ToolExposure::Deferred ComposioActionTool per action of every connected Composio toolkit. Deferred tools never reach the wire: an agent that opted into discovery finds them through the harness's tool_search bridge and calls them by name. Connected MCP server actions are registered the same way by mcp/registry/action_tool.rs.

What the model sees

Several layers narrow the registry before a schema is sent:

  • user_filter.rs maps UI toggle ids to tool names (TOOL_FAMILIES). A default-on family missing from a stale snapshot is kept; a default-off family (installers, mutators, service lifecycle) is stripped unless the user enabled it. Tools no family covers are always kept.
  • toolpacks/ keeps a pack's tools constructed but unadvertised. The agent sees use_skill and a short pack index instead of the real schemas. See toolpacks/README.md.
  • ToolExposure::Deferred tools (impl/meta/deferred.rs holds the host half) are left off the wire until found with tool_search.
  • agent_policy/ classifies every tool against the channel's permission ceiling into allow, require-approval, deny or hide, and renders the prompt's tool-boundary section. See agent_policy/README.md.

Executing a call

The Tool trait and its vocabulary come from tinytools. The tinyagents harness runs the loop; OpenHuman's host adapters decide policy. Before a tool runs, the security gate (agent/tinyagents/host/security_gate.rs) checks the tier, the command class and the approval gate; the tool itself then checks SecurityPolicy for paths, commands and the action budget. The autonomy policy is off by default (see ../security/README.md), so on a default install the path floor and the sandbox do the bounding. Process-spawning tools in sandboxed mode route through ../sandbox/. Each call is bounded by timeout/, and a failure is classified by status/ into a plain-language cause and next step.

Layout

Path What it does
mod.rs Cross-cutting tool modules, their built-in exports, and the all_tools_* controller pair. Domain factories are called explicitly from ops.rs; tool contracts come directly from tinytools.
ops.rs Registry assembly (default_tools*, all_tools*), all config and feature gating, and tool_group.
Deferred Composio action expansion integrations/composio/orchestrator_actions.rs.
user_filter.rs filter_tools_by_user_preference and the UI toggle to tool-name map.
host_extensions.rs Readers over tinytools' erased host-extension slots: pack_registry_handle, tool_call_id.
schemas.rs, schemas/ The tools.* controllers: registry.rs (schemas and dispatch), composio.rs, web_search.rs.
impl/ Built-in tool families: filesystem/ (the FsGate adapter only; the tools are tinyagents_harness_tools::fs::filesystem), browser/, system/, network/, meta/, and the documents-gated document/ and presentation/.
toolpacks/ On-demand tool disclosure (use_skill, pack catalog, guides) and ToolGroups / GroupMode.
agent_policy/ Per-session tool boundary against a channel's permission ceiling.
registry/ Read-only discovery registry across MCP stdio, controller and connected MCP tools, plus policy diagnostics.
timeout/ Process-wide tool timeout and process-group kill helpers.
status/ Tool-call lifecycle state and failure classification (classify, describe, tool_execution_error).

Where the built-in tools come from:

Tools Source
file_read, file_write, edit, apply_patch, grep, glob, list, read_diff, csv_export, git_operations, run_linter, run_tests, image_info, read_workspace_state tinyagents_harness_tools::fs::filesystem, gated by impl/filesystem/gate.rs
detect_tools, curl, pushover tinyagents_harness_tools
http_request, web_fetch tinyagents_harness_tools::net::network, wired with host limits, TinyJuice extraction and the x402 handler in impl/network/host.rs
current_time, resolve_time, ask_user_clarification tinyagents_harness_tools
shell, install_tool, schedule, proxy_config, retrieve_tool_output impl/system/
update_check, update_apply platform/update/tools.rs
gitbooks_search, gitbooks_get_page, mcp_list_servers, mcp_list_tools, mcp_call_tool, mcp_<server>_<tool> impl/network/ (MCP tools behind mcp)
gmail_unsubscribe integrations/gmail/
browser, browser_open impl/browser/ (behind modules)
generate_document, generate_presentation impl/document/, impl/presentation/ (behind documents)
web_search and the other search roles crate::search::build_search_tools

Key types and entry points

  • Tool, ToolSpec, ToolResult, ToolExposure, PermissionLevel, ToolScope, ToolCategory: imported from the vendored tinytools contract. Embedders get Tool, ToolResult, ToolExposure and PermissionLevel from the curated openhuman_embed facade.
  • ops::all_tools_with_runtime: the full registry. Its last parameter, approval_workspace_root, scopes file_write's approval prompts.
  • integrations::composio::orchestrator_actions::{collect_orchestrator_tools, collect_deferred_integration_actions}.
  • filter_tools_by_user_preference (crate-internal, user_filter.rs).
  • toolpacks::{append_pack_tools, bind_pack_registry, strip_packed_from_visible} and toolpacks::groups::{ToolGroups, GroupMode, current}. openhuman-embed re-exports ToolGroups and GroupMode as its tool-visibility control.
  • timeout::{tool_execution_timeout_secs, set_tool_timeout_secs, output_or_kill, kill_process_group}.
  • status::{classify, ToolLifecycleState, ToolFailureClass, ClassifiedFailure}.

RPC surface

Namespace tools, registered in core/all.rs through all_tools_registered_controllers. Wire names follow openhuman.<namespace>_<function>. The list is deliberately small; anything else is agent-only.

Method Purpose
openhuman.tools_composio_execute Run a Composio action through the mode-aware client (backend-proxied or direct).
openhuman.tools_web_search Ranked web search through the search role; results plus the provider that answered.
openhuman.tools_web_answer Grounded answer with citations through the answer role.
openhuman.tools_web_contents Page contents for given URLs through the contents role.
openhuman.tools_searxng_search The search role pinned to a self-hosted SearXNG (requires SearXNG enabled).

registry/ registers a second namespace, tool_registry (list, get, diagnostics). Dotted ids such as tools.web_search in that registry are tool_ids, not RPC methods.

Boundaries

  • The Tool trait, ToolResult, ToolExposure and the generic filesystem and network tools belong to tinytools (vendor/tinyagents/vendor/tinytools). Use that one copy; a second path produces incompatible types.
  • The agent loop, tool-call parsing, tool_search, use_skill and the pack registry handle belong to tinyagents (vendor/tinyagents).
  • Execution policy (paths, commands, approvals) is security/; where a command runs is sandbox/.
  • Search provider resolution and the TinySearch bridge are crate::search (see ../search/README.md); the module itself is tinysearch.
  • New domain tools go in the owning domain's tools.rs. Its registration function builds that family, and ops.rs composes the families before applying capability filters. Preserve catalogue order when moving registrations. Only cross-cutting families belong under impl/.
  • This folder has no persistence and no event-bus subscriber. Approval routing reads Tool::external_effect_with_args; the gate itself is security/approval/.

Gotchas

  • Override external_effect_with_args, not only external_effect, when a tool's effect depends on its arguments (Composio execute versus list). The harness checks the per-call variant.
  • PermissionLevel ordering is compared with < against a channel's maximum. A multi-action tool should return its lowest level from permission_level() and do the per-call check in permission_level_with_args.
  • is_concurrency_safe tells the harness a call may run alongside others in the same batch. Return true only for calls with no shared side effects.
  • The shell inherits the host PATH; Node.js and Python commands run with the host toolchain.
  • The browser shares http_request.allowed_domains but strips the * wildcard, so unifying the lists can only narrow browser reach. Allow-all stays behind OPENHUMAN_BROWSER_ALLOW_ALL.
  • Search is configured per provider and per role in [search]; disabling all providers removes the search tools. User-facing setup is in docs/gitbooks/en/features/native-tools/web-search.md.

Tests

Registry tests are split by concern under ops_tests*.rs (default registry, capability gating, domain families, Composio registration, REPL tools, execution and serde). Every other module has a sibling *_tests.rs. Run with cargo test -p openhuman tools:: or pnpm debug rust tools.

Further reading