Quick Start

Installation

Hive requires Python 3.10+. Get started by installing the core framework and its interactive dashboard dependencies:

pip install hive-framework textual

1. Configure Your Environment

Hive uses LiteLLM to support multiple providers (OpenAI, Anthropic, Google Gemini, etc.). Set your preferred API key as an environment variable:

export OPENAI_API_KEY="your_api_key_here"
# OR
export ANTHROPIC_API_KEY="your_api_key_here"

2. Create Your First Agent

Hive agents are defined by a Goal and an Execution Graph. Instead of hardcoding logic, you define nodes (like LLM steps or tool calls) and let the framework handle the state and self-improvement loops.

Create a file named my_agent.py:

import asyncio
from pathlib import Path
from framework.runtime.agent_runtime import create_agent_runtime
from framework.llm import LiteLLMProvider
from framework.runner.graph import Graph, Node

async def main():
    # 1. Define a simple graph
    graph = Graph(id="hello_hive")
    graph.add_node(Node(id="intake", type="llm_generate"))
    graph.set_entry("intake")

    # 2. Setup the LLM and Runtime
    llm = LiteLLMProvider(model="gpt-4")
    storage_path = Path("./storage")
    storage_path.mkdir(exist_ok=True)

    runtime = create_agent_runtime(
        graph=graph,
        goal="Research the latest trends in autonomous AI agents.",
        storage_path=storage_path,
        llm=llm
    )

    # 3. Execute the agent
    await runtime.start()
    result = await runtime.run(context={"topic": "AI Agents"})
    
    print(f"Execution Summary: {result.status}")
    print(f"Output: {result.output}")
    
    await runtime.stop()

if __name__ == "__main__":
    asyncio.run(main())

3. Launch the Interactive Dashboard (TUI)

Hive provides a powerful Terminal User Interface (TUI) for real-time monitoring of agent graphs, logs, and human-in-the-loop interactions.

If you are using one of the provided templates (like Deep Research Agent), you can launch the dashboard directly:

python -m examples.templates.deep_research_agent tui

Key TUI Features:

• Graph View: Watch the active node pulse as the agent traverses the execution graph.
• Log Pane: Granular Level 1-3 logs (Summary, Node Details, and raw Tool/LLM calls).
• Chat REPL: Directly converse with the coding agent to modify the graph or provide feedback.

4. Using MCP Tools

Hive is MCP (Model Context Protocol) native. To give your agent file system access or other capabilities, point it to an MCP config:

# Load MCP tools into the registry
agent._tool_registry.load_mcp_config("mcp_servers.json")

# Tools are now available for LLM nodes to use automatically
tools = list(agent._tool_registry.get_tools().values())

5. Human-in-the-Loop (HITL)

When an agent hits a high-uncertainty node or requires a credential, it can pause and wait for approval. You can review and approve generated tests or actions via the CLI:

# Internally, Hive uses the ApprovalAction workflow
from framework.testing.approval_types import ApprovalAction

# Users can [a]pprove, [r]eject, [e]dit, or [s]kip actions in real-time.

Next Steps

• Explore Templates: Check the examples/ directory for deep research and coding agent patterns.
• Advanced Graphs: Learn how to use EventLoopNode for self-correcting agentic loops.
• Credential Management: Use the built-in CredentialStore to securely manage OAuth2 and API tokens.