HelloAgents Multi-Agent Framework
A production-grade multi-agent framework built on OpenAI's native API, integrating 16 core capabilities for complete engineering support.
- Source repo
- jjyaoao/HelloAgents
- Stars
- ★ 3.3k
- Last updated
- 12d ago
- License
- NOASSERTION
- Primary language
- Python
- FA score
- 29/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformOpenAI API
- Cost
- Free software; you pay for model usage
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- Developers who want to quickly build multi-agent applications on OpenAI, using ReActAgent and built-in tools to automate complex tasks.
- Not a fit if
- Teams needing commercial use rights (CC BY-NC-SA 4.0 is non-commercial)
- Developers on Python versions below 3.10
- Source review
- 29/100 · Major gaps 8 safety controls not found
What does this agent do, and when should you use it?
HelloAgents is a production-grade multi-agent framework built on OpenAI's native API, integrating 16 core capabilities including ToolResponse protocol, context engineering (HistoryManager/TokenCounter), session persistence (SessionStore), sub-agent mechanism (TaskTool), optimistic locking, circuit breaker, Skills externalization, TodoWrite progress management, DevLog decision logging, streaming output (SSE), asynchronous lifecycle, observability (TraceLogger), logging systems, and LLM/Agent base class refactoring. The framework provides three LLM adapters (OpenAI-compatible, Anthropic, Gemini) with automatic provider detection, supporting various cloud and local inference services. It includes multiple Agent implementations (SimpleAgent, ReActAgent, ReflectionAgent, PlanAndSolveAgent) and a rich set of built-in tools, along with comprehensive documentation and examples.
HelloAgents delivers a full multi-agent development experience: developers can install via pip, create an LLM instance (HelloAgentsLLM with auto provider detection), register tools (like ReadTool, WriteTool, TodoWriteTool), and instantiate agents like ReActAgent to run tasks. The framework supports Function Calling architecture, manages context via HistoryManager and TokenCounter, handles tool responses through a unified ToolResponse format, implements session persistence with SessionStore, and enables sub-agents via TaskTool with tool filtering. It provides streaming output through SSE, asynchronous lifecycle, circuit breaker for fault tolerance, and optimistic locking for file editing concurrency control. Output is delivered through tool calls and streaming responses; the deployment boundary is a Python library requiring environment variables like LLM_API_KEY.
- Developers who want to quickly build multi-agent applications on OpenAI, using ReActAgent and built-in tools to automate complex tasks.
- Teams needing a unified tool response protocol and context management to maintain robust agent systems.
- Applications requiring session persistence, such as chatbots, using SessionStore to save conversation history.
- Complex tasks requiring a sub-agent mechanism, delegating subtasks via TaskTool to other LLM calls.
- Highly interactive scenarios needing streaming output and async handling, leveraging SSE and lifecycle management.
- Debugging scenarios requiring observability and logging, using TraceLogger to record detailed execution traces.
How do you install or deploy this agent?
Install via pip: pip install hello-agents. Requires Python 3.12 or 3.13 (3.13 recommended). Configure environment variables in a .env file: LLM_MODEL_ID=your-model-name, LLM_API_KEY=your-api-key-here, LLM_BASE_URL=your-api-base-url.
How do you use this agent?
- Install:
pip install hello-agents. 2. Configure.envas above. 3. Write code:from hello_agents import ReActAgent, HelloAgentsLLM, ToolRegistry;from hello_agents.tools.builtin import ReadTool, WriteTool, TodoWriteTool;llm = HelloAgentsLLM();registry = ToolRegistry();registry.register_tool(ReadTool())etc.;agent = ReActAgent("assistant", llm, tool_registry=registry);agent.run("analyze project structure and generate report").
What are this agent's strengths and limitations?
- Comprehensive engineering support covering 16 capabilities including tool response protocol, context engineering, session persistence.
- Support for multiple LLM providers (OpenAI-compatible, Anthropic, Gemini) with automatic detection.
- Multiple Agent implementations (ReActAgent, ReflectionAgent, PlanAndSolveAgent) catering to different scenarios.
- Rich built-in tools and detailed documentation to reduce onboarding friction.
- Non-commercial license (CC BY-NC-SA 4.0) restricts commercial use without authorization.
- Requires Python 3.10+ only, limiting language environments.
- Reliance on external LLM APIs requires API keys and network connectivity.
- The development version is under active iteration and may differ from the tutorial version.
How does this agent compare with similar options?
The framework is closely tied to the Datawhale Hello-Agents tutorial and serves as its extended implementation. Additionally, a community Go re-implementation, HelloAgents-go, is available for Go developers.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| HelloAgents Multi-Agent Framework This agent | 29 · Major gaps | Library / SDKFree + model costs | ★ 3.3k | 12d ago | Python | OpenAI API |
| rpi: Rust Coding-Agent Runtime | 64 · Some gaps | CLIFree + model costs | ★ 116 | today | Rust | OpenAI API · Claude API |
| SGR Agent Core | 56 · Major gaps | Self-hosted serviceFree + model costs | ★ 1.1k | 1mo ago | Python | OpenAI API |
| Lagent Lightweight Agent Framework | 43 · Major gaps | Library / SDKFree + model costs | ★ 2.3k | 6mo ago | Python | OpenAI API |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows: the repository provides no documentation on permission management, user confirmation, data flow transparency, sensitive data handling, dependency security audits, external effect controls, rollback mechanisms, or source attribution. All trust-related criteria are unmet, hence score 0.
Evidence shows: dependencies listed in README and pyproject.toml are consistent with requirements.txt, but no verification of dependency availability or detailed failure messages is provided. Test files exist but no execution results are given, so self-consistency, dependency availability, and failure messages each score 1.
Evidence shows: README clearly distinguishes learning and development versions and provides adapters for multiple LLM providers, but lacks detailed capability boundaries, trigger precision, or environment fit specifics. Thus audience and scenarios score 2, others score 1.
Evidence shows: README provides clear project structure, installation instructions, and examples, but lacks known limitations, version changelog, and explicit maintenance responsibility. License is CC BY-NC-SA 4.0, but no versioning policy is provided. Hence information architecture, install notes, examples, and license score 2, others score 1.
Evidence shows: README claims 16 core capabilities but provides no actual output examples or performance data, so output usability, marginal value, and cost-benefit each score 1.
Evidence shows: claims in README lack traceable test results or external validation, and no distinction between facts and inferences is made. Hence all criteria score 1.
- Not found in source: least-privilege scopingGrant only what the task needs: a dedicated account or read-only token, scoped to specific directories and repos.
- Not found in source: confirmation before actingTurn on (or add) a confirmation step before it acts, and try it in a sandbox or test environment before real data.
- Not found in source: data-flow disclosureWatch which external services it contacts (proxy or firewall logs) and keep sensitive data out until you know where it goes.
- Not found in source: sensitive-data handlingUse dedicated, low-privilege, revocable API keys — never production credentials — and keep secrets out of logs.
- Not found in source: dependency securityPin versions and run a dependency audit (npm audit, pip-audit) before installing; prefer running it in a container.
- Not found in source: disclosed external effectsEstablish which external systems it writes to, sends to or changes, and verify with test accounts or repos before production.
- Not found in source: rollback or recovery pathBack up first, or work on a git branch or snapshot, so its changes can be undone.
- Not found in source: verifiable attributionInstall from the official repo or registry and check the publisher and URL to avoid look-alike packages.
- The repository provides no security or permission control documentation; assess risks before use.
- Test files require real LLM configuration; no mock or offline tests are provided, so functionality cannot be verified.
- The license is CC BY-NC-SA 4.0, with non-commercial restrictions that may affect commercial deployment.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
HelloAgents V1.0.1：组件化运行时、知识检索与持久记忆 HelloAgents V1.0.1 围绕智能体应用的构建与扩展，完善了从 Agent Loop、工具执行、上下文管理，到知识检索、用户画像和后台任务的开发流程。 从一个简单的 SimpleAgent 开始，可以逐步加入所需能力；检索、记忆和上下文组件也支持独立使用，方便接入已有应用。 📦 版本：V1.0.1 🐍 Python：支持 3.12 / 3.13，推荐 3.13 🚀 安装：python -m pip install --upgrade "hello-agents==1.0.1" 📚 文档：[使用指南](https://github.com/jjyaoao/HelloAgents/tree/main/docs) 🧩 案例：[按功能浏览示例](https://github.com/jjyaoao/HelloAgents/tree/main/examples) --- ✨ 核心亮点 - 组件化设计：通过 AgentComponents 组合或替换历史管理、Token 计数、工具输出处理、会话存储和 Skills 加载器。 …View on GitHub ↗ -
Release notes excerpt
HelloAgents V1.0.0 Release Notes 📅 发布日期: 2026-02-21 📦 安装: pip install hello-agents>=1.0.0 🔗 GitHub: https://github.com/jjyaoao/HelloAgents 📚 文档: https://github.com/jjyaoao/HelloAgents/tree/main/docs --- 🎯 概述 HelloAgents V1.0.0 是一个里程碑版本，标志着框架从教学原型升级为生产级多智能体框架。本版本集成了 16 项核心能力，涵盖工具响应协议、上下文工程、可观测性、会话持久化、子代理机制、异步生命周期、流式输出等完整的工程化支持，为构建复杂智能体应用提供坚实基础。(感谢项目YYHDBL/MyCodeAgent给予的部分实现灵感支持~) ✨ 核心亮点 - 🏗️ 生产级架构: Function Calling 统一架构，解析成功率 99%+ - 🔧 16 项核心能力: 从工具协议到异步生命周期的完整工程化支持 - 🚀 性能优化: Token 成本降低 85%，上下文压缩智能化 …View on GitHub ↗ -
Release notes excerpt
🎓 HelloAgents V0.2.9 - 学习版定稿公告 📅 发布日期: 2026-02-13 📦 版本: v0.2.9 (Learning Edition - Stable) 🔗 GitHub: https://github.com/jjyaoao/HelloAgents 📚 教程: https://github.com/datawhalechina/Hello-Agents --- 🎯 核心公告 HelloAgents V0.2.9 正式定稿为「学习版」，从此版本开始： - ✅ 接口冻结：核心 API 保持稳定，不再引入破坏性变更 - ✅ 教程基准：所有教程、文档、示例代码均基于此版本 - ✅ 长期维护：仅接受 bug 修复和安全更新，不添加新特性 - ✅ 初学者友好：推荐所有初学者和教程读者使用此版本 --- 📖 为什么需要学习版？ 在过去的开发中，我们收到了很多反馈： > "教程里的代码跑不通了，API 变了..." > "刚学会一个功能，更新后又不一样了..." > "能不能有个稳定版本，让我安心学完整个教程？" 我们听到了你们的声音！ V0.2.9 学习版的目标是： …View on GitHub ↗
FAQ
What license is required for commercial use?
How do I integrate different LLM providers?
What is the difference between the learning and development versions?
Can I use local model deployments?
How is HelloAgents related to the Datawhale Hello-Agents tutorial?
learn_version branch to follow the tutorial chapters; the main branch and the hello-agents PyPI package track the current framework.