# Core Features of the Hello-Agents Project: A Comprehensive Technical Guide

> Explore the core features of the Hello-Agents project. Discover its modular LLM framework, agent paradigms like ReAct, and extensible tool and vector-store memory integration.

- Repository: [Datawhale/hello-agents](https://github.com/datawhalechina/hello-agents)
- Tags: deep-dive
- Published: 2026-05-09

---

**The hello-agents project provides a modular, educational framework that unifies LLM clients, implements classic agent paradigms like ReAct and Plan-and-Solve, and offers extensible tool integration with vector-store memory retrieval capabilities.**

The hello-agents repository by DataWhaleChina is an open-source learning framework designed to bridge the gap between LLM theory and production implementation. Understanding the core features of the hello-agents project reveals how this tutorial-based codebase enables developers to build sophisticated AI agents through reusable Python classes and hands-on case studies.

## Unified LLM Client Architecture

At the heart of the framework lies the **`HelloAgentsLLM`** class located in [`hello_agents/core/llm.py`](https://github.com/datawhalechina/hello-agents/blob/main/hello_agents/core/llm.py). This unified client abstracts provider-specific implementations and automatically loads credentials from environment variables, supporting multiple backends including ModelScope, Ollama, and VLLM.

The client exposes a consistent interface for chat completion and reasoning tasks, allowing you to swap underlying models without altering agent logic. As implemented in [`hello_agents/__init__.py`](https://github.com/datawhalechina/hello-agents/blob/main/hello_agents/__init__.py), the `SimpleAgent` base class inherits from this architecture, providing plug-in points for custom providers through simple subclassing.

```python
from hello_agents import HelloAgentsLLM

class MyLLM(HelloAgentsLLM):
    def __init__(self, model: str = "my-model"):
        # Custom logic to locate API key & endpoint for MyProvider

        super().__init__(model=model, provider="myprovider")

my_llm = MyLLM()
print(my_llm.think([{"role":"user","content":"说中文"}]))

```

## Classic Agent Paradigms

The project delivers complete, runnable implementations of three seminal agent architectures documented in `docs/chapter4/第四章 智能体经典范式构建.md`.

**ReAct Agent** combines reasoning and acting in an interleaved loop. The `ReActAgent` class manages the `Thought` → `Action` → `Observation` cycle, parsing LLM outputs to execute tools and iterate until reaching a `Finish[…]` condition.

**Plan-and-Solve Agent** decomposes complex queries through a dedicated `Planner` module that creates step-by-step strategies, while the `Executor` handles individual task completion. This separation of planning and execution allows for more structured handling of multi-step problems.

**Reflection Agent** implements self-correction mechanisms where the agent evaluates its own outputs and iteratively refines responses based on internal critique.

```python

# Basic agent with ReAct paradigm

from hello_agents import HelloAgentsLLM, ToolExecutor, ReActAgent

# Load .env automatically

llm = HelloAgentsLLM()

# Register a simple web‑search tool (SerpApi wrapper)

def search(query: str) -> str:
    # …implementation omitted (see chapter 4)

    ...

tool_exec = ToolExecutor()
tool_exec.registerTool(
    name="Search",
    description="Web search tool for real‑time facts.",
    func=search,
)

agent = ReActAgent(llm_client=llm, tool_executor=tool_exec)
answer = agent.run("华为最新手机的主要卖点是什么？")
print("🧭 Final answer →", answer)

```

## Tool Integration Layer

The **`ToolExecutor`** class provides a generic registry for external capabilities. Located in the Chapter 4 implementation files (see lines 66-78 of the ReAct documentation), this layer exposes a uniform `name → function` API that translates agent outputs into concrete actions.

Any Python function can be registered as a tool, including web search via SerpApi, calculators, or database queries. The executor handles parameter validation and error propagation, ensuring that tool failures are gracefully communicated back to the agent as observations.

## Memory and Retrieval Systems

Chapter 8 (`docs/chapter8/第八章 记忆与检索.md`) introduces a modular memory subsystem supporting vector-store retrieval and RAG-style augmentation. The **`Memory`** and **`Retriever`** classes enable agents to persist conversation history and retrieve relevant documents based on semantic similarity.

This subsystem supports document chunking strategies and integrates with the planning agents to prepend retrieved context to prompts, effectively grounding LLM responses in external knowledge bases.

```python

# Plan‑and‑Solve agent with memory support

from hello_agents import HelloAgentsLLM, Planner, Executor, PlanAndSolveAgent, Memory

llm = HelloAgentsLLM()
memory = Memory(vector_store_path="data/vectors")   # RAG store

planner = Planner(llm)
executor = Executor(llm, memory=memory)  # executor will prepend retrieved docs

agent = PlanAndSolveAgent(planner, executor)
final = agent.run("请写一篇 500 字的关于 AI 代理的综述")
print(final)

```

## Advanced Capabilities

Beyond basic agent loops, the framework addresses production concerns through three specialized modules:

**Context Engineering** (`docs/chapter9/第九章 上下文工程.md`) provides techniques for managing long-term conversation state, including sliding window management and hierarchical prompt construction.

**Agentic RL** (`docs/chapter11/第十一章 Agentic-RL.md`) implements end-to-end training pipelines from supervised fine-tuning (SFT) to GRPO (Generalized Reward-Penalty Optimization), enabling reinforcement learning for agentic behaviors.

**Performance Evaluation** (`docs/chapter12/第十二章 智能体性能评估.md`) supplies benchmark suites and metrics for measuring correctness, latency, and token usage across agent implementations.

## Low-Code Platform Integration

For rapid prototyping and non-programmer accessibility, Chapter 5 (`docs/chapter5/第五章 基于低代码平台的智能体搭建.md`) provides tutorials for visual agent construction using **Coze**, **Dify**, and **n8n**. These integrations allow users to transfer concepts learned in Python implementations to production-ready low-code environments.

## Real-World Case Studies

Chapters 13-15 demonstrate end-to-end applications combining all core features:

- **Travel Assistant**: Multi-agent system for itinerary planning and booking
- **Deep-Research Agent**: Academic literature review automation
- **Cyber-Town**: Multi-agent simulation environment

These implementations showcase how the `SimpleAgent` base class and `ToolExecutor` combine to handle complex, real-world workflows.

## Implementation Workflow

According to the source code structure, a typical hello-agents workflow follows this pattern:

1. **Initialize** the LLM client: `llm = HelloAgentsLLM()`
2. **Create** a tool registry via `ToolExecutor.registerTool(...)`
3. **Choose** a paradigm: instantiate `ReActAgent`, `PlanAndSolveAgent`, or `ReflectionAgent`
4. **Run** the agent: `agent.run(question)` triggers the thought-action-observation loop
5. **Augment** with memory: retrieve documents via `Memory.retrieve(query)` before LLM calls
6. **Evaluate** results using the metrics suite in the evaluation module

All components are deliberately modular, allowing substitution of LLM providers, tool sets, or prompting strategies without modifying the core execution loop.

## Summary

- **Unified Client**: The `HelloAgentsLLM` class in [`hello_agents/core/llm.py`](https://github.com/datawhalechina/hello-agents/blob/main/hello_agents/core/llm.py) abstracts provider-specific implementations for seamless model swapping.
- **Three Paradigms**: Complete ReAct, Plan-and-Solve, and Reflection implementations with reusable Python classes.
- **Tool Registry**: Generic `ToolExecutor` supporting any external function with uniform API mapping.
- **RAG Support**: Modular memory subsystem with vector-store retrieval and document chunking.
- **Production Ready**: Advanced modules for context engineering, reinforcement learning, and systematic evaluation.
- **Educational Structure**: Chapter-based documentation progressing from fundamentals to complex multi-agent systems.

## Frequently Asked Questions

### What is the difference between ReActAgent and PlanAndSolveAgent?

**ReActAgent** interleaves reasoning and action in a single loop, making decisions step-by-step based on immediate observations. **PlanAndSolveAgent** separates the workflow into distinct phases: first generating a complete plan through the `Planner` class, then executing steps via the `Executor` class. This makes Plan-and-Solve better for complex multi-step tasks requiring structured decomposition, while ReAct offers more flexibility for dynamic environments.

### How does the ToolExecutor handle external API authentication?

The `ToolExecutor` class manages tool registration and execution but delegates authentication to the individual tool functions. When registering a tool via `registerTool()`, you provide a Python function that internally handles API keys—typically loading them from environment variables or secure vaults. The executor focuses on routing agent outputs to the correct function and formatting observations for the agent loop.

### Can I use hello-agents with local models like Ollama or VLLM?

Yes. The `HelloAgentsLLM` client in [`hello_agents/core/llm.py`](https://github.com/datawhalechina/hello-agents/blob/main/hello_agents/core/llm.py) supports multiple providers including ModelScope, Ollama, and VLLM through its extensible provider architecture. You can configure the provider during instantiation or subclass `HelloAgentsLLM` to implement custom authentication logic for local endpoints, as demonstrated in the framework's extension examples.

### Where are the memory and retrieval implementations documented?

The memory subsystem is detailed in `docs/chapter8/第八章 记忆与检索.md`, which introduces the `Memory` and `Retriever` classes. This documentation covers vector-store configuration, document chunking strategies, and RAG integration patterns. The chapter provides executable examples showing how to initialize persistent storage and retrieve relevant context to augment agent prompts before LLM calls.