Tool Executor
What it is
The execution layer that runs model-requested tools sequentially or concurrently when safe.
In plain terms
Picture a construction crew where each worker can hammer nails into a different wall at the same moment without getting in anyone’s way, but if two of them reach for the same ladder, one has to wait their turn. Tool Executor makes that same call on the model’s behalf: independent tool requests get to run together, while two edits aimed at the same file get lined up one after another instead of racing each other.
Why it matters
When a model’s response asks for several tool calls at once, something has to decide whether they’re safe to run in parallel or need to happen one at a time — a file write and a web search can overlap, but two edits to the same file can’t. That decision is what keeps a multi-tool turn from silently corrupting state or racing against itself. Agent team delegation depends on the same execution layer to keep parallel subagents from stepping on each other’s changes.
How it works
Before anything runs, _should_parallelize_tool_batch (agent/tool_dispatch_helpers.py) inspects the whole batch of requested tool calls: it forces sequential execution if any tool is on a fixed never-parallel list, if arguments fail to parse, or if two path-scoped calls like read_file, write_file, or patch target overlapping paths; a fixed set of read-only tools such as web_search and vision_analyze are always cleared to run together. AIAgent._execute_tool_calls (run_agent.py) reads that verdict and dispatches to either execute_tool_calls_concurrent or execute_tool_calls_sequential (agent/tool_executor.py), the concurrent path using a thread pool capped at 8 workers. Concurrent results are collected back in the original call order before being appended to the message list, so the model sees them exactly as it requested them.
A concrete example
A model reply asks for three tool calls at once: a web search for headlines, a separate web search for stock prices, and a write_file call to save notes.
- _should_parallelize_tool_batch sees two read-only searches plus a file write to a path nothing else touches, so it clears all three to run concurrently.
- All three execute at once on separate threads.
- If the reply had instead asked for two write_file calls aimed at the same notes.txt, that same check would force them to run one after the other instead, so the second write can’t silently clobber whatever the first one just wrote.
How it connects
This note belongs to the Runtime family. Its closest neighboring concepts are: Conversation Loop, Turn Finalizer, Personal OS.
Source evidence
vendor/hermes-agent/agent/tool_executor.py#<file>— Structural Source Map fallback for agent/tool_executor.py. A core source file in the Tool Execution Pipeline structure within Tools, Toolsets, and MCP.
Workflows
- Agent Team Delegation
Related articles
- No article currently mentions this concept by name/alias often enough to qualify (see mention-mining policy).