How-To Guide
Hermes Subagent Delegation: Configure Models, Costs, Limits, and Fallbacks
Configure Hermes Agent subagents with isolated context, model and provider pins, concurrency limits, fallback chains, worktrees, and measured cost controls.
Quick answer
Use delegate_task only for independent work that needs reasoning. Start with leaf children, max_concurrent_children: 1, a bounded max_iterations, and a tested worker model pinned under delegation.model and delegation.provider. Children receive isolated context and return summaries; they inherit the parent's enabled toolsets but cannot widen their own capabilities. Measure total provider usage and accepted outputs, then raise concurrency only if it improves completion time without causing 429 errors, duplicate work, or expensive retries.
Hermes subagent delegation is useful when independent workstreams need judgment, tools, and separate context. It is not a generic speed switch. Each child runs a full agent loop, so parallelism can reduce elapsed time while increasing total model calls, token use, rate-limit pressure, and review work. Configure the worker lane deliberately, keep child permissions bounded, and measure accepted-task cost before increasing concurrency.
Managed cloud · API costs included · Skill library · Cancel anytime
Before you start:
- ☑Hermes Agent installed and verified with
hermes doctor - ☑The parent workflow succeeds once without delegation
- ☑A provider/model route with enough quota for concurrent agent loops
- ☑Clear subtask boundaries and an explicit output contract for each child
- ☑A verification step that the parent can run after merging child results
Steps
- 1
Prove the task with one agent first
Run the workflow serially before adding workers. Delegation cannot repair a broken provider route, vague acceptance criteria, missing tools, or an incorrect working directory. Record the successful artifact, elapsed time, retries, and provider usage as the baseline.
- 2
Choose delegation instead of mechanical execution
Use
delegate_taskwhen the child needs judgment, research, or multi-step tool use. Use code execution or a deterministic script for mechanical API loops, parsing, deduplication, and batch transforms; a full child agent is usually unnecessary overhead for those jobs. - 3
Split only independent workstreams
Give each child one bounded mission, its sources or files, an output path or response schema, and a definition of done. Do not ask several children to edit the same file or infer shared state unless worktree isolation and an explicit merge owner are in place.
- 4
Start with leaf children
Leaf is the default role. Leaf children cannot delegate again, ask the user for clarification, write shared persistent memory, schedule cron jobs, or send cross-platform messages. This keeps the parent responsible for orchestration, user interaction, and side effects.
- 5
Set the child iteration budget
Configure
delegation.max_iterationsto bound each child agent loop. The documented default is 50, but a smaller limit is sensible for narrow work. Iteration limits are not token limits: a few long-context calls can still cost more than many short calls. - 6
Begin with one concurrent child
Set
delegation.max_concurrent_children: 1for the first measured run, then test 2 and 3 only when the work genuinely parallelizes. More workers can create token-per-minute bursts, provider 429 errors, duplicate browsing, and merge conflicts without improving accepted output. - 7
Pin a worker model and provider
Set
delegation.modeland, when needed,delegation.provider. If omitted, children inherit the parent's route. Keep the parent on the model that plans and reviews well; use a cheaper worker only after it passes the exact delegated task. The worker pin is global fordelegate_task, not selectable per child call. - 8
Understand credential and fallback behavior
Children inherit the parent's authorized credential pool and configured primary fallback chain unless their provider route is explicitly overridden. A fallback can preserve completion, but switching provider/model may invalidate prompt-cache savings and make a long retry more expensive. Test the primary and fallback paths separately.
- 9
Verify inherited tool boundaries
Subagents inherit the parent's enabled toolsets; a child cannot grant itself a toolset that was unavailable to the parent. Configure tools before starting the conversation because tool changes require a new session. Confirm that leaf-only blocks match the side effects your workflow permits.
- 10
Use worktree isolation for parallel code edits
Enable delegation worktree isolation when multiple coding children must change a repository. Assign separate file or component ownership, require tests in each worktree, and make the parent or a dedicated reviewer responsible for integration. Isolation prevents collisions; it does not resolve conflicting designs.
- 11
Enable nested orchestration only with a reason
An orchestrator child can spawn descendants only when
max_spawn_depthis raised above the flat default and orchestration is enabled. Start flat. Every deeper layer adds model calls, handoffs, context summaries, and cost, while making failure ownership harder to inspect. - 12
Measure and accept the final result
After each run, record provider/model, child count, elapsed time, total usage, retries, 402/429 errors, artifacts produced, and outputs that passed verification. Compare cost per accepted task with the single-agent baseline. Keep delegation only where it buys meaningful speed or better coverage.
Pro Tips
- 💡The majority of tokens in a parallel run often live in workers, so optimize the worker model after preserving parent planning quality.
- 💡Only child summaries return to the parent's conversation, which limits context growth but makes precise output contracts essential.
- 💡Stagger unrelated scheduled jobs so cron runs and subagent batches do not create the same provider-rate burst.
- 💡A cheaper model that retries, misuses tools, or produces rejected output can cost more per accepted task than a stronger model.
- 💡Keep side effects with the parent: children should research or prepare artifacts; the parent should verify, publish, send, or mutate external systems.
- 💡Use the Hermes dashboard and provider usage console together: one shows agent/run state, the other shows the actual billing and quota lane.
Troubleshooting
❌ Children do not start
✅ Confirm the delegation toolset was enabled before the session, start a new session after tool changes, check hermes doctor, and run a one-child task. Orchestrator mode is not required for ordinary leaf delegation.
❌ A parallel batch hits HTTP 429
✅ Reduce max_concurrent_children to 1, stagger other cron or gateway work, lower child context, and inspect token-per-minute pressure. Add another credential only when it is authorized and has genuinely separate usable quota.
❌ Delegation causes unexpected spend
✅ Inspect the child provider/model, number of children, iterations, retries, context size, and fallback activation. Pin a tested worker model, shrink task scope, and compare total cost per accepted output rather than per-token list price.
❌ A child cannot use a required tool
✅ Children inherit the parent's enabled toolsets and cannot widen them. Enable the required parent toolset, then start a new session. Also check leaf restrictions for user interaction, scheduling, memory writes, and cross-platform sends.
❌ Several children edit the same files
✅ Stop the batch from sharing a working tree. Assign non-overlapping ownership or enable worktree isolation, then merge through one reviewer with targeted tests and a final full build.
❌ The fallback worked but the run became expensive
✅ Provider/model switching can lose prompt-cache reuse and replay a large context at full input cost. Shorten the delegated context, use a stable primary route, and reserve fallback for completion resilience rather than normal routing.
❌ Nested children multiply without useful output
✅ Return to leaf roles and max_spawn_depth: 1. Raise depth only for a documented hierarchy where every orchestrator has bounded children, artifacts, and a merge contract.
FAQ
Do Hermes subagents share the parent's whole conversation?
No. Each child receives a fresh isolated context built for its task. The child returns a summary to the parent, which keeps the main conversation smaller but requires the delegation prompt to include every fact and constraint the child needs.
Do subagents inherit tools and credentials?
They inherit the parent's enabled toolsets and authorized provider configuration, subject to child-role restrictions. They cannot enable extra capabilities for themselves, and leaf children cannot perform several user-facing or shared-state side effects.
Can every child use a different model?
Not through the normal delegate_task call. delegation.model is a global worker pin. Leave it unset to inherit the parent model, change the session-level configuration, or use a task system that explicitly supports per-task model overrides.
How many subagents should run at once?
Start with one, then measure two or three. The right number depends on independent work, provider request and token limits, context size, tool latency, and merge overhead. Maximum parallelism is not the same as fastest accepted completion.
Does delegation reduce cost?
Usually it reduces wall-clock time, not automatically cost. It can lower cost when a cheaper worker handles well-specified tasks successfully, but parallel full agent loops can also multiply token use, retries, and review work.
Do Hermes subagents use fallback providers?
Current Hermes documentation says delegated agents inherit the parent's configured primary fallback chain, while an explicit delegation provider/model can choose their primary worker route. Test both lanes because fallback can change price, cache behavior, and tool-call quality.
When should I use code execution instead of a subagent?
Use deterministic code for parsing, arithmetic, API pagination, deduplication, file transforms, and other mechanical loops. Use a subagent when the work requires interpretation, judgment, research choices, or a multi-step tool-using investigation.
Is managed hosting required for subagents?
No. Hermes can run delegation locally or on infrastructure you control. Managed FlyHermes is the commercial path when you want browser/mobile access and less responsibility for provider setup, uptime, gateway operations, and monitoring.
Related setup and cost guides
Subagent feature overview
Understand isolated child-agent roles and the delegation boundary.
Multi-agent workflow guide
Design parent, worker, reviewer, and artifact handoffs.
Provider costs and rate limits
Diagnose 402/429 errors, subscription boundaries, retries, and auxiliary spend.
Provider fallback guide
Configure credential pools and cross-provider resilience deliberately.
Hermes dashboard
Inspect agent, provider, session, and operational state from the self-hosted control surface.