HelloAgents: a Python multi-agent framework built on the Datawhale hello-agents tutorial

What HelloAgents solves, and who it is written for

Most agent tutorials stop at a loop that calls a model and prints text. HelloAgents picks up where that loop becomes a program: what a tool returns, what happens to the conversation when it outgrows the context window, where session state lives between runs, and how a failing tool stops taking down the whole run. The README frames the repository as a production-grade multi-agent framework built on the OpenAI native API, and lists sixteen core capabilities grouped around tool response protocol, context engineering, session persistence and subagent mechanics.

The audience is narrow and clear. The README says the repository maintains two branches, and that the learn_version branch corresponds exactly to the Datawhale Hello-Agents tutorial text while the current development branch carries newer code that may differ from the tutorial. That split tells you who this is for: someone reading the tutorial, running the code alongside it, and then wanting to see a more complete implementation of the same ideas. If you have never written an agent loop, the branch note is the first thing to read, not the feature list.

How the framework is put together: adapters, tools and context

The package layout in the README separates concerns in a way that is easy to trace. hello_agents/core holds llm.py, llm_adapters.py, agent.py, session_store.py, lifecycle.py and streaming.py. hello_agents/agents holds the four agent types: SimpleAgent, ReActAgent, ReflectionAgent and PlanAndSolveAgent. Tools live under hello_agents/tools, with registry.py, response.py, circuit_breaker.py, tool_filter.py and a builtin directory containing file_tools.py, task_tool.py, todowrite_tool.py, devlog_tool.py and skill_tool.py. Context engineering sits in hello_agents/context with history.py, token_counter.py, truncator.py and builder.py.

The provider story is the part worth understanding before you write config. The README states the framework supports all major LLM services through three adapters, and that the adapter is chosen automatically from the base URL rather than set by hand. An OpenAI-compatible adapter is the default and covers cloud APIs such as OpenAI, DeepSeek, Qwen, Kimi and Zhipu GLM, plus local inference through vLLM, Ollama and SGLang. A second adapter handles Anthropic when the base URL contains anthropic.com. A third handles Gemini when the base URL contains googleapis.com or generativelanguage. The README also shows a provider attribute on the LLM object, with a comment that the framework auto-detects a provider. That detection is convenient and also a constraint: if your endpoint does not resemble one of those three shapes, the automatic choice is the part you will have to work around.

The tool layer is where the framework's own vocabulary appears. ToolResponse is described as a unified return format for tools. ToolFilter is tied to the subagent mechanism, so a subagent can be handed a narrower set of tools than its parent. file_tools.py is documented as carrying optimistic locking for concurrent edits, and circuit_breaker.py as the fault-tolerance mechanism. Read together, these are the pieces that distinguish a framework from a demo: a defined tool contract, a way to limit which tools an agent sees, and a way to stop calling a tool that keeps failing.

Installing HelloAgents and running a first agent

The README gives a single install command and states Python 3.10 or newer is required. The package name on PyPI is hello-agents, with a hyphen, while the import name is hello_agents with an underscore.

pip install hello-agents

Configuration goes in a .env file. The README and .env.example agree on four unified variables: the model name, the API key, the base URL, and an optional timeout that defaults to 60 seconds. The example file notes that copying it to .env and filling in your key is the intended flow.

LLM_MODEL_ID=your-model-name
LLM_API_KEY=your-api-key-here
LLM_BASE_URL=your-api-base-url

The first real use is a ReAct agent with three builtin tools. The README's example imports ReActAgent, HelloAgentsLLM and ToolRegistry, registers ReadTool, WriteTool and TodoWriteTool on the registry, constructs the agent with a name, an LLM and the registry, then calls run with a task string. What you should see is the agent working through that task using the registered tools; the README does not show the expected output text, so the shape of the console output is something you will observe rather than something the documentation promises.

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("分析项目结构并生成报告")

Optional extras are declared in pyproject.toml rather than installed by default: google-genai for the Gemini adapter and anthropic for the Anthropic adapter. If you point LLM_BASE_URL at either of those services, install the matching extra, because the base install does not pull them in.

The dual-branch contract is the sharpest limitation

