Just assemble.
1. System Architecture
- Inputs — domain knowledge (documents, schemas, rules) and functions (existing systems, human workflows) enter the system
- Information extraction and cache — raw inputs are parsed and monitored; function calls are recorded by the Cache component
- UKF layer — all information is normalized into Unified Knowledge Format (UKF) instances (Knowledge, Document, Experience, etc.)
- KLStore — UKF instances are persisted to pluggable storage backends (in-memory, file system, databases, remote, cascading)
- KLEngine — retrieval and utilization engines query the stored knowledge (string matching, faceted search, vector search, etc.)
- Application layer — agents, workflows, imitators, and tools consume knowledge through the KLBase orchestration layer
- Interface — CLI and GUI provide user-facing access to the system
2. Core Components
2.1. LLMs
AgentHeaven uses LiteLLM to provide a unified interface for various LLM providers. LLMs are configured as presets (e.g.,sys, chat, embedder, coder) in the config system, making them an integral part of the framework rather than external services.
2.2. Prompts
Prompts use a function-based model centered onPromptSpec: a prompt is a callable, versioned unit that can be persisted in a database, retrieved through a prompt manager, and localized through small translation dictionaries stored in the same runtime ecosystem. This keeps prompt logic close to Python while still treating prompts as persistent knowledge assets.
Prompt execution, prompt persistence, and prompt translation are first-class runtime services. Template-style authoring is still possible where useful, but function-based prompt specs are the primary interface.
2.3. Cache
The Cache component monitors and records function calls and their results. It can be used for logging queries, LLM inputs/outputs, agent trajectories, or collecting data from a running system. Cached entries can be converted to UKF instances (e.g., ExperienceUKFT) for long-term storage.2.4. Unified Knowledge Format (UKF)
The UKF protocol separates the extraction, storage, management, retrieval, and utilization of knowledge. As a semantic layer, BaseUKF unifies all components required in agentic workflows as structured data. Users define domain-specific UKF variants to represent their knowledge types.2.5. KLStore, KLEngine, and KLBase
- KLStore — the storage layer for long-term management of UKF instances. Supports in-memory, file system, database, remote, cascading, and routing backends.
- KLEngine — the utilization layer. Retrieval engines can use string matching, faceted search, vector search, or graph walks. Other engines support fine-tuning and knowledge distillation.
- KLBase — the core orchestrator that integrates one or more KLStore and KLEngine instances, providing a unified interface for agentic workflows built on top.
2.6. ToolSpec
ToolSpec is a structured representation of tools (functions, APIs, etc.). Built around FastMCP 3.x, it supports conversion from and to: Python functions, code strings, MCP tools, FastMCP tools, function-call JSON schemas, and UKF instances.3. Integration Points
AgentHeaven connects to external systems through well-defined integration layers:| Integration | Provider | Purpose |
|---|---|---|
| LLM inference | LiteLLM | Unified access to OpenAI, Anthropic, Google, Ollama, and more |
| Databases | SQLAlchemy | Relational database storage for UKF data |
| Vector databases | LlamaIndex | Semantic search and vector storage |
| Tool protocols | FastMCP 3.x | Standardized tool definition and communication |
| Prompt runtime | ahvn.utils.prompt | Function-based prompt specs, prompt persistence, and translation lookup |