agent-heaven 0.9.1.dev0

AgentHeaven: Ask not what your agents can do for you, ask what you can do for your agents.

AgentHeaven

Ask not what your agents can do for you, ask what you can do for your agents.

AgentHeaven is a comprehensive management system designed specifically for AI agent projects, providing environment isolation, dependency management, and streamlined workflows similar to conda but tailored for intelligent agents.

📖 English Documentation 📖 中文文档 💻 Documentation GitHub

🚧 AgentHeaven is in active experimental development. Features may change. NOT ready for stable deployment.

Installation

AgentHeaven supports multiple package managers for flexible installation. Choose the one that best fits your workflow:

Optional Dependencies:

• exp: experimental features and integrations, including database integration, vector engines, etc. Recommended.
• gui: GUI tools for agent management and monitoring.
• dev: development tools including docs generation, code formatting, testing, etc.

Quick Install

Minimal installation (core only, no optional dependencies):

# pip
pip install agent-heaven

# uv
uv pip install agent-heaven

# poetry
poetry add agent-heaven

# conda
conda install -c conda-forge agent-heaven

Full installation (with all optional dependencies):

# pip
pip install "agent-heaven[exp,gui,dev]"

# uv
uv pip install "agent-heaven[exp,gui,dev]"

# poetry
poetry add agent-heaven --extras "exp gui dev"

# conda
conda install -c conda-forge agent-heaven[exp,gui,dev]

Install From Source

Minimal installation (core only, no optional dependencies):

git clone https://github.com/RubikSQL/AgentHeaven.git
cd AgentHeaven

# pip
pip install -e "."

# uv
uv pip install -e "."

# poetry
poetry install

# conda
conda env create -f environment.yml
conda activate ahvn

Full installation (with all optional dependencies):

git clone https://github.com/RubikSQL/AgentHeaven.git
cd AgentHeaven

# pip
pip install -e ".[dev,exp,gui]"

# uv
uv pip install -e ".[dev,exp,gui]"

# poetry
poetry install --extras "dev exp gui"

# conda
conda env create -f environment-full.yml -n ahvn
conda activate ahvn

Quick Start

Prerequisites

Apart from Python requirements, we recommend installing Git to support version control features.

Initial Setup

Initialize the AgentHeaven environment globally. Use -r to force reinitialization:

ahvn setup --reset

Configuration

Set up your LLM providers:

OpenAI (Optional):

ahvn config set --global llm.providers.openai.api_key <YOUR_OPENAI_API_KEY>

Ollama Models (Optional):

# Requires Ollama to be installed
ollama pull gpt-oss:20b       # General local model (relatively large)
ollama pull qwen3:8b          # General local model (relatively small)
ollama pull embeddinggemma    # For text embedding
ollama pull qwen3-coder:30b   # For code generation

Documentation

📖 Complete Documentation

Quick Links

• 🚀 Introduction
• 📋 Getting Started
• 💻 CLI Guide
• 🐍 Python API
• 🎯 Example Applications
• 📚 API Reference

Building Documentation Locally

You can directly access the compiled docs at docs/en/build/html/index.html.

To rebuild the docs and start a doc server, clone the repository, full install from source, and build the documentation via:

bash scripts/docs.bash en zh -s

To start a doc server without rebuilding, run:

bash scripts/docs.bash en zh -s --no-build

• English documentation: http://localhost:8000/
• Chinese documentation: http://localhost:8001/

Contributing

We welcome contributions! Please see our Contributing Guide for details on how to get started.

Citation

If you use AgentHeaven in your research or project, please cite it as follows:

@software{agent-heaven,
  author = {RubikSQL},
  title = {AgentHeaven},
  year = {2025},
  url = {https://github.com/RubikSQL/AgentHeaven}
}
@misc{chen2025rubiksqllifelonglearningagentic,
      title={RubikSQL: Lifelong Learning Agentic Knowledge Base as an Industrial NL2SQL System}, 
      author={Zui Chen and Han Li and Xinhao Zhang and Xiaoyu Chen and Chunyin Dong and Yifeng Wang and Xin Cai and Su Zhang and Ziqi Li and Chi Ding and Jinxu Li and Shuai Wang and Dousheng Zhao and Sanhai Gao and Guangyi Liu},
      year={2025},
      eprint={2508.17590},
      archivePrefix={arXiv},
      primaryClass={cs.DB},
      url={https://arxiv.org/abs/2508.17590}, 
}

License

This project is licensed under the Sustainable Use License. See the LICENSE file for details.