The Event Loop Node

The Event Loop Node is the core execution engine of the Hive framework. While standard nodes represent single actions or decisions, the Event Loop Node enables autonomous, iterative reasoning. It allows an agent to interact with tools, evaluate outcomes, and refine its approach until a goal is achieved or an escalation is required.

Overview

The Event Loop Node manages a "Think-Act-Observe" cycle. In each iteration, the node:

1. Analyzes the current state and history.
2. Executes one or more tool calls (via MCP or local functions).
3. Evaluates the results against the objective.
4. Issues a Verdict to determine the next phase of execution.

This node is particularly suited for "Deep Research" agents or any workflow where the number of steps cannot be predicted upfront.

The Verdict System

At the end of every iteration (or "step"), the Event Loop Node generates a verdict. This verdict dictates the flow of the agent within the node and its transition to the rest of the graph.

| Verdict | Description | | :--- | :--- | | CONTINUE | The task is progressing. The node will trigger another iteration to perform further actions. | | ACCEPT | The objective is met. The node terminates with a success status and passes data to the next node in the graph. | | RETRY | The previous step produced an error or unsatisfactory result. The node attempts the logic again, often with adjusted parameters. | | ESCALATE | The node cannot proceed (e.g., missing credentials, ambiguous instructions). This typically triggers a Human-in-the-Loop (HITL) workflow. |

Node Configuration

When defining an Event Loop Node in your agent graph, you configure the LLM provider, available tools, and the "Stop" criteria.

from framework.runtime.agent_runtime import create_agent_runtime

# Event Loop Nodes are typically defined within the graph structure
entry_points=[
    EntryPointSpec(
        id="research_loop",
        name="Deep Research",
        entry_node="researcher_node", # An EventLoopNode type
        trigger_type="manual"
    )
]

Exit Statuses

The lifecycle of an Event Loop Node ends with one of the following statuses, which can be monitored via the TUI Dashboard or Runtime Logs:

• success: Objective achieved.
• failure: Maximum retries reached or terminal error encountered.
• stalled: No progress detected over multiple iterations.
• escalated: Paused for human intervention.
• guard_failure: A security or safety guardrail blocked execution.

Observability and Logging

Because Event Loop Nodes are non-deterministic, Hive provides granular three-level logging specifically designed for iterative execution.

Step-Level Logs (Level 3)

Each iteration within the loop is recorded as a NodeStepLog. This includes:

• Tool Calls: Every individual tool use, including inputs and results.
• Token Usage: Input/Output counts per step to monitor costs.
• Latency: Time taken for that specific iteration.
• Verdict Feedback: The internal reasoning used by the LLM to justify its next move.

Node-Level Summary (Level 2)

Upon exiting the loop, the NodeDetail object captures the aggregate performance:

• accept_count: Total successful steps.
• retry_count: How many times the node had to pivot.
• needs_attention: A boolean flag triggered if the node exhibits "stalled" behavior or high latency, surfacing it in the Monitoring UI.

Integration with MCP

The Event Loop Node is the primary consumer of Model Context Protocol (MCP) tools. When the node decides to "Act," it dispatches requests to registered MCP servers (e.g., filesystem tools, web search, or database connectors).

# Example: A file-view tool being used within an Event Loop
# The node iterates: view_file -> analyze content -> patch_file
result = await view_file(
    path="src/main.py",
    workspace_id="ws_123",
    agent_id="researcher_01",
    session_id="session_xyz"
)

Best Practices

1. Define Clear Guardrails: Use verdict_feedback to debug why an agent might be stuck in a CONTINUE loop.
2. Monitor Escalations: Use the ESCALATE verdict to prevent agents from wasting tokens on tasks they aren't authorized to complete.
3. Set Step Limits: While Hive allows for autonomous loops, configure maximum step counts in your runtime settings to prevent "hallucination loops" in complex reasoning tasks.