# HelloAgents

> A production-grade multi-agent framework built on OpenAI's native API, featuring 16 core capabilities including tool response protocol, context engineering, session persistence, and sub-agent mechanisms.

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.

## Features
- ReAct agent implementation
- Reflection agent implementation
- Plan-and-Solve agent implementation
- ToolResponse unified protocol
- HistoryManager for context engineering
- TokenCounter for token tracking
- ObservationTruncator for context window management
- SessionStore for session persistence
- TaskTool sub-agent mechanism
- ToolFilter for sub-agent tool scoping
- CircuitBreaker for fault tolerance
- Skills knowledge externalization
- TodoWrite task progress tracking
- DevLog decision logging
- SSE streaming output
- Async lifecycle management
- TraceLogger observability
- Four logging paradigms
- Optimistic locking for file editing
- OpenAI-compatible adapter
- Anthropic adapter
- Gemini adapter
- Automatic LLM provider detection
- ToolRegistry for tool management
- Function Calling architecture

## Integrations
OpenAI, DeepSeek, Qwen, Kimi, Zhipu GLM, Anthropic Claude, Google Gemini, vLLM, Ollama, SGLang, Datawhale Hello-Agents tutorial

## Platforms
API, CLI, DEVELOPER_SDK

## Pricing
Open Source

## Version
V1.0.0

## Links
- Website: https://github.com/jjyaoao/HelloAgents
- Documentation: https://github.com/jjyaoao/HelloAgents/tree/main/docs
- Repository: https://github.com/jjyaoao/HelloAgents
- EveryDev.ai: https://www.everydev.ai/tools/hello-agents