Introducing a new way to review your PRs.

Read the announcement

nousresearch / hermes-agent

The agent that grows with you

View on GitHub

38 documents · Updated Nov 20, 2026

docs / delegated-agent-workflows

Delegated agent workflows

Hermes lets a primary agent split bounded work into child agent runs. The primary gives each child a goal and the context it needs, while Hermes manages isolation, routing, progress, completion, and delivery back to the originating conversation. Routing and execution details are covered in Delegation routing and execution.

Delegation model

Delegation is a controlled fan-out from one primary agent to one or more child agents. A child starts with a fresh conversation and works in its own agent session, so the primary must pass the task context explicitly. The child returns a summary rather than its full intermediate work to the primary.

The workflow supports two shapes:

  • Single task: one bounded goal runs as one child.
  • Parallel batch: several independent goals run as separate children and return as one consolidated result by default.

Each task can also define an output contract. Hermes checks the child result against that contract and keeps the raw result when the child still does not match after the limited correction step.

References: tools/delegate_tool.py• L551-665 website/…/delegation.md• L34-78 website/…/delegation.md• L80-105

Child boundaries

Child agents are bounded by their own conversation, terminal session, tool access, and execution budget. A child normally cannot ask the user questions or use the parent’s conversation history. Its final summary is a report for the parent, not proof that an external side effect succeeded.

The delegation tree can stay flat or allow bounded orchestration. When deeper delegation is enabled, an orchestrator child can assign independent work to its own children until the configured depth limit. The limit controls scope and cost, while concurrency limits control how many children run at the same time.

References: tools/delegate_tool.py• L203-260 tools/delegate_tool_config.py• L93-177 tools/delegate_tool_progress.py• L158-219

Work assignment

The primary agent assigns work through the delegate_task capability. A useful assignment states the outcome, supplies the facts and paths the child needs, and sets any required result shape. This keeps the child focused and prevents it from guessing about the parent’s earlier discussion.

When the work is independent, the primary can submit a batch. Hermes tracks each task separately, so one refused or failed task does not hide the outcome of its siblings. Grouping affects how results are delivered to the primary; it does not change the fact that the tasks execute as separate children.

References: tools/delegate_tool.py• L551-665 website/…/delegation.md• L184-217 tools/delegate_tool_routes.py• L288-339

Backend and model routes

Delegation routing selects where each child runs without moving lifecycle control out of Hermes. The active delegation backend decides the route for each task. A route can inherit the primary route, select a provider and model, use a direct endpoint, apply a reasoning or speed setting, or run under a named Hermes profile.

The default backend uses the delegation settings for the profile. Other backends can add task choices such as a named model option or profile. Hermes validates the selected route before it starts the child. A route that cannot be resolved refuses that task instead of silently using a different backend.

Backend selection is part of the session’s tool contract. A saved backend change normally takes effect in a new session. An explicit apply-now action rebuilds the current session’s delegation tool so its task choices and route agree.

References: agent/delegation_provider.py• L1-33 tools/delegate_tool_routes.py• L29-53 agent/delegation_backends.py• L1-9 agent/delegation_backends.py• L78-132

Profile routes

A profile route runs the child as the named Hermes profile. That profile supplies the child’s model, credentials, fallback policy, skills, identity guidance, and terminal policy. The child’s work remains part of the parent’s delegation record even though its model context and profile scope are separate.

This route is useful when a task needs a distinct operating policy or credential set. Hermes binds the target profile for the child’s work and does not use the launching profile’s secrets as a fallback.

References: tools/delegate_tool_routes.py• L111-153 tools/delegate_tool_routes.py• L190-221 website/…/delegation-provider-plugin.md• L115-130

Progress and outcomes

Hermes exposes delegation as a live workflow rather than only as a final tool response. Child progress includes the task goal, current activity, model when known, status, timing, and the child session identity. Terminal results include summaries and failure states for each task.

The main product surfaces join three views of one child: the original task request, live progress events, and the settled result. This lets a user see what is running, open a child session when one is available, and distinguish completion from failure or interruption.

This diagram shows how an assignment moves from the primary agent through child execution and back to the product surfaces.

flowchart LR
    P[Primary agent] --> A[Delegation assignment]
    A --> R[Backend and model route]
    R --> C[Bounded child run]
    C --> L[Progress events]
    C --> O[Task outcome]
    L --> S[CLI, TUI, gateway, and Desktop surfaces]
    O --> S
    O --> P

References: tools/delegate_tool_progress.py• L97-142 apps/…/subagents.ts• L5-40 apps/…/delegate-model.ts• L7-30 apps/…/delegate.tsx• L57-129

Background delivery

A background delegation lets the primary continue after dispatch. Hermes returns a handle, runs the child work separately, and delivers the completion as a new event between turns. The primary conversation can then use the child outcome without polling the child transcript.

Background completions are tied to the originating session and profile. Hermes records the dispatch and result durably before delivery, so a restart can restore a finished result. This recovery does not resume child execution; work that was still running when its owner disappeared is reported as unknown.

The delivery path serves more than one product surface. The CLI and TUI show child activity and completion notices, the gateway routes results to the owning conversation, and Desktop keeps a session-scoped view of active children and recent failures.

References: tools/async_delegation.py• L1-8 tools/async_delegation.py• L166-193 tools/async_delegation.py• L222-255 tools/async_delegation.py• L635-704 apps/…/background-delegation.ts• L5-19 gateway/session_worker_delegation.py• L124-164

Product surfaces

Delegation uses shared child identity and result data across the user-facing surfaces. Each surface presents the same workflow with a different level of detail.

SurfaceDelegation view
CLILive child activity, per-task completion lines, and final summaries.
TUIActive child state, control actions, and delegation status such as pause and limits.
GatewayProgress and completion events routed back to the owning session or transport.
DesktopChild cards in chat, model and route details, live activity, terminal status, and links to child sessions.

Desktop also provides profile-scoped controls for the active backend and its model or profile routes. The settings view reports unavailable backends instead of allowing a route that cannot run.

References: apps/…/delegate.tsx• L133-165 apps/…/delegate-model.ts• L73-158 apps/…/delegation.ts• L3-98 ui-tui/…/delegationStore.ts• L5-29

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep the task route, child model metadata, and result route information aligned so users can tell where each child ran.
  • Keep progress and terminal status mappings consistent across the child event stream, durable completion records, and Desktop rows.
  • Keep session and profile ownership on background completion records so a restart or concurrent consumer cannot deliver a result to the wrong conversation.
  • When backend task parameters change, update the session refresh behavior because the delegation schema is part of the cached tool contract.

Important failure modes

TriggerConsequenceGuard
Child receives an incomplete goal or contextIt works from missing facts and can return an incorrect summary.The parent must pass the needed context in the assignment.
Selected backend or route is unavailableThe affected task does not start.Hermes refuses the task and reports the route error instead of silently falling back.
Background owner session closes or resetsNew work is refused and running children are interrupted.Session ownership fences and explicit interruption propagate through the child tree.
Completion cannot be admitted by its target surfaceThe result stays pending for retry rather than being acknowledged as delivered.Durable claims, ownership checks, and bounded delivery attempts protect the completion path.
Child exits while external work is still runningThe child-owned process is stopped or the work is not safely transferred.The child must wait for the process or explicitly hand it off before returning.

Key files

FileWhy to read it
tools/delegate_tool.pyMain assignment entry point and child lifecycle boundary.
tools/delegate_tool_routes.pyPer-task route resolution and profile route scope.
agent/delegation_provider.pyContract between delegation backends and core execution.
agent/delegation_backends.pyBackend selection and session refresh behavior.
tools/async_delegation.pyBackground dispatch, durable completion, and recovery.
tools/delegate_tool_progress.pyShared child progress and failure presentation contract.
apps/…/subagents.tsDesktop child identity, status, and progress state.
apps/…/delegate.tsxDesktop chat presentation for delegated children.
apps/…/delegation.tsDesktop interface for backend and route settings.
gateway/session_worker_delegation.pyGateway-owned persistence and delivery authorization.