HelloAgents: a tutorial-derived Python agent framework with 16 engineering features

The two-branch split is the first thing to understand about HelloAgents

HelloAgents is not one artifact. The README states that the repository maintains two versions: a learn_version branch that corresponds exactly to the body of the Datawhale Hello-Agents tutorial, and the current development branch carrying V1.0.0. The README warns that on the development branch, some implementations may differ from the tutorial content, and tells readers who want to follow the tutorial to switch to learn_version. That warning is doing real work. A reader who installs the package and follows along in the tutorial can hit code that no longer matches the prose, and the failure will look like their own mistake rather than a version mismatch. The repository also points to a Releases page with versions from v0.1.1 to v0.2.9, each tied to a specific tutorial chapter, which means the intended reading path is: pick the release that matches your chapter, not the newest tag. There is also an AtomGit mirror for users whose network makes GitHub awkward, plus community reimplementations in Go and TypeScript maintained in separate repositories. Those reimplementations are outside this repository and are not covered by its licence file in any way the README describes.

What problem HelloAgents solves, and who it is written for

Most agent tutorials stop at a ReAct loop that calls a tool and prints a string. The engineering problems start after that: what shape does a tool return so the agent can tell success from failure, how do you stop a conversation from exceeding the context window, how do you resume a session after a restart, and how do you keep two writers from clobbering the same file. HelloAgents takes those questions as its subject. The README lists sixteen core capabilities, and the ones that map to the questions above are the ToolResponse protocol, HistoryManager and TokenCounter for context engineering, SessionStore for persistence, TaskTool for subagents, an optimistic lock on file editing, a CircuitBreaker, Skills for externalising knowledge, TodoWrite for progress, DevLog for decision records, SSE streaming, an async lifecycle and a TraceLogger. The audience is a developer who already understands what an LLM API call looks like and now wants the surrounding scaffolding. It is also, explicitly, an audience following a specific Chinese-language tutorial, since the learn_version branch is defined by its correspondence to that text. If you are not following the tutorial, you are using the development branch, and the README's own framing is that this branch is continuously iterating.

How the pieces fit: adapters, registry, protocol, context

The architecture visible in the project structure is layered. At the bottom, hello_agents/core/llm.py holds the LLM base class and configuration, and llm_adapters.py holds three adapters: OpenAI-compatible, Anthropic and Gemini. Selection is automatic rather than declared. The README states that the framework picks an adapter based on the base_url, with anthropic.com in the URL selecting the Anthropic adapter and googleapis.com or generativelanguage selecting Gemini, and everything else falling through to the OpenAI-compatible path. That last path is the widest one, covering hosted services (the README names OpenAI, DeepSeek, Qwen, Kimi and Zhipu GLM) and local inference servers such as vLLM, Ollama and SGLang pointed at a localhost port. Above the LLM sits the agent layer in hello_agents/agents/, with four implementations: SimpleAgent, ReActAgent, ReflectionAgent and PlanAndSolveAgent, all built on a Function Calling architecture described in the agent base class. Tools live in hello_agents/tools/, split into a registry, a response protocol, a circuit breaker and a filter used for the subagent mechanism, with builtins for file operations, task delegation, TodoWrite, DevLog and Skills. Context handling is its own package: history.py, token_counter.py, truncator.py and builder.py. Observability is a single TraceLogger, and the Skills system has a loader. The data flow implied by the README example is: you construct an LLM, register tools into a ToolRegistry, hand the registry to an agent, and call run with a natural-language task.

Getting it running: install, environment keys, and the registry call

Installation is a single command, pip install hello-agents, and the README states Python 3.10 or later. Configuration goes in a .env file with three keys: LLM_MODEL_ID, LLM_API_KEY and LLM_BASE_URL. The README's example constructs HelloAgentsLLM() with no arguments and prints llm.provider, noting that the framework detects the provider from the API key format and base URL and that in the example it resolves to modelscope. That auto-detection is convenient and also the first place to look when something misbehaves, because a base URL that happens to contain one of the matched substrings will route you to a different adapter than you intended. Tool wiring is explicit: from hello_agents import ReActAgent, HelloAgentsLLM, ToolRegistry, then from hello_agents.tools.builtin import ReadTool, WriteTool, TodoWriteTool. You instantiate the registry, call registry.register_tool() once per tool, then construct ReActAgent("assistant", llm, tool_registry=registry) and call agent.run() with a task string. The builtin import path is worth noting because the README also documents three ways to write custom tools (functional, standard class and what it calls expandable) in docs/custom_tools_guide.md. If you only need the tutorial's material, remember the branch caveat: the install command does not choose a branch for you.

