HelloAgents

HelloAgents is a production-grade multi-agent framework built on OpenAI's native API by developer jjyaoao, hosted on GitHub with over 3,100 stars and 700 forks. It is designed to provide complete engineering support for building complex agent applications, covering 16 core capabilities from context management to observability. The project is licensed under CC BY-NC-SA 4.0, meaning it is free for non-commercial use with attribution required.

What It Is

HelloAgents is a Python-based agent framework that goes beyond simple LLM wrappers to deliver production-ready infrastructure for multi-agent systems. It implements patterns like ReAct, Reflection, and Plan-and-Solve agents, and provides built-in tooling for session persistence, circuit breaking, streaming output, and sub-agent orchestration. The framework is closely tied to the Datawhale "Hello-Agents" tutorial series, with a dedicated learn_version branch that mirrors the tutorial content exactly.

16 Core Capabilities

The README lists the following engineering capabilities bundled into the framework:

• ToolResponse Protocol — unified return format for all tool calls
• Context Engineering — HistoryManager, TokenCounter, and ObservationTruncator for managing LLM context windows
• Session Persistence — SessionStore for saving and restoring conversation state
• Sub-agent Mechanism — TaskTool and ToolFilter for delegating work to child agents
• Optimistic Locking — concurrent file editing with conflict detection
• Circuit Breaker — CircuitBreaker for fault tolerance in tool execution
• Skills System — externalized knowledge via SkillLoader
• TodoWrite — task progress tracking within agent runs
• DevLog — decision logging for auditability
• Streaming Output — SSE-based streaming responses
• Async Lifecycle — asynchronous agent execution model
• Observability — TraceLogger for end-to-end tracing
• Logging System — four distinct logging paradigms
• LLM/Agent Base Class Refactor — Function Calling architecture as the foundation

LLM Provider Support

HelloAgents supports three adapter types that cover all major LLM services, with automatic provider detection based on the configured base_url:

• OpenAI-compatible adapter (default) — works with OpenAI, DeepSeek, Qwen, Kimi, Zhipu GLM, vLLM, Ollama, SGLang, and any OpenAI-format endpoint
• Anthropic adapter — activates when base_url contains anthropic.com
• Gemini adapter — activates when base_url contains googleapis.com or generativelanguage

Installation is via pip install hello-agents, and configuration is done through a .env file with LLM_MODEL_ID, LLM_API_KEY, and LLM_BASE_URL.

Project Structure and Branches

The repository maintains two active branches: a stable learn_version branch aligned with the Datawhale tutorial, and the main branch (currently at V1.0.0) for ongoing development. Community-contributed ports exist for Go (HelloAgents-go) and TypeScript (HelloAgents-ts). An AtomGit mirror is also maintained for accessibility within mainland China networks.

Update: V1.0.0

The latest release is V1.0.0, published in February 2026. Historical releases from v0.1.1 through v0.2.9 are available on the Releases page, each corresponding to specific tutorial chapters. The project shows active development with the last push recorded in September 2026 and 39 open issues, indicating an engaged contributor community.