Agent Routing
Last updated
The ways a request reaches an agent: automatic dispatch, the subagents tool, and external agents.
Two ways decide which agent handles a task:
1. Automatic — A dispatcher LLM analyzes the input and picks the best-fit provider via
exec/model.Route (ResolveAgent() before v1.2.1). Since v1.1.0 pass-tier models are never picked or used as fallbacks; a session pinned to a model still uses it.Startup order:
exec.Prepare (TUI-only exclusions, /skill-name match) → exec.Run (named skill resolution, agent resolution, session load; exec.Start was renamed exec.Run in v1.2.1) → Execute. Subagents and schedules call exec.Run directly with isSub=true and skip exec.Prepare. A named skill that is excluded or not found fails the run.The
:self-id one-shot override prefix was removed; delegate to a named session with subagents(self_id=...), or switch sessions with /session.2.
subagents tool — An agent calls another agent in-process (no HTTP) during execution, inheriting AllowAll and WorkDir from the parent ctx. Since v1.1.0 mode=invoke requires model — the dispatcher fallback for a blank model was dropped; pass model: "auto" (hotfix after v1.1.0) to let the dispatcher pick from the task — and the tier list the parent picks from in reasoning_guide(topics=[subagent_dispatch]) starts one tier lower than for its own work (S → A, A → B, B → C). An explicitly named model overrides the model a self_id session is pinned to; model: "auto" reuses that pinned model and only lets the dispatcher pick when there is none. reasoning defaults to auto, and an invalid level returns an error listing the valid ones.Subagents run under a collection-only charter — they gather and report, they don't nest or write. The exclusion set is built from three parts:
| Source | Excluded |
|---|---|
| Charter base | subagents, background_subagents (since v1.3.2), edit_file, remove_file and restore_file (since v1.3.11), edit_tool, test_tool, edit_skill, write_result, html_template, generate* (wildcard), open_file, schedules, store_secret (since v1.2.1; before that only subagents, edit_file, generate*). pkg_manage was Removed in v1.3.2 along with the tool |
| TUI-only tools / skills | Whatever configs/jsons/tui_tools.json lists, e.g. extension-upload, extension-install |
Caller's exclude_tools | Anything the parent passes in |
ask_user is not excluded — subagents can ask the user through the shared pending registry. A subagent's pending question is also published to the owning (parent) session, and the leg waits for that resume and returns the answered result. Subagent legs execute concurrently up to MAX_CONCURRENT_SUBAGENTS (half the CPU cores, at least 3); a leg past that limit waits for a slot while its own MAX_SUBAGENT_TIMEOUT_MIN (30 min) timeout is already running, so wide fan-outs should be dispatched in batches no larger than that limit. Each result carries a usage header that rolls up into the parent session's totals; since v1.0.22 the report itself is saved to ~/.config/agenvoy/download/temp-<report_name>.md and only its path comes back.