Where HelloAgents is the wrong tool

The licence is the sharpest limitation. The README and the badge both identify CC BY-NC-SA 4.0, and the README spells out the terms: attribution, ShareAlike (derivative works must carry the same licence), and NonCommercial, with a note that commercial use requires contacting the maintainer for authorisation. A ShareAlike clause on a framework is a different proposition from a permissive software licence, because it can reach the code you write on top of it, and the README's own summary is not legal advice. Separately, the repository metadata reports the licence as NOASSERTION, which means automated licence scanners will not classify it cleanly; that mismatch between the badge and the machine-readable field is itself a thing to resolve before a compliance review. Beyond licensing, the project is a tutorial companion under active iteration, with the README stating plainly that the development branch may diverge from the tutorial. If you need a stable API surface with a deprecation policy, this is not that. And if your workload is a single prompt-and-response call, the sixteen capabilities are overhead: a ToolRegistry, a TokenCounter and a SessionStore buy you nothing when there is no tool to call and no session to resume.

A real alternative: LangGraph, and the difference in approach

LangGraph models an agent as an explicit graph of nodes and edges with a shared state object, and its persistence layer is built around checkpoints taken at graph boundaries. The difference from HelloAgents is where control flow lives. In LangGraph you declare the topology before running anything, and the framework's job is to execute that topology and checkpoint it. In HelloAgents the topology is the agent's own reasoning loop: ReActAgent, ReflectionAgent and PlanAndSolveAgent each encode a different control pattern, and the engineering features (ToolResponse, HistoryManager, TokenCounter, ObservationTruncator, SessionStore) sit underneath that loop rather than describing it. If you need branching, human-in-the-loop interrupts at named points, or a graph you can draw and review, the explicit topology is the better fit. If you are following the Datawhale tutorial and want the code that matches its chapters, HelloAgents is the one that lines up, and switching to a graph framework means abandoning that correspondence. There is also a smaller consideration: the README points to community Go and TypeScript reimplementations of HelloAgents, so a polyglot team has an escape hatch in the other direction, but those are separate projects with their own maintenance.

Maintenance cost and what the licence commits you to

The release history in the supplied material runs V0.2.8 in October 2025, V0.2.9 in February 2026 and V1.0.0 later that same month, with the last push to the default branch in September 2026. That cadence suggests active work rather than a frozen artifact, which cuts both ways: fixes arrive, and so do changes that can break code written against an earlier tag. The README's advice to pin to the release matching your tutorial chapter is effectively upgrade guidance, and it implies you should treat version selection as a deliberate step rather than tracking main. On licence, the ShareAlike term means a modified distribution has to carry CC BY-NC-SA 4.0, and the NonCommercial term means commercial deployment needs separate authorisation from the maintainer. The README says to contact the maintainer for that. Nothing here is legal advice, and the discrepancy between the README's stated licence and the NOASSERTION metadata is exactly the kind of thing a legal reviewer will want clarified in writing before anyone builds a product on it.

Editorial conclusion

Adopt HelloAgents if you are working through the Datawhale Hello-Agents tutorial and want the matching code, or if you need a small Python framework that already has a ToolResponse protocol, a TokenCounter and a SessionStore rather than wiring those yourself. Do not adopt it for a commercial product without first resolving the non-commercial clause of CC BY-NC-SA 4.0 with the maintainer, and do not expect it to be a drop-in replacement for a mature multi-provider orchestration library. Before committing, verify which branch you are actually installing (learn_version versus the development branch at V1.0.0), confirm that pip install hello-agents resolves to the code you expect, and read the docs/ files for the specific capability you depend on, because the README states that parts of the development branch may differ from the tutorial text.

Official sources

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