Agent Architecture

Hive utilizes a dynamic node-graph architecture to manage agent logic. Unlike traditional frameworks that rely on rigid, hardcoded chains, Hive represents agents as directed graphs where nodes represent discrete execution steps and edges represent conditional transitions.

The Node-Graph System

At the core of every Hive agent is a Graph. This graph structure allows for complex branching, looping, and error-recovery behaviors that are difficult to express in linear workflows.

Node Types

Hive supports several specialized node types, each designed for a specific stage of the agentic lifecycle:

• EventLoopNode: The primary node for autonomous reasoning. It allows the agent to iterate on a task, using tools and LLM reasoning until a specific verdict (e.g., ACCEPT, ESCALATE) is reached.
• LLMNode: A standard node for text generation or simple tool calls.
• RouterNode: Logic-heavy nodes that determine the next path in the graph based on the output of previous steps.
• FunctionNode: Executes arbitrary Python code, useful for data transformation or integrating with external systems.
• Human-In-The-Loop (HITL) Nodes: Specialized nodes that pause execution and wait for external approval or input before proceeding.

Edges and Transitions

Edges define the flow of execution. They are often conditional, triggering based on the result of the source node (e.g., on_success, on_failure, or custom status values).

# Example of a simplified graph structure
graph = Graph(
    id="research_agent",
    entry_node="intake",
    nodes=[
        Node(id="intake", type="function"),
        Node(id="research", type="event_loop"),
        Node(id="review", type="llm_tool_use")
    ],
    edges=[
        Edge(source="intake", target="research", condition="always"),
        Edge(source="research", target="review", condition="on_success"),
        Edge(source="review", target="research", condition="retry_requested")
    ]
)

Agent Runtime

The AgentRuntime is the engine that executes the graph. It manages the state, handles tool execution, and coordinates between the LLM providers and the local environment.

Key Responsibilities:

1. Context Management: Maintains the context dictionary passed between nodes.
2. Tool Execution: Interface with the ToolRegistry to execute local functions or MCP (Model Context Protocol) tools.
3. Persistence: Saves the state of the graph to disk, allowing agents to be paused and resumed across different sessions.
4. Observability: Dispatches events to the EventBus for real-time monitoring via the TUI or CLI.

Execution Lifecycle

A Hive agent follows a distinct lifecycle designed for reliability and self-improvement:

1. Initialization: The AgentRuntime loads the graph, tools, and credentials.
2. Entry Point: Execution begins at a defined EntryPointSpec.
3. Node Execution:
   • The Runtime identifies the active node.
   • The node's logic is executed (LLM call, tool use, or code).
   • Results are stored in the execution context.
4. Edge Evaluation: The runtime evaluates edge conditions to determine the next node.
5. Pause/Resume (HITL): If a node requires human intervention, the runtime persists the state and enters a paused status.
6. Self-Correction: If a failure is detected, the framework can capture the failure data and engage a "coding agent" to evolve the graph or the underlying connection code before redeploying.

Multi-Level Logging and Observability

The architecture includes a three-level logging system to provide deep visibility into agent behavior:

| Level | Name | Scope | Key Data | | :--- | :--- | :--- | :--- | | Level 1 | Summary | Full Graph Run | Status (Success/Fail), total tokens, duration. | | Level 2 | Details | Per Node | Success/Error flags, attempt counts, node latency. | | Level 3 | Tool Logs | Per Step | Specific tool inputs/outputs, LLM raw text, trace IDs. |

This data is OTel-aligned (OpenTelemetry), allowing you to correlate individual tool calls with high-level graph outcomes.

Credential Management

Hive agents interact with sensitive environments using a built-in CredentialStore. Instead of hardcoding keys, the architecture uses CredentialObject types (supporting API Keys, OAuth2, and Basic Auth) that the AgentRuntime injects into tools at runtime. This ensures that agents remain portable and secure across different execution environments.