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-runtime

Agent runtime

The agent runtime turns one user request into a result by joining a turn loop, a selected model route, managed conversation context, and guarded tool use. The runtime keeps one internal message flow while it adapts requests for different providers and preserves enough state for the next turn.

Runtime flow

The runtime begins at run_agent.py and uses AIAgent as its public boundary. Construction prepares the route, client, tools, session state, memory, and context engine. Each request then enters agent/conversation_loop.py and continues until the model returns an answer or the runtime reaches a safe stop.

The main stages are:

  1. Accept the user request and load or create the conversation state.
  2. Build the effective system prompt and request context.
  3. Resolve the provider wire format and send the request.
  4. Inspect the model result.
  5. Run requested tools and add their results to the conversation.
  6. Repeat the model and tool exchange until the model returns a final answer.
  7. Save the turn result and expose status, usage, and failure information to the caller.

The following diagram shows how a request moves through the runtime and where the child systems take control.

flowchart TD
    A[User request] --> B[AIAgent]
    B --> C[Turn setup]
    C --> D[Prompt and context assembly]
    D --> E[Provider request]
    E --> F{Model result}
    F -->|Tool calls| G[Tool safeguards and execution]
    G --> H[Tool results in conversation]
    H --> D
    F -->|Final text| I[Turn finalization]
    I --> J[AI-assisted result]

The simple chat() interface returns the final text. The full conversation interface returns the final text with messages and turn metadata so CLI, gateway, TUI, and other callers can render progress or resume the session. The runtime also supports interruption, retry, provider fallback, and bounded iteration so a stalled or failing model does not leave an unfinished request in an invalid state.

References: run_agent.py• L214-285 agent/conversation_loop.py• L1543-1691

Turn orchestration

Turn orchestration is the control layer that decides what must happen before and after each provider call. It keeps the durable conversation in a common message shape, checks the iteration budget, handles retries and overflow, and chooses between another tool round and finalization.

The runtime treats a model answer with tool calls as an intermediate result. It records those calls and their results in order, then sends the expanded conversation back to the model. A text answer ends the loop and passes through finalization, which makes the result available to the caller and the session store.

The internal message contract is based on system, user, assistant, and tool roles. It keeps assistant tool requests paired with tool results and prevents invalid role sequences from reaching a provider. This common contract lets the same orchestration work across different provider protocols.

References: agent/conversation_loop.py• L1635-1691 agent/turn_request_assembly.py• L106-130 agent/agent_init.py• L1-7

Provider access

Provider access converts the runtime's model choice into a usable endpoint, credential set, and API mode. The shared resolver serves chat, gateway, cron, ACP, and auxiliary model work so each entry point follows the same route rules.

Resolution prefers an explicit request and saved model configuration before environment-based and provider-default choices. The result identifies the provider, model route, base URL, credentials, and wire protocol. The runtime can therefore use OpenAI-compatible chat completions, the OpenAI Responses path, native Anthropic messages, Bedrock Converse, or a Codex app-server route without changing the turn contract.

When the selected route fails in a recoverable way, the runtime can move through the configured fallback chain. The replacement route is resolved with its own credentials and API mode, then the same conversation continues through the normal loop. Auxiliary work such as context summaries and vision calls may use separate routes rather than consuming the main conversational route.

References: hermes_cli/runtime_provider.py• L84-160 hermes_cli/runtime_provider.py• L994-1033 agent/agent_init.py• L25-45

Context management

Context management keeps the request within the active model's input limit while preserving the information needed for the task. A context engine tracks provider usage, decides when compaction is needed, and can provide context-specific tools.

The default engine reduces long conversations by protecting the start and recent tail, pruning old tool output, and replacing the middle with a summary. It can use an auxiliary model for that summary and falls back to a bounded deterministic summary when the summary route cannot complete. The gateway also has a higher-threshold session safety pass for sessions that grow between turns.

Context changes are request-aware. The runtime may select or compact context for a provider request, but the durable transcript remains the source of truth. Model switches and provider fallbacks refresh context limits and related usage state so an old route cannot silently control a new route's compaction policy. See Context, memory, and compression for the detailed context lifecycle.

