jjyaoao/HelloAgents

HelloAgents – A Modular Multi‑Agent Framework

What it is – HelloAgents is a Python library that lets you build multi‑agent applications that talk to large language models (LLMs) via the function‑calling interface. It supplies ready‑made building blocks – a loop that sends a prompt, receives a tool call, runs the tool, feeds the result back – plus optional pieces for context handling, retrieval‑augmented generation (RAG), persistent memory, sub‑agents, skills, streaming output and observability.

Key components

• Core – SimpleAgent, ReActAgent, ReflectionAgent, PlanSolveAgent implement different reasoning patterns. HelloAgentsLLM abstracts OpenAI‑compatible, Anthropic and Gemini providers, auto‑detecting the correct adapter from the LLM_BASE_URL.
• Tool system – Register tools (e.g., a calculator) via ToolRegistry. Built‑in tools cover file editing, task delegation, dev‑log, RAG, memory, GraphRAG, permissions, circuit‑breaker, etc.
• Context engine – Manages conversation history, token budgeting, truncation and builds the final payload sent to the model.
• Retrieval & memory – Pluggable vector stores (Qdrant), BM25, hybrid ranking, reranking, and a persistent “profile” store for user‑specific facts.
• Runtime – Handles the async loop, streaming SSE output, budget sharing across models, session persistence and background jobs.

How to get started

1. Install with uv sync --locked or pip install -r requirements.txt (Python 3.12‑3.13).
2. Define a .env with your model ID, API key and base URL.
3. Register the tools you need, create a HelloAgentsLLM instance, then instantiate a SimpleAgent and call agent.run(prompt).

from hello_agents import SimpleAgent, HelloAgentsLLM, ToolRegistry
from hello_agents.tools import CalculatorTool

registry = ToolRegistry()
registry.register_tool(CalculatorTool())
with HelloAgentsLLM() as llm:
    agent = SimpleAgent("assistant", llm, tool_registry=registry)
    print(agent.run("计算两晚住宿每晚 320 元，加上 180 元交通费的总预算"))

Extensibility – You can add any of the optional components through AgentComponents (e.g., a RAG store, a memory store, a sub‑agent). The framework also supports:

• MCP bridge for external tool integration (stdio/HTTP).
• Circuit‑breaker and permission policies to sandbox tool execution.
• Observability via TraceLogger for tracing runs.

Documentation & examples – The repo ships a full hierarchy of docs (installation, reliability, tool‑response protocol, context engineering, RAG, GraphRAG, memory, sub‑agents, streaming, etc.) and a rich examples/ folder that demonstrates each feature, from a simple async agent demo to a complete travel‑assistant application.

Community & versions

• Two main branches: learn_version (aligned with the Datawhale tutorial) and the current v1.0.1 release.
• Community ports in Go and TypeScript are linked.
• Licensed under CC BY‑NC‑SA 4.0 (non‑commercial use; commercial licensing requires permission).

Who it’s for – Developers who want a plug‑and‑play, yet highly configurable, framework for building LLM‑driven agents with tool use, retrieval, and memory without wiring everything from scratch.