The README is unusually direct about this: the repository maintains two versions, and the development branch is described as continuously iterating, with some implementations possibly differing from the tutorial content. The recommended branch for beginners is learn_version. That is a real cost. A reader following the tutorial and installing from the default branch can hit behaviour that the tutorial text does not describe, and the README does not document a rollback path or a compatibility table mapping tutorial chapters to commits beyond pointing at the Releases page, which it says covers v0.1.1 through v0.2.9 with each version corresponding to a specific tutorial chapter.

There is a second gap. The README lists sixteen capabilities and links to documentation files under docs/, including dedicated guides for the tool response protocol, context engineering, observability, circuit breaking, session persistence, subagents, skills, optimistic locking, TodoWrite, DevLog, async lifecycle, streaming SSE, the function calling architecture, the logging system and custom tools. Four of those guides are cited in the README but their file names are the only description given in the repository's own summary. If you need to know, for example, what the CircuitBreaker thresholds are or how SessionStore serialises state, the README does not answer it; the linked guide is where that would live, and you should read it before committing to the design.

The licence is the third constraint and the one with the widest consequences. The README states the project uses CC BY-NC-SA 4.0 and summarises the terms as attribution, share-alike and non-commercial, with commercial use requiring authorisation from the maintainer. The pyproject.toml declares license text CC-BY-NC-SA-4.0. This is a content licence applied to a software package, which is a deliberate choice by the maintainer but an unusual one for a library you might want to link into a product.

Alternatives and where HelloAgents does not fit

The closest alternative is not another framework but the source material itself. The Datawhale hello-agents tutorial is what this repository is based on, and the README credits it directly. The difference in approach is that the tutorial teaches concepts in sequence, while HelloAgents packages them: the tutorial explains why context management matters, and the repository ships HistoryManager, TokenCounter, ObservationTruncator and ContextBuilder as importable modules. If you want to understand the ideas, the tutorial is the shorter path. If you want to read working code for the same ideas, the repository is.

The README also names two community reimplementations, HelloAgents-go and HelloAgents-ts, for Go and TypeScript developers. Those are separate repositories, not part of this package, and the README describes them as community contributions. If your team is not on Python, that is the relevant comparison rather than a different Python framework.

Where HelloAgents is the wrong tool: any commercial product. The non-commercial term in CC BY-NC-SA 4.0 is not a soft preference, and the README states commercial use requires contacting the maintainer. Equally, if you need a documented API surface with versioned guarantees, the dual-branch arrangement and the fact that the README points to docs/ files without summarising their contents means you will be reading source and guides rather than a stable reference.

Maintenance, upgrade cost and what the licence means in practice

The repository is not archived, and the last push was on 2026-09-04, which is recent. The most recent release listed is V1.0.0 from 2026-02-21, preceded by V0.2.9 on 2026-02-13 and V0.2.8 on 2025-10-26. The gap between the V1.0.0 release and the last push suggests work has continued on the branch after the tagged release, which is consistent with the README's description of a continuously iterating development branch.

Upgrade cost is dominated by the branch question rather than by dependency churn. The dependency set in pyproject.toml is bounded with upper limits: openai below 2.0.0, requests below 3.0.0, pydantic below 3.0.0, numpy below 3.0.0, networkx below 4.0.0, plus tiktoken and pyyaml. Those caps reduce the chance of a breaking transitive upgrade, at the cost of holding you back when a major version lands. The optional extras, google-genai and anthropic, are only installed on request.

On the licence, the practical point is that CC BY-NC-SA 4.0 is a share-alike, non-commercial licence, and the README states modified works must use the same licence. The pyproject.toml records the same identifier. This is not legal advice; if your use is commercial or you plan to redistribute a modified version, the README's own instruction is to contact the maintainer for authorisation.

Editorial conclusion

Adopt HelloAgents if you are following the Datawhale hello-agents tutorial, or if you want a compact Python 3.10+ codebase that shows how ReAct, session persistence, subagents and circuit breaking fit together in one repository. Do not adopt it for commercial work: the LICENSE and README both state CC BY-NC-SA 4.0, and the README says commercial use requires contacting the maintainer for authorisation. Before you build anything on it, check which branch you are on, since the README states the development branch differs from the tutorial, and confirm that the OpenAI-compatible, Anthropic or Gemini adapter matches the base URL you intend to use.

Frequently asked questions

Official sources

1. Issues
2. jjyaoao/HelloAgents on GitHub
3. README
4. Releases