Conversation Loop

Relevant source files

• agent/agent_init.py
• agent/agent_runtime_helpers.py
• agent/chat_completion_helpers.py
• agent/context_compressor.py
• agent/context_engine.py
• agent/conversation_compression.py
• agent/conversation_loop.py
• agent/error_classifier.py
• agent/tool_executor.py
• agent/turn_context.py
• agent/turn_finalizer.py
• contributors/emails/ben@whetstone.com.au
• contributors/emails/chaosxinglong@gmail.com
• contributors/emails/lanyusea@gmail.com
• contributors/emails/miniadmin@skshim-mini.local
• tests/agent/test_cjk_token_estimation.py
• tests/agent/test_compression_anti_thrash_persistence.py
• tests/agent/test_compression_concurrent_fork.py
• tests/agent/test_compressor_tool_call_budget.py
• tests/agent/test_context_compressor.py
• tests/agent/test_context_compressor_summary_continuity.py
• tests/agent/test_context_compressor_temporal_anchoring.py
• tests/agent/test_context_engine_on_turn_complete_usage.py
• tests/agent/test_context_engine_select_context.py
• tests/agent/test_credential_pool_routing.py
• tests/agent/test_error_classifier.py
• tests/agent/test_idle_compaction_lock_and_guards.py
• tests/agent/test_resume_stale_active_task.py
• tests/agent/test_summary_prefix_semantics.py
• tests/agent/test_summary_prefix_tool_use.py
• tests/agent/test_turn_context.py
• tests/agent/test_turn_finalizer_cleanup_guard.py
• tests/agent/test_turn_finalizer_final_response_persistence.py
• tests/agent/test_turn_finalizer_iteration_limit_exit.py
• tests/cli/test_cli_interrupt_ack_race.py
• tests/cli/test_cli_shutdown_memory_messages.py
• tests/run_agent/repro_48013_image_shrink_brick.py
• tests/run_agent/test_18028_content_policy_blocked.py
• tests/run_agent/test_413_compression.py
• tests/run_agent/test_70773_shared_client_fd_corruption.py
• tests/run_agent/test_compression_feasibility.py
• tests/run_agent/test_compression_persistence.py
• tests/run_agent/test_credential_pool_interrupt.py
• tests/run_agent/test_identity_flush.py
• tests/run_agent/test_image_shrink_recovery.py
• tests/run_agent/test_per_model_compression_threshold.py
• tests/run_agent/test_per_model_threshold_init_ordering.py
• tests/run_agent/test_primary_runtime_restore.py
• tests/run_agent/test_run_agent.py
• tests/run_agent/test_switch_model_pool_reload_52727.py
• tests/run_agent/test_verification_continuation_budget.py
• tests/test_hermes_state_compression_locks.py
• tests/tools/test_daemon_pool.py
• tools/daemon_pool.py
• website/docs/developer-guide/context-engine-plugin.md

This page describes the internal mechanics of the AIAgent conversation loop, detailing how the agent orchestrates iterative interactions, including system prompt construction, message assembly, integration of tool calls, iteration budget management, context compression, and interrupt handling.

---

Overview

All user interactions with Hermes Agent are funneled into the pivotal method:

The core logic of this method is implemented in agent/conversation_loop.py agent/conversation_loop.py1-6 It manages an iterative loop that continues until the model returns a final answer, the iteration budget is exhausted, or an interrupt is received agent/conversation_loop.py4-6 The function run_conversation is the primary driver for one user turn, handling model calls, tool dispatch, retries, and post-turn hooks agent/conversation_loop.py3-6

Conversation Loop — Code Entity Map

Sources: agent/conversation_loop.py1-15 agent/chat_completion_helpers.py1-14 agent/agent_runtime_helpers.py1-18 agent/iteration_budget.py33-35

---

Iteration Budget and Interrupts

The loop is regulated by a turn-based budget and an interrupt mechanism for safety and control.

Iteration Budget

The IterationBudget class agent/iteration_budget.py33 manages the maximum allowed tool-calling steps:

• Initialization: Default budget is typically 90 iterations, shared across subagents agent/iteration_budget.py33-40
• Consumption: consume() is called after tool execution to decrement the remaining count agent/iteration_budget.py84
• Sharing: When subagents are spawned, the budget is shared to prevent infinite recursion agent/iteration_budget.py33-40

Interrupt Handling

Hermes Agent uses a non-blocking interrupt system to stop long-running API calls or tool executions:

• API Level: _interruptible_streaming_api_call (and its non-streaming variant) monitors an interrupt flag agent/conversation_loop.py90-93
• Interruption Signals: The INTERRUPT_WAITING_FOR_MODEL_PREFIX is used to signal cancellations while waiting on a provider agent/conversation_loop.py93
• Tool Level: Tools can be cancelled via the _cancelled_tool_result helper, which returns a structured error to the model agent/tool_executor.py202-205

Sources: agent/iteration_budget.py33-84 agent/conversation_loop.py90-93 agent/tool_executor.py202-205

---

Context and History Management

Before each LLM call, the agent must determine if the conversation history fits within the model's context window.

Context Compression

The compression logic is triggered based on context usage:

• Thresholds: Compression is triggered when the estimated request tokens approach the model's limit agent/conversation_loop.py31-39
• Summarization: compress_context manages the reduction of history while protecting essential context agent/conversation_compression.py15-18
• Image Shrinking: try_shrink_image_parts_in_messages is used as a recovery helper to reduce payload size agent/conversation_compression.py20-23

Message Sanitization

The loop performs several cleanup steps on messages:

• Repair: _repair_tool_call_arguments fixes malformed JSON in model responses agent/message_sanitization.py39-40
• Alternation: repair_message_sequence enforces the role alternation required by many providers agent/agent_runtime_helpers.py11
• Sanitization: _sanitize_surrogates and _sanitize_messages_non_ascii remove characters that cause API failures agent/message_sanitization.py51-59

Sources: agent/conversation_loop.py31-39 agent/conversation_compression.py15-23 agent/agent_runtime_helpers.py11 agent/message_sanitization.py39-59

---

Tool Execution and Error Recovery

The agent handles tool calls through a dispatch system that includes error classification and smart failover.

Execution Flow

1. Detection: The loop identifies tool_calls in the assistant response.
2. Execution: _execute_tool_calls_sequential or _execute_tool_calls_concurrent dispatches calls agent/tool_executor.py3-5 Concurrent execution is limited to _MAX_TOOL_WORKERS (default 8) agent/tool_executor.py95
3. Classification: If an API error occurs, classify_api_error determines the FailoverReason (e.g., rate_limit, billing, context_overflow) agent/error_classifier.py33-51

Mapping to Code Entities

Sources: agent/tool_executor.py1-12 agent/error_classifier.py33-51 agent/conversation_loop.py1-15

Error Recovery Strategies

Reason	Recovery Action
context_overflow	Triggers context compression or image stripping agent/conversation_loop.py31-49
rate_limit	Triggers adaptive_rate_limit_backoff or jittered_backoff agent/conversation_loop.py75-81
billing	Triggers recover_with_credential_pool to rotate keys agent/agent_runtime_helpers.py13
image_too_large	_image_error_max_dimension extracts provider ceilings for reactive resizing agent/conversation_loop.py162-180

Sources: agent/conversation_loop.py31-180 agent/agent_runtime_helpers.py13 agent/error_classifier.py33-51

---

Finalization and Trajectory

Once the model provides a final answer (indicated by finish_reason: stop), the agent wraps up the turn:

• Reasoning: extract_reasoning pulls native thinking blocks or XML scratchpads from the response agent/agent_runtime_helpers.py17
• Trajectory: convert_to_trajectory_format normalizes messages for persistent storage, including converting tool results to text-only summaries agent/agent_runtime_helpers.py76-91
• Incremental Persistence: Tool messages are flushed to the session database incrementally via _flush_session_db_after_tool_progress to ensure transcript survival agent/tool_executor.py138-155

Sources: agent/agent_runtime_helpers.py17-91 agent/tool_executor.py138-155 agent/conversation_loop.py30