Agent Loop Lifecycle and Tool Dispatch

A Hermes turn is an orchestration cycle, not one model request. The agent prepares context, calls the selected provider, executes any requested tools, appends tool results, and continues until it can return a final response or reaches a controlled stop condition.

Official documentation: https://hermes-agent.nousresearch.com/docs/developer-guide/agent-loop

Turn lifecycle

The agent appends the user message, builds or reuses the system prompt, checks context pressure, converts messages for the resolved API mode, and makes an interruptible provider call. Tool calls are dispatched through registered handlers and returned to the conversation as tool messages. A text response is persisted with usage metadata and delivered to the entry point.

Hermes normalizes different provider protocols around a common internal message shape. Provider-specific conversion still matters: chat completions, Codex Responses, and native Anthropic messages package tools and reasoning differently even though they converge on the same agent loop.

Tool-dispatch checklist

• Verify the tool schema is visible to the active model.
• Verify the handler is registered and its requirements are available.
• Keep assistant tool calls paired with their tool results.
• Route dangerous operations through approval controls.
• Preserve the task or session identifier for stateful tools.
• Use callbacks for progress rather than inventing platform-specific loops.
• Test interruption while a provider call or tool is active.
• Confirm final persistence after the tool loop ends.

Pitfalls

• Calling a handler directly and bypassing approvals, hooks, or state.
• Breaking message-role alternation after a tool error.
• Assuming all tools can run concurrently; interactive tools may require serialization.
• Treating a fallback model switch as invisible to caching and output behavior.
• Returning a success message before the final state is persisted.

Verification steps

1. Run a harmless request that requires exactly one tool.
2. Confirm the model emits a valid tool call and the registry resolves it.
3. Confirm pre-call and post-call hooks execute in order.
4. Inspect the tool result added to the conversation.
5. Confirm the next model call produces the final answer.
6. Resume or search the session and verify the complete turn was stored.
7. Test cancellation on a disposable long-running request and confirm the session remains valid.