automagik-hive

Quick Start • Features • Examples • 🗺️ Roadmap • Contributing

---

What is Automagik Hive?

Hive doesn't compete with Agno - it makes it easier to use.

Think of Hive as "Create React App" for Agno agents. Instead of weeks setting up project structure, writing boilerplate, and researching optimal configurations, Hive gives you:

• 🤖 AI-Powered Generation - Describe what you want; Hive's meta-agent generates optimal configs
• 🔄 Smart CSV RAG - Hash-based incremental loading (450x faster, 99% cost savings)
• 🎯 YAML-First Config - No Python boilerplate, just declarative configs
• 📦 Project Scaffolding - Zero to agent in 30 seconds

Built by practitioners who got tired of manually setting up the same patterns. Powered entirely by Agno.

---

Key Features

🤖 AI That Generates AI

Use an Agno agent to generate Agno agent configurations. Natural language requirements → optimal YAML configs.

$ hive ai support-bot --interactive

🤖 AI-Powered Agent Generator
────────────────────────────────────────

💭 What should your agent do?
> Customer support bot with CSV knowledge base

🧠 Analyzing requirements...
✅ Generated successfully!

💡 AI Recommendations:
  • Model: gpt-4o-mini (cost-effective for support)
  • Tools: CSVTools, WebSearch
  • Complexity: 4/10
  • Estimated cost: $0.002/query

📋 Generated: ai/agents/support-bot/config.yaml

How it works:

1. Meta-agent analyzes natural language requirements
2. Selects optimal model from 7+ providers (OpenAI, Anthropic, Google, etc.)
3. Recommends tools from Agno's builtin catalog
4. Generates context-aware system instructions
5. Creates production-ready YAML configuration

Not keyword matching - real LLM intelligence.

🔄 Smart CSV RAG System

The one feature from V1 worth keeping - hash-based incremental CSV loading:

from hive.knowledge import create_knowledge_base

# Smart loading with hot reload
kb = create_knowledge_base(
    csv_path="data/faqs.csv",
    embedder="text-embedding-3-small",
    num_documents=5,
    hot_reload=True  # Watches for changes
)

# Only re-embeds changed rows
# MD5 hash tracking prevents redundant processing

Performance Numbers:

• ✅ 450x faster - Hot reload for unchanged CSVs
• ✅ 10x faster - Small updates (only changed rows)
• ✅ 99% cost savings - No redundant embeddings
• ✅ 18/18 tests passing - Production-ready

Real-world impact: $700+/year savings at scale.

🎯 YAML-First Agent Design

No Python boilerplate. Just declarative configurations:

agent:
  name: "Customer Support Bot"
  agent_id: "support-bot"
  version: "1.0.0"

model:
  provider: "openai"
  id: "gpt-4o-mini"
  temperature: 0.7

instructions: |
  You are a friendly customer support agent.
  Answer questions using the knowledge base.
  When unsure, escalate to human support.

tools:
  - name: CSVTools
    csv_path: "./data/faqs.csv"
  - name: WebSearch

storage:
  table_name: "support_bot_sessions"
  auto_upgrade_schema: true

Want to extend with Python? Just create agent.py:

from agno.agent import Agent
from hive.discovery import discover_config

def get_support_bot(**kwargs):
    config = discover_config()  # Loads config.yaml
    return Agent(
        name=config['agent']['name'],
        # ... custom logic here
        **kwargs
    )

📦 Project Scaffolding

Opinionated structure that scales:

my-project/
├── ai/                         # All AI components
│   ├── agents/                 # Agent definitions
│   │   ├── examples/           # Built-in examples (learning)
│   │   │   ├── support-bot/
│   │   │   ├── code-reviewer/
│   │   │   └── researcher/
│   │   └── [your-agents]/      # Your custom agents
│   ├── teams/                  # Multi-agent teams
│   ├── workflows/              # Step-based workflows
│   └── tools/                  # Custom tools
│
├── data/                       # Knowledge bases
│   ├── csv/                    # CSV files
│   └── documents/              # Document stores
│
├── .env                        # Environment config
├── hive.yaml                   # Project settings
└── pyproject.toml              # Dependencies

🚀 Built on Agno's Power

Hive is a thin layer over Agno. You get all of Agno's features:

• Performance: 3μs agent instantiation, 6.5KB memory per agent
• Native tools: 20+ production-ready tools (web search, code execution, file ops, etc.)
• Storage: PostgreSQL, SQLite with auto-schema migration
• Playground: Auto-generated API with OpenAPI docs
• Workflows: Sequential, parallel, conditional, looping
• Teams: Automatic routing, collaboration, coordination

🛠️ Builtin Tools Catalog

Easy access to Agno's tools with metadata and recommendations:

Category	Tools
Execution	PythonTools, ShellTools
Web	DuckDuckGoTools, TavilyTools, WebpageTools
Files	FileTools, CSVTools
Data	PandasTools, PostgresTools
APIs	SlackTools, EmailTools, GitHubTools

from hive.config.builtin_tools import BUILTIN_TOOLS

# Browse tools
for tool_name, info in BUILTIN_TOOLS.items():
    print(f"{tool_name}: {info['description']}")

🔥 Hot Reload

Change configs, see results instantly:

$ hive dev  # Starts dev server

# Edit ai/agents/my-bot/config.yaml
# Server automatically reloads
# Test at http://localhost:8886/docs

🏢 Enterprise-Ready

When you're ready for production:

• ✅ PostgreSQL with PgVector (hybrid search, HNSW indexing)
• ✅ Environment-based configuration (dev/staging/prod)
• ✅ API authentication with cryptographic keys
• ✅ Structured logging with Loguru
• ✅ Type safety with Pydantic validation
• ✅ Test coverage (87% pass rate, 147 tests)

---

Quick Start

Prerequisites

• Python 3.11+ (3.12 recommended)
• At least one AI provider API key:
  • OpenAI (OPENAI_API_KEY)
  • Anthropic (ANTHROPIC_API_KEY)
  • Google (GEMINI_API_KEY)

Installation

# Install via uvx (recommended - no pollution)
uvx automagik-hive --help

# Or install globally with uv
uv pip install automagik-hive

# Or install with pip
pip install automagik-hive

Create Your First Agent (30 seconds)

# 1. Initialize project
uvx automagik-hive init my-project
cd my-project

# 2. Create API keys file
cp .env.example .env
# Edit .env and add your API keys

# 3a. Template-based creation (fast)
hive create agent my-bot

# 3b. AI-powered creation (optimal)
hive ai my-bot --description "Customer support bot with FAQ knowledge"

# 4. Start development server
hive dev

# 5. Access API docs
open http://localhost:8886/docs

Your First Conversation

# Via CLI
curl -X POST http://localhost:8886/agents/my-bot/runs \
  -H "Content-Type: application/json" \
  -d '{"message": "How do I reset my password?"}'

# Via Python
from agno.agent import Agent

agent = Agent.load("ai/agents/my-bot")
response = agent.run("How do I reset my password?")
print(response.content)

---

Real-World Examples

Customer Support Router

Problem: Route support queries to specialized agents (billing, technical, general)

# ai/teams/support-router/config.yaml
team:
  name: "Support Router"
  team_id: "support-router"
  mode: "route"  # Agno handles routing automatically

members:
  - "billing-agent"
  - "technical-agent"
  - "general-agent"

instructions: |
  You are a support routing system.

  Route queries based on topic:
  - Billing: payments, invoices, refunds
  - Technical: bugs, errors, integrations
  - General: questions, information, other

Result: Automatic routing, no manual orchestration code needed.

Knowledge-Powered Agent

Problem: Answer customer questions from FAQ database

agent:
  name: "FAQ Bot"
  agent_id: "faq-bot"

model:
  provider: "openai"
  id: "gpt-4o-mini"

tools:
  - name: CSVTools
    csv_path: "./data/faqs.csv"

instructions: |
  Search the FAQ database for answers.
  Provide concise, helpful responses.
  If no match found, offer to escalate.

Setup CSV:

question,answer,category
How do I reset password?,Go to Settings > Security > Reset Password,account
What are your hours?,We're available 24/7 via chat and email,general
How do refunds work?,Refunds process in 5-7 business days,billing

Smart loading: Only re-embeds changed rows, saves 99% on embedding costs.

Code Review Workflow

Problem: Automated code review with security checks

# ai/workflows/code-review/config.yaml
workflow:
  name: "Security Code Review"
  workflow_id: "code-review"

steps:
  - name: "static_analysis"
    agent: "security-scanner"

  - name: "review"
    agent: "code-reviewer"
    tools:
      - PythonTools
      - FileTools

  - name: "report"
    function: "generate_report"

Result: Comprehensive reviews covering OWASP Top 10, best practices, and fix suggestions.

---

Architecture That Scales

Project Structure

my-project/
├── ai/                         # AI components (auto-discovered)
│   ├── agents/                 # Agents (YAML + optional Python)
│   ├── teams/                  # Multi-agent teams
│   ├── workflows/              # Step-based workflows
│   └── tools/                  # Custom tools
│
├── data/                       # Knowledge bases
│   ├── csv/                    # CSV files (with hot reload)
│   └── documents/              # Other documents
│
├── .env                        # Environment variables
├── hive.yaml                   # Project configuration
└── pyproject.toml              # Python dependencies

Auto-Generated API

$ hive dev

# Agno Playground generates:
GET  /                          # API info
GET  /health                    # Health check
GET  /agents                    # List agents
POST /agents/{id}/runs          # Run agent
GET  /agents/{id}/sessions      # Get sessions
POST /teams/{id}/runs           # Run team
POST /workflows/{id}/runs       # Run workflow

Full OpenAPI docs at /docs.

---

CLI Commands

# Project Management
hive init <project-name>                  # Initialize new project
hive version                              # Show version

# Component Creation - Templates
hive create agent <name>                  # Create agent from template
hive create team <name>                   # Create team
hive create workflow <name>               # Create workflow
hive create tool <name>                   # Create custom tool