Agent Loop and Turn Phases
Relevant source files
The following files were used as context for generating this wiki page:
The Agent Loop is the primary execution cycle of the Hermes Agent. It governs how the system receives user input, processes it through a Large Language Model (LLM), interacts with tools, and manages persistent state across a conversation. The loop ensures that every turn remains grounded in project context and memory while allowing for autonomous tool execution.
The Conversation Loop
The agent/conversation_loop.py module manages the high-level orchestration of the agent's life cycle. A session typically begins with the initialization of the AIAgent class, which loads environment variables, configuration files, and identity settings from SOUL.md.
Loop Lifecycle
- Input Acquisition: The loop waits for user input from the interface (CLI, TUI, or Gateway).
- Context Assembly: The
prompt_builder.pycomponent gathers instructions fromAGENTS.md, memory, and active skills to create the system prompt. - Turn Execution: The loop calls the LLM and processes responses, including tool calls.
- State Persistence: The loop saves the session transcript to
~/.hermes/state.dbafter each exchange.
Sources: run_agent.py, agent/conversation_loop.py, website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/context-files.md
The flowchart depicts the iterative nature of the agent loop, where a single user request may trigger multiple internal tool-execution turns.
Turn Phases
Each interaction within the loop consists of distinct phases. The agent/turn_api_call.py module handles the communication with the model provider and ensures the response adheres to the expected tool-calling format.
Phase 1: Context and Hint Discovery
Before the LLM call, the SubdirectoryHintTracker monitors file paths in tool parameters. If the agent navigates into a new directory, the system injects directory-specific AGENTS.md instructions into the context.
Sources: website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/context-files.md
Phase 2: LLM API Call
The agent sends the assembled prompt to the LLM. The system supports swapping providers (e.g., Anthropic, OpenAI) mid-session via the /model command.
Sources: agent/turn_api_call.py, agent/AGENTS.md
Phase 3: Tool Execution and Delegation
If the LLM returns a tool call, the agent executes the corresponding function. For complex tasks, the agent uses delegate_task to spawn subagents, which operate in their own bounded loops to prevent context pollution in the main session.
Sources: optional-skills/software-development/subagent-driven-development/SKILL.md
Phase 4: Learning and Skill Synthesis
If a turn involves a /learn command, the agent inventories sources (URLs, local files, or recent history) and authors a reusable skill using the learn_prompt.py logic. This skill is then persisted for future sessions.
Sources: agent/learn_prompt.py
| Phase | Component | Action |
|---|---|---|
| Discovery | SubdirectoryHintTracker | Injects localized context files |
| API Call | run_turn_api_call | Sends request to LLM provider |
| Execution | terminal, file, etc. | Interacts with the local system |
| Delegation | delegate_task | Orchestrates subagents for subtasks |
| Persistence | state.db | Logs conversation and state changes |
Context Management in the Loop
The loop maintains efficiency by managing the token budget. Long conversations trigger the /compress command, which summarizes the history to stay within the model's context window.
The sequence diagram shows how the Conversation Loop orchestrates context assembly and multi-turn tool interactions before returning the final output to the user.
Sources: agent/conversation_loop.py, agent/turn_api_call.py, website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/context-files.md
Summary
The Agent Loop and its turn phases provide a structured environment for autonomous operations. By separating context assembly, API interaction, and tool execution into distinct phases, the Hermes Agent maintains high reliability and project awareness. Mechanisms like subagent delegation and progressive context discovery allow the loop to scale to complex software development tasks while managing resource constraints.