HouYi is a lightweight multi-agent framework built on Pydantic v2, combining declarative programming with neuro-symbolic verification for production reliability.
🪶 Lightweight Core Pydantic-based declarative definitions enable agents, tasks, and workflows to be defined as simple Python classes with automatic validation, serialization, and documentation generation—achieving "code as configuration."
⚡ Async Event-Driven Execution Built on asyncio with DAG-based task orchestration, supporting parallel execution, dynamic graph evolution, and non-blocking I/O for high-concurrency agent scenarios.
🔍 Zero-Config Observability Native OpenTelemetry integration auto-instruments every agent execution with distributed tracing across LLM calls, tool invocations, and state transitions—<3% performance overhead, no manual setup required.
🧠 Neuro-Symbolic Verification Integrates Z3 SMT solver for formal verification of LLM outputs against business constraints, separating probabilistic reasoning from deterministic execution to ensure reliability in production.
📊 Multi-Dimensional Evaluation 19 built-in evaluators (quality, safety, performance) combined with adversarial testing framework enable comprehensive agent validation and continuous improvement through automated feedback loops.
🔄 Persistent State & Long-Running Workflows Automatic execution snapshots support pause/resume, external event handling, and human-in-the-loop workflows—agents can wait for async callbacks and resume exactly where they left off.
🛡️ Secure Sandbox Execution Isolated execution environment with permission controls prevents LLM-generated code from accessing unauthorized resources, ensuring enterprise-grade security.
🎯 Advanced Context Engineering Dynamic context managers with RAG integration and reusable "Skills" as versioned capabilities—agents can share and evolve capabilities like software libraries.
💰 Cost-Aware Governance Token budget control with dynamic model routing enables automatic cost optimization while maintaining quality through intelligent provider fallback.
- Python 3.11+
- uv (recommended for development)
# From PyPI (coming soon)
pip install houyi# Clone the repository
git clone https://github.com/YiLabsAI/HouYiAgent.git
cd HouYiAgent
# Install uv (see https://docs.astral.sh/uv/)
# Use Python 3.11 by default
uv python install 3.11
# Create/sync the virtualenv in .venv and install dev dependencies
uv sync --extra devfrom houyi import Agent, tool
# 1. Define a skill
@tool
def search(query: str) -> list[str]:
"""Search the web for information."""
return [f"Result for {query}"]
# 2. Create an agent
agent = Agent(role="Researcher", skills=[search])
# 3. Run it
result = agent.run("What is HouYi?")
# Output: ✅ agent.run (13.16ms)See Getting Started Guide for complete tutorial.
Explore the examples/ directory:
python examples/quickstart.py # Basic agent
python examples/llm_example.py # LLM integration
python examples/team_example.py # Multi-agent team
python examples/evaluation_example.py # All 19 evaluatorsUser Guides:
- Getting Started - Installation, quick start, core concepts
- API Reference - Complete API documentation
- Advanced Features - Observability, multi-LLM, DAG execution
- Evaluation - All 19 evaluators explained
Development:
- Development Guide - Coding standards and best practices
- Release Notes - Version history and updates
We welcome contributions! Please see our Contributing Guide for details.
- Built on industry standards:
- OpenTelemetry (OTEL) for observability and distributed tracing
- AgentSkills.io for skill interoperability and sharing
- MCP (Model Context Protocol) for context management
- A2A (Agent-to-Agent) protocol for multi-agent communication