Skip to main content
Create a heaven for your agents to live, grow, and thrive.
AgentHeaven is a composable Python framework that brings together LLM inference, tool orchestration, knowledge management, and agent construction into one place. Rather than being yet another agent framework, it focuses on preparing everything an agent needs before it acts — creating a context-rich, well-organized environment where agents can work effectively.

​
1. The Problem

Building AI agent applications today means stitching together many separate concerns:
  • LLM access — connecting to different providers, managing presets, handling sessions
  • Tool orchestration — defining, converting, and exposing tools across protocols (MCP, function calling, etc.)
  • Knowledge management — storing, indexing, and retrieving domain knowledge from various backends
  • Prompt engineering — defining, versioning, and localizing prompts as persistent runtime assets
  • Agent construction — combining all of the above into coherent, maintainable workflows
Most frameworks address one or two of these. AgentHeaven addresses all of them in a unified, composable design.

​
2. What AgentHeaven Provides

LayerWhat it doesKey modules
LLMsUnified inference across providers with configurable presetsahvn.utils.llm via LiteLLM
PromptsFunction-based prompt specs with database persistence and built-in translation dictionariesahvn.utils.prompt via PromptSpec, PromptManager, and TranslationDict
ToolsConvert between functions, MCP tools, JSON schemas, and codeahvn.tool via FastMCP 3.x
KnowledgeUnified Knowledge Format (UKF) with pluggable storage and retrievalahvn.ukf, ahvn.klstore, ahvn.klengine, ahvn.klbase
CacheMonitor and record function calls for data collection and learningahvn.cache
CLICommand-line interface for setup, configuration, and managementahvn.cli (ahvn command)

​
3. Key Design Principles

  • Composable, not monolithic — each module works independently and can be mixed and matched
  • Provider-agnostic — swap LLM providers, databases, or vector stores without changing application code
  • Knowledge-first — treat domain knowledge as a first-class asset via the Unified Knowledge Format (UKF)
  • Agent-friendly — design APIs and data structures that work well for both humans and AI agents
  • Configuration-driven — versioned, scoped config resolved through runtime context keeps code stateless and portable
For the design principles in depth, see Philosophy.

​
4. Who is AgentHeaven for?

  • Developers building AI-powered applications that need structured knowledge management
  • Researchers experimenting with agent architectures, tool use, and retrieval strategies
  • Teams that need a shared, configurable foundation for multiple agent projects

​
Further Exploration

Getting started:
Architecture and design: