jjyaoao/HelloAgents

HelloAgents – Production‑grade multi‑agent framework (Python)

What it is – A Python library built on top of the OpenAI‑compatible API that gives you a ready‑made, extensible platform for building multi‑agent applications. It bundles a set of engineering‑level capabilities (tool‑response protocol, context management, session persistence, sub‑agent routing, optimistic file locking, circuit‑breaker, skill loading, progress tracking, logging, observability, streaming via SSE, async lifecycle, etc.) so you can focus on the agent logic rather than boilerplate.

Core concepts

Component	Role
HelloAgentsLLM	Wrapper around any OpenAI‑compatible, Anthropic, or Gemini provider. Detects the correct adapter from `LLM_BASE_URL` automatically.
Agent base class (`ReActAgent`, `SimpleAgent`, `ReflectionAgent`, `PlanAndSolveAgent`)	Implements the Function‑Calling / ReAct pattern, handling tool calls, tool responses, and iterative reasoning.
ToolRegistry & ToolResponse	Register built‑in or custom tools (file read/write, task delegation, todo tracking, dev‑log, skill extraction). The registry enforces the `ToolResponse` schema.
SessionStore	Persists conversation history to disk so agents can resume later.
HistoryManager / TokenCounter / ContextBuilder	Manages context windows, counts tokens, truncates when limits are hit.
CircuitBreaker	Prevents runaway tool calls by halting after a configurable failure threshold.
TraceLogger	Emits structured traces for observability (useful for debugging or monitoring).
Streaming (SSE)	Sends partial LLM outputs to the client in real time.

Quick start

pip install hello-agents

from hello_agents import ReActAgent, HelloAgentsLLM, ToolRegistry
from hello_agents.tools.builtin import ReadTool, WriteTool, TodoWriteTool

llm = HelloAgentsLLM()                     # auto‑detects provider from .env
registry = ToolRegistry()
registry.register_tool(ReadTool())
registry.register_tool(WriteTool())
registry.register_tool(TodoWriteTool())

agent = ReActAgent(name="assistant", llm=llm, tool_registry=registry)
agent.run("分析项目结构并生成报告")

Create a .env file with your credentials:

LLM_MODEL_ID=your-model-name
LLM_API_KEY=your-api-key
LLM_BASE_URL=api.your‑provider.com

The library will pick the correct adapter (OpenAI‑compatible, Anthropic, or Gemini) based on the URL.

Installation & Compatibility

Python ≥ 3.10
Distributed on PyPI as hello-agents
MIT‑style source code, but the project is released under CC BY‑NC‑SA 4.0 (non‑commercial, share‑alike). Commercial use requires contacting the maintainer.

Extending the framework

Add a custom tool – implement ToolResponse (function, class, or expandable style) and register it via ToolRegistry.register_tool().
Create a new agent – subclass hello_agents.core.agent.Agent and override the plan/act methods, or reuse one of the provided agents (SimpleAgent, ReActAgent, etc.).
Plug in a new LLM provider – add an adapter in core/llm_adapters.py that follows the existing OpenAI/Anthropic/Gemini interface.

Documentation & Resources

Docs folder – detailed guides for each of the 16 core capabilities (tool‑response protocol, context engineering, observability, circuit‑breaker, session persistence, sub‑agent mechanism, skills system, optimistic lock, todo progress, dev‑log, async lifecycle, streaming SSE, function‑calling architecture, logging system, custom tool development).
Examples – ready‑to‑run scripts under examples/ showing typical workflows.
Learn version – a stable branch (learn_version) that matches the Datawhale “Hello‑Agents” tutorial for step‑by‑step learning.
Community ports – Go (HelloAgents-go) and TypeScript (HelloAgents-ts) re‑implementations for non‑Python ecosystems.

License

The code is released under Creative Commons BY‑NC‑SA 4.0. You may use, modify, and share it non‑commercially as long as you credit the authors and keep the same license. Commercial usage requires a separate agreement with the maintainer.

Bottom line – HelloAgents supplies a production‑ready scaffolding for multi‑agent AI systems, handling the messy engineering parts (tool orchestration, context limits, persistence, observability) so developers can concentrate on the domain logic of their agents.