Jiuxia/ghrah

简体中文

This is an Alpha version framework that can be used for proof of concept, it is not production-ready and may have numerous breaking updates

A general-purpose distributed agent cluster framework

Can be used to build a secure, auditable runtime core for various workloads, ranging from single agents to agent cluster systems

Quick Start

Install Dependencies

uv sync

Configure Agentconf

Use the Agentconf TUI to configure your LLM provider, model, and Agent

uv run agentconf

Run Examples

uv run python examples/simple_chat.py

Or run other examples under the examples directory

Project Structure

src/ghrah/
├── core/           # Core abstractions: config, messages, events, exceptions, HITL, CommandSender
├── agents/         # Agent implementations: ActorAgent base class
├── chat/           # LLM interaction layer: ChatMessage, ContentBlock, ChatFormat
│   └── format/     # Format adapters: OpenAIFormat, AnthropicFormat
├── abilities/      # Ability system: Ability interface, hooks, executors, built-in abilities
│   └── builtin/    # Built-in abilities: conversation, file operations, task termination, cluster operations, etc.
├── context/        # Context management: ActionChain, StateManager, MessageStore, window policies
│   └── persistence/# Persistence backends: JSON, SQLite, in-memory, remote
├── llm/            # LLM integration: LLMFactory (agentconf → ChatFormat)
└── communication/  # Communication layer: Router, Registry, Supervisor

Documentation

For full usage documentation, see the docs/ directory:

Document	中文	English
Installation & Quick Start	getting-started.md	getting-started_en.md
Core Concepts	core-concepts.md	core-concepts_en.md
Ability System	ability-system.md	ability-system_en.md
Hook Mechanism	hook-mechanism.md	hook-mechanism_en.md
Context Management	context-management.md	context-management_en.md
Multi-Agent Communication	multi-agent.md	multi-agent_en.md
Persistence & Window Management	persistence.md	persistence_en.md
Built-in Ability Reference	builtin-abilities.md	builtin-abilities_en.md
Configuration Reference	configuration.md	configuration_en.md
Error Handling	error-handling.md	error-handling_en.md
Architecture & Flow Diagrams	architecture.md	architecture_en.md
Chat Interaction Layer	chat-module.md	chat-module_en.md
Dual-Mode Architecture	distributed-mode.md	distributed-mode_en.md
HITL Human-in-the-Loop	hitl.md	hitl_en.md

Development

# Install optional-dependencies
uv sync --extra dev

# Run tests
uv run pytest tests/ -v

# Lint
uv run ruff check src/ tests/

License

Apache 2.0