References: agent/context_engine.py• L48-107 agent/context_engine.py• L121-154 agent/context_compressor.py• L5630-5736 agent/conversation_loop.py• L1571-1591

Tool use

Tool use gives the model controlled access to actions such as file work, terminal work, search, memory, and delegation. The runtime exposes only the tool schemas that match the active toolsets and current availability, then dispatches each accepted call through a guarded execution path.

Some tools need live agent state and are handled inside the agent boundary. Other tools use the shared registry, which supplies their handler and returns a bounded result or structured error. Independent calls may run in parallel, while interactive or dependent calls run in order. Results return to the conversation in the same order as the model's calls.

Before an action can change the workspace or external systems, the runtime applies tool loop limits, result-size controls, interruption checks, and command approval rules. Dangerous terminal actions can wait for a user decision. Repeated calls without progress can produce guidance or stop the turn, with stronger limits for unattended surfaces. See Agent tools and guardrails for the safety boundary.

References: agent/tool_executor.py• L1563-1605 agent/tool_executor.py• L1659-1722 tools/registry.py• L96-141 agent/tool_guardrails.py• L20-38 tools/approval.py• L1-10

Session state

Session state connects separate turns into one usable agent experience. The runtime keeps the message history, model route, usage records, memory updates, tool progress, and turn boundary together so a caller can resume or inspect work after a turn ends.

The system prompt is assembled from identity, project context, skills, and memory at session setup. Memory providers and context engines receive explicit session lifecycle events. End-of-turn persistence records the accepted messages and usage, while real session boundaries release or reset context and memory state. This separation lets a gateway reuse an agent across turns without carrying temporary turn state into the next request.

References: agent/prompt_builder.py• L1-5 agent/context_engine.py• L181-203 run_agent.py• L322-384 agent/conversation_loop.py• L1558-1613

Child page map

The runtime overview connects to four focused pages. Each page explains one boundary without repeating the full runtime model.

PageScope
Agent turn executionThe request, model, tool, retry, and finalization cycle
Model-provider integrationProvider selection, credentials, API modes, and fallback routes
Context, memory, and compressionPrompt inputs, memory handoff, context limits, and compaction
Agent tools and guardrailsTool discovery, dispatch, approval, loop limits, and safe results

Change checklist

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

  • Keep the shared message contract aligned with every provider adapter and with session replay.
  • Keep provider route resolution and fallback route resolution aligned so the active API mode matches the credentials and endpoint.
  • Keep context-engine model switching tied to the active provider route so old token limits do not govern a new model.
  • Keep tool schema availability aligned with the dispatch path so the model cannot request a tool that the active session cannot execute.
  • Keep approval, interruption, and loop-stop results as valid tool results so the next model request remains structurally valid.

Important failure modes

TriggerConsequenceGuard
Provider route and API mode do not matchThe provider rejects the request or tool formatShared runtime resolution and mode detection
Context grows beyond the active model limitThe provider rejects the request or the model loses needed historyContext-engine thresholds and reactive overflow recovery
Summary model cannot compact the middle of a long sessionContext grows until the next compaction attemptFailure cooldown, fallback summary, and bounded compression attempts
Tool arguments are invalid or a handler failsThe model receives no usable action resultStructured tool-error results at the dispatch boundary
Dangerous or repeated tool calls continue without progressA workspace or external system can be changed in an unsafe loopApproval gates, loop guardrails, interruption, and iteration budgets

Key files

FileWhy to read it
run_agent.pyPublic AIAgent boundary and runtime construction inputs
agent/conversation_loop.pyMain request-to-result orchestration
agent/turn_request_assembly.pyRequest context and provider-facing message assembly
hermes_cli/runtime_provider.pyShared provider and API-mode resolution
agent/context_engine.pyContract for context tracking and compaction
agent/context_compressor.pyDefault long-session context strategy
agent/tool_executor.pyTool execution and result return path
tools/registry.pyTool discovery, availability, and dispatch registry
agent/tool_guardrails.pyRepeated-call and no-progress safety rules
tools/approval.pyHuman approval boundary for risky actions