HelloAgents is a Python-based multi-agent framework with tool response protocol, context management, session persistence, sub-agent mechanism, and 16 core capabilities. It offers examples and a quickstart to build React/Plan & Solve style agents using built-in tools.
Collecting history — the radar snapshots this repo daily. The trend line appears after 3 days of data (1 so far).
What it is
HelloAgents is a production-grade multi-agent framework built in Python that provides tool response protocol, context engineering, session persistence, sub-agent mechanisms, optimistic locking, circuit breakers, skills externalization, todo/write progress management, DevLog decision recording, streaming outputs, asynchronous lifecycle, and observability/logging. It integrates LLM/Agent base classes and a built-in tool system with registry and common built-in tools.
How it works
The project includes core components for LLM configuration and adapters, an agent base class (Function Calling architecture), session storage, lifecycle management, and streaming. It features a ToolRegistry for managing tools and a set of built-in tools for file operations, note-taking, sub-agent wiring, and memory management. The code structure highlights modules for core (llm.py, llm_adapters.py, agent.py, session_store.py, lifecycle.py, streaming.py), tools (registry.py, response.py, circuit_breaker.py, tool_filter.py, builtin/), context (history.py, token_counter.py, truncator.py, builder.py), observability (trace_logger.py), and skills (loader.py).
Getting started
Basic installation:
pip install hello-agents
Basic usage example:
from hello_agents import ReActAgent, HelloAgentsLLM, ToolRegistry
from hello_agents.tools.builtin import ReadTool, WriteTool, TodoWriteTool
llm = HelloAgentsLLM()
registry = ToolRegistry()
registry.register_tool(ReadTool())
registry.register_tool(WriteTool())
registry.register_tool(TodoWriteTool())
agent = ReActAgent("assistant", llm, tool_registry=registry)
agent.run("分析项目结构并生成报告")
Environment configuration example:
LLM_MODEL_ID=your-model-name
LLM_API_KEY=your-api-key-here
LLM_BASE_URL=your-api-base-url
# 自动检测provider
llm = HelloAgentsLLM() # 框架自动检测为modelscope
print(f"检测到的provider: {llm.provider}")
Supported LLM providers include adapters for OpenAI-compatible services, Anthropic, and Google Gemini. The framework auto-selects the adapter based on base_url.
Getting started (continued)
Project structure highlights core components and built-in tools, including file tools, task tools, and skills systems, organized under hello_agents/ and its subpackages.
Recent releases
- V1.0.0 (2026-02-21): HelloAgents V1.0.0 Release Notes. Installation:
pip install hello-agents>=1.0.0. - V0.2.9 (2026-02-13): v0.2.9 Learning Edition - Stable. Version:
v0.2.9. - V0.2.8 (2025-10-26):
pip install hello-agents>=0.2.8. - V0.2.7 (2025-10-23): Updated dependencies and fixed numpy dependency issue in bfcl; added builder in chapter9; fix import error in chapter9.
- V0.2.6 (2025-10-19): NoteTool and TerminalTool added for structured notes and filesystem interactions.
Traction
Stars: 2615, Forks: 611, Open issues: 31
Behind the repo
N/A
Caveats
License: CC BY-NC-SA 4.0 per README; license text located in LICENSE. The repository mentions two branches (learn_version for learners and V1.0.0 development) and references to tutorials. Created 2025-09-11. Last push 2026-06-08.