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 / agent-turn-execution

Agent turn execution

An agent turn is one complete response cycle for a user request. It admits the work for a session, prepares a model-ready request, manages model and tool rounds, then stores and delivers one final result. This page extends the agent runtime overview and connects to model provider integration, context memory and compression, and agent tools and guardrails.

Turn lifecycle

The turn lifecycle moves one request from an admitted session to a durable response. The same transcript supports model calls, tool results, recovery, and later turns.

flowchart TD
    A[User request] --> B[Turn admission]
    B --> C[Context and request assembly]
    C --> D[Preflight size gate]
    D --> E[Model call]
    E --> F{Response type}
    F -->|Retry or recovery| D
    F -->|Tool calls| G[Persist and run tools]
    G --> H{More model work?}
    H -->|Yes| C
    H -->|No| I[Finalize turn]
    F -->|Final text| I
    I --> J[Persist and deliver result]

Turn admission

The turn facade admits one active turn for a session before the conversation loop starts. A durable lease prevents concurrent workers from changing the same transcript, while activity and relay scopes let hosts track cancellation, liveness, and task outcome. The facade returns early when admission is interrupted or times out. References: agent/turn_facade.py• L22-57, agent/turn_facade.py• L79-121, agent/turn_facade.py• L188-216

Turn context

Turn context converts the incoming request and stored history into the working state for the loop. It restores or builds the session prompt, adds the current user turn, prepares memory and hook context, sets budgets, and persists enough state for recovery before the first provider call. References: agent/turn_context.py• L483-500, agent/turn_context.py• L1017-1020, agent/conversation_loop.py• L1553-1593

Request preparation

Each model attempt uses a request-local view of the transcript. This view can include current-turn context and provider-specific shaping without changing the durable conversation history except at defined turn or compression boundaries.

Request assembly

Request assembly combines the working transcript with the active system prompt, tools, memory or hook context, and any model-specific additions. It then normalizes the request and creates the provider-facing cache plan so the model sees a consistent message sequence. References: agent/turn_request_assembly.py• L106-127, agent/turn_request_assembly.py• L140-205, agent/turn_request_assembly.py• L232-284

Preflight gate

The preflight gate checks whether the assembled request can fit the active model context. When needed, it grows a managed local window or runs context compression, refunds work that never reached the provider, and stops safely when compression cannot make enough progress. References: agent/turn_preflight_gate.py• L20-101, agent/turn_preflight.py• L57-102, agent/turn_preflight.py• L145-225

Preflight can also run after tool results because tool output increases the next request. That check uses provider usage when available and otherwise uses a route-aware estimate. The context memory and compression page describes the compression system in more detail. References: agent/turn_preflight.py• L244-306, agent/turn_preflight.py• L347-428

Model interaction

After the request passes preflight, the loop makes a provider call and treats the response as a controlled state transition. A response can be usable text, tool work, an incomplete output, or a failure that requires recovery.

Model calls

The call phase selects streaming or non-streaming delivery, runs provider middleware, and marks the request as active for interrupt and redirect handling. A user correction that arrives during the call discards the stale response and rebuilds the request from the correction. References: agent/turn_api_call.py• L47-65, agent/turn_api_call.py• L68-157

Retry and recovery

The retry loop surrounds each provider attempt with rate-limit checks, request creation, the model call, and response validation. Error handling classifies the failure before it chooses a retry, credential recovery, context recovery, provider fallback, or terminal result. Restart signals cause the outer loop to rebuild the request instead of replaying stale request data. References: agent/conversation_loop.py• L1496-1525, agent/turn_api_error.py• L52-221, agent/turn_retry_state.py• L9-15

Retries are bounded by attempt and iteration budgets. The loop gives special handling to context overflow, incomplete output, malformed responses, content refusal, and user interrupts. It stops rather than sending a request that is known not to fit or cannot be made safe. References: agent/turn_api_error.py• L253-425, agent/turn_response_check.py• L131-218, agent/turn_iteration_prep.py• L437-566

Response routing

Response intake normalizes provider output into the agent’s assistant message shape and records provider hooks and usage. The loop then routes the message to either the tool-round path or the final-text path. Incomplete reasoning and provider-specific incomplete responses can request another call without becoming a false final answer. References: agent/turn_response_intake.py• L120-197, agent/conversation_loop.py• L1663-1677

Tool rounds

Tool rounds extend one user turn across several model calls. The model proposes calls, the agent validates and records them, tools produce results, and the next model request uses those results as new context.

Tool execution

The tool-round path validates the model’s calls and applies tool guardrails before execution. It persists the assistant tool-call message before running side effects, then records tool results and stops the turn if persistence or a guardrail halt prevents safe continuation. References: agent/turn_tool_round.py• L46-81, agent/turn_tool_round.py• L87-150, agent/turn_tool_round.py• L163-190

Tool policy and dispatch are shared with the wider tool system. See agent tools and guardrails for the capabilities and safety rules that apply inside this round. References: agent/turn_tool_round.py• L93-127, agent/turn_tool_round.py• L202-230

Tool continuation

After successful tool execution, the loop may compact the expanded transcript and then returns to request assembly. It keeps the current user-turn boundary aligned after compaction so new context and results remain attached to the correct turn. References: agent/turn_tool_round.py• L192-230, agent/turn_preflight.py• L244-360, agent/turn_context_compaction.py• L116-123

Turn completion

Completion turns the loop’s working state into a durable, host-readable result. It must preserve what the user saw, close the transcript with a valid assistant boundary, and report whether the turn completed, failed, or was interrupted.

Final response

The final-text path removes temporary retry scaffolding and applies stop gates before it accepts a response. It can ask the model to continue after an empty answer, a dropped tool call, a truncated answer, or an acknowledgement that did not complete the task. Once accepted, it transforms and flushes the response before leaving the loop. References: agent/turn_final_response.py• L56-68, agent/turn_final_response.py• L130-249, agent/turn_final_response.py• L320-376

Finalization

Finalization resolves budget fallbacks, recovers streamed text when needed, shapes the transcript tail, persists the session, and runs post-turn hooks. It assembles a result envelope with the final response, transcript, usage, model route, completion state, and failure information. Cleanup errors are reported without replacing a response that is already available. References: agent/turn_finalizer.py• L522-634, agent/turn_finalizer.py• L684-752

Result delivery

The public conversation entry point stamps the result with the current-turn boundary and closes failed turns that would otherwise leave a user-only durable tail. The facade then releases leases and scopes, while simple callers receive the result’s final_response string. References: agent/conversation_loop.py• L1694-1745, agent/conversation_loop.py• L1792-1835, agent/turn_facade.py• L218-220

Change checklist

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

  • Changes to request assembly must preserve the separation between the durable transcript and the provider-facing request copy. This affects prompt caching, replay, and context-size checks.
  • Changes to tool execution must keep the persist-before-side-effect order and the matching assistant tool-call and tool-result rows.
  • Changes to retry or fallback paths must preserve restart signals so the next request is rebuilt with the active provider, context, and user correction.
  • Changes to finalization must keep the result envelope, durable assistant boundary, and current-turn boundary aligned for every terminal path.
  • Changes to compression or transcript rewriting must re-anchor the current user turn before later context injection or delivery.

Important failure modes

TriggerConsequenceGuard
The request remains over the model window after compressionThe provider call is not sent, and the turn ends with context-recovery guidancePreflight fail-closed checks and bounded compression attempts
Tool-call persistence fails before executionSide effects are skipped, and the turn reports a persistence failurePersist the assistant tool-call block before dispatch
A user correction crosses an in-flight model callThe stale response is discarded and the turn is rebuilt from the correctionRedirect state and restart signals
The model returns a malformed or empty response repeatedlyRetries and fallbacks end in a failed result instead of an endless loopResponse-shape checks, retry limits, and fallback routing
The loop ends after a tool result with no final textThe transcript could leave the next request with an invalid or silent tailFinalization adds a visible completion boundary and explanation

Key files

FileWhy to read it
agent/turn_facade.pyShows turn admission, lease ownership, scopes, and the caller-facing boundary
agent/conversation_loop.pyShows the high-level phase order and the public result path
agent/turn_context.pyShows how one user request becomes turn state and how API messages are built
agent/turn_request_assembly.pyShows the request-local model payload and pressure measurement
agent/turn_preflight.pyShows context-size checks and compression before or after model work
agent/turn_api_call.py and agent/turn_api_error.pyShow provider calls, interrupts, retries, and fallback decisions
agent/turn_tool_round.pyShows validation, durable tool-call staging, execution, and continuation
agent/turn_final_response.pyShows acceptance and recovery of a final text response
agent/turn_finalizer.pyShows persistence, result assembly, delivery metadata, and post-turn cleanup