AI-powered agent generation with intelligent CSV knowledge bases
Quick Start • Features • Examples • 🗺️ Roadmap • Contributing
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.
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.yamlHow it works:
- Meta-agent analyzes natural language requirements
- Selects optimal model from 7+ providers (OpenAI, Anthropic, Google, etc.)
- Recommends tools from Agno's builtin catalog
- Generates context-aware system instructions
- Creates production-ready YAML configuration
Not keyword matching - real LLM intelligence.
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 processingPerformance 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.
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: trueWant 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
)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
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
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']}")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/docsWhen 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)
- 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)
- OpenAI (
# 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# 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# 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)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, otherResult: Automatic routing, no manual orchestration code needed.
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.
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.
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
$ 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 workflowFull OpenAPI docs at /docs.
# 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
# Component Creation - AI-Powered ⭐
hive ai <agent-name> --interactive # Interactive AI generation
hive ai <agent-name> --description "..." # Generate from description
# Development
hive dev # Start dev server (hot reload)
hive dev --port 8000 # Custom port
hive dev --examples # Run with built-in examples
# Production
hive serve # Start production server
hive serve --port 8000 # Custom portHive supports multiple database backends for different use cases:
| Backend | Best For | Setup | Performance | Features |
|---|---|---|---|---|
| PostgreSQL | Production | Docker | ⭐⭐⭐⭐⭐ | Full text search, PgVector, HNSW |
| SQLite | Development | None | ⭐⭐⭐ | File-based, good for testing |
# Start PostgreSQL with Docker
docker run -d \
--name hive-postgres \
-e POSTGRES_PASSWORD=your_password \
-e POSTGRES_DB=hive \
-p 5432:5432 \
pgvector/pgvector:latest
# Update .env
HIVE_DATABASE_URL=postgresql://postgres:your_password@localhost:5432/hiveFeatures:
- PgVector for hybrid search
- HNSW indexing (fast vector similarity)
- Full-text search
- Auto-schema migration
- Production-ready
# Update .env
HIVE_DATABASE_URL=sqlite:///./data/hive.dbLimitations:
- No concurrent writes
- No vector similarity search
- File locking issues under load
- Not recommended for production
Minimal .env (20 vars, not 145!):
# Core (Required)
HIVE_ENVIRONMENT=development # development|staging|production
HIVE_API_PORT=8886 # API server port
HIVE_DATABASE_URL=postgresql://... # Database connection
HIVE_API_KEY=hive_your_32_char_key # API authentication
# AI Providers (At least one required)
OPENAI_API_KEY=sk-... # OpenAI models
ANTHROPIC_API_KEY=sk-ant-... # Claude models
GEMINI_API_KEY=... # Google models
# Optional
HIVE_LOG_LEVEL=INFO # DEBUG|INFO|WARNING|ERROR
HIVE_VERBOSE_LOGS=false # Detailed logging
HIVE_ENABLE_METRICS=true # Performance tracking
HIVE_CORS_ORIGINS=http://localhost:3000 # Comma-separated origins# Clone repository
git clone https://github.com/namastexlabs/automagik-hive
cd automagik-hive
# Install dependencies
uv sync
# Run tests
uv run pytest # All tests
uv run pytest tests/hive/knowledge/ # Knowledge tests
uv run pytest -v --cov=hive # With coverage
# Lint & format
uv run ruff check --fix
uv run ruff format
# Type check
uv run mypy hive/
# Start examples
uv run python hive/examples/agents/demo_all_agents.py| Feature | Pure Agno | Hive + Agno |
|---|---|---|
| Agent Creation | Write Python factories | YAML or AI generation |
| Getting Started | Read docs, write boilerplate | hive init → instant project |
| Knowledge Base | Setup PgVector, write loaders | create_knowledge_base() with hot reload |
| Model Selection | Research 7+ providers | AI recommends optimal choice |
| Tool Selection | Browse Agno tools | Catalog + AI recommendations |
| CSV RAG | Write custom incremental loader | Built-in hash-based incremental |
| Project Structure | DIY | Opinionated ai/ structure |
Hive = Scaffolding for Agno
Like Create React App for React, Hive removes setup friction without replacing the framework.
❌ Compete with Agno - We extend it, don't replace it ❌ Reinvent orchestration - Use Agno's native teams/workflows ❌ Lock you in - Generated code is pure Agno, you own it ❌ Replace your code - We scaffold, you customize
- AI-powered agent generation with meta-agent
- Smart CSV RAG with hash-based incremental loading
- YAML-first configuration
- Project scaffolding with examples
- Builtin tools catalog
- Hot reload for dev server
- Interactive TUI for agent creation
- Live agent testing in terminal
- Knowledge base quality scoring
- Tool compatibility checker
- Agent performance profiling
- Multi-environment configs (dev/staging/prod)
- Cost tracking and optimization
- Deployment helpers (Docker, AWS, Fly.io)
- Agent monitoring dashboard
- Workflow visualization
- ✅ Cryptographic API key generation (
secrets.token_urlsafe) - ✅ Constant-time validation (prevents timing attacks)
- ✅ Environment-based security (auto-enabled in production)
- ✅ Input validation (size limits, sanitization)
- ✅ PostgreSQL with PgVector (hybrid search)
- ✅ SQLite for development
- ✅ Auto-schema migration
- ✅ Session persistence
- ✅ Structured logging (Loguru)
- ✅ Automatic emoji mapping
- ✅ Performance metrics
- ✅ Error tracking
- ✅ Docker-ready
- ✅ Environment scaling (dev/staging/prod)
- ✅ Health checks
- ✅ Graceful shutdown
We welcome contributions! See CONTRIBUTING.md for guidelines.
Areas for contribution:
- Additional builtin tool integrations
- Example agents for common use cases
- Documentation improvements
- Bug fixes and performance optimizations
Powered by:
- Agno - The AI agent framework powering everything
- UV - Modern Python packaging and project management
- Typer - Beautiful CLI framework
- Rich - Terminal output that doesn't suck
- Pydantic - Data validation with type hints
- FastAPI - Modern web framework (via Agno)
MIT License - see LICENSE for details.
- Documentation: docs/
- Examples: hive/examples/
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Agno Framework: github.com/agno-agi/agno
Built with ❤️ by practitioners who got tired of boilerplate.
Remember: Hive doesn't compete with Agno. We make it easier to use. 🚀