# How to Set Up the datawhalechina/hello-agents Repository: Complete Installation Guide

> Learn how to set up the datawhalechina/hello-agents repository with our step by step guide. Clone, install, configure API keys and instantiate an agent to get started quickly.

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

---

**Clone the repository, install the hello-agents framework via `pip install "hello-agents==0.1.1"`, configure your API keys in a `.env` file, and instantiate a `SimpleAgent` with `HelloAgentsLLM` to verify your setup.**

The datawhalechina/hello-agents repository is a chapter-by-chapter tutorial that guides you from large language model fundamentals to building full-stack AI agents. Setting up this repository gives you access to a lightweight teaching framework, executable examples for each chapter, and auto-detecting LLM clients that work with OpenAI, ModelScope, vLLM, and Ollama without code changes.

## Step-by-Step Setup Guide

### 1. Clone the Repository

Start by cloning the GitHub repository to access the documentation, source code, and chapter examples.

```bash
git clone https://github.com/datawhalechina/hello-agents.git
cd hello-agents

```

### 2. Create a Python Virtual Environment

Isolate your dependencies to avoid conflicts with system Python packages.

```bash
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

```

### 3. Install the Core Framework

Install the stable package version used throughout the tutorial. According to `docs/chapter7/第七章 构建你的Agent框架.md`, this specific version ensures compatibility with the chapter examples.

```bash
pip install "hello-agents==0.1.1"

```

Some chapters require additional dependencies. For Chapter 7, install any extra requirements listed in [`code/chapter7/requirements.txt`](https://github.com/datawhalechina/hello-agents/blob/main/code/chapter7/requirements.txt):

```bash
pip install -r code/chapter7/requirements.txt

```

### 4. Configure API Credentials

The `HelloAgentsLLM` class in [`hello_agents/core/llm.py`](https://github.com/datawhalechina/hello-agents/blob/main/hello_agents/core/llm.py) automatically detects your LLM provider by reading environment variables. Create a `.env` file in the repository root:

```bash

# .env

OPENAI_API_KEY="sk-..."
MODELSCOPE_API_KEY="..."
LLM_BASE_URL="https://api.openai.com/v1"  # Optional: for custom endpoints

```

The framework supports multiple providers including OpenAI, ModelScope, Zhipu, vLLM, and Ollama. The detection order prioritizes service-specific keys, then examines `LLM_BASE_URL` for local server patterns like `localhost:8000` (vLLM) or `localhost:11434` (Ollama).

### 5. Verify Installation

Run a minimal script to confirm everything is wired correctly. Create a file named [`verify_setup.py`](https://github.com/datawhalechina/hello-agents/blob/main/verify_setup.py):

```python
from dotenv import load_dotenv
from hello_agents import SimpleAgent, HelloAgentsLLM

# Load API keys from .env

load_dotenv()

# Initialize the unified LLM client (auto-detects provider)

llm = HelloAgentsLLM()

# Create a basic agent using the abstract Agent base class

agent = SimpleAgent(
    name="TestAgent",
    llm=llm,
    system_prompt="You are a helpful assistant."
)

# Test interaction

response = agent.run("Hello! Introduce yourself briefly.")
print("Agent response:", response)

```

Execute the verification:

```bash
python verify_setup.py

```

If configured correctly, you will see a response from your chosen LLM provider.

## Repository Structure Overview

Understanding the three-layer architecture helps you navigate the codebase effectively.

### Documentation Layer (`docs/`)

The `docs/` directory contains Markdown chapters explaining agent theory and paradigms like ReAct, Plan-and-Solve, and Reflection. Each chapter includes quick-start commands and conceptual explanations.

### Framework Source (`hello_agents/`)

This directory contains the teaching-oriented agent framework:

- **[`hello_agents/core/agent.py`](https://github.com/datawhalechina/hello-agents/blob/main/hello_agents/core/agent.py)**: Defines the abstract `Agent` base class that all concrete agents implement.
- **[`hello_agents/core/llm.py`](https://github.com/datawhalechina/hello-agents/blob/main/hello_agents/core/llm.py)**: Implements `HelloAgentsLLM`, the unified client with auto-detection logic for multiple providers.
- **[`hello_agents/core/message.py`](https://github.com/datawhalechina/hello-agents/blob/main/hello_agents/core/message.py)**: Contains the `Message` data model for standardized communication.
- **`hello_agents/agents/`**: Houses concrete implementations including `SimpleAgent`, `ReactAgent`, `ReflectionAgent`, and `PlanSolveAgent`.
- **[`hello_agents/tools/registry.py`](https://github.com/datawhalechina/hello-agents/blob/main/hello_agents/tools/registry.py)**: Contains the `ToolRegistry` class for managing utilities like `CalculatorTool`.

### Executable Examples (`code/`)

Each chapter has a corresponding `code/chapterX/` directory with runnable notebooks and scripts. For example, [`code/chapter7/my_simple_agent.py`](https://github.com/datawhalechina/hello-agents/blob/main/code/chapter7/my_simple_agent.py) demonstrates how to extend the base `SimpleAgent` with tool-calling capabilities by subclassing and implementing optional tool execution logic.

## Running Advanced Examples

Once the basic setup is complete, you can run more sophisticated agents.

### Tool-Enabled Agent with MySimpleAgent

The repository includes `MySimpleAgent` in [`code/chapter7/my_simple_agent.py`](https://github.com/datawhalechina/hello-agents/blob/main/code/chapter7/my_simple_agent.py), which extends the base agent with tool execution. Run this example from the `code/chapter7/` directory:

```python
from dotenv import load_dotenv
from hello_agents import HelloAgentsLLM, ToolRegistry
from hello_agents.tools import CalculatorTool
from my_simple_agent import MySimpleAgent

load_dotenv()

llm = HelloAgentsLLM()
registry = ToolRegistry()
registry.register_tool(CalculatorTool())

agent = MySimpleAgent(
    name="CalculatorBot",
    llm=llm,
    system_prompt="You can use tools to help with calculations.",
    tool_registry=registry,
    enable_tool_calling=True
)

result = agent.run("Calculate 15 * 8 + 32")
print(result)

```

The agent detects `[TOOL_CALL:calculator:...]` patterns in the LLM output, executes the `CalculatorTool` via the registry, and returns the final result.

### Switching to Local Models (vLLM/Ollama)

You can switch to local inference without modifying code. The `HelloAgentsLLM` class detects local endpoints via `LLM_BASE_URL`:

```bash

# .env for vLLM

LLM_BASE_URL="http://localhost:8000/v1"
LLM_API_KEY="vllm"  # Dummy value for vLLM

```

Or for Ollama:

```bash

# .env for Ollama

LLM_BASE_URL="http://localhost:11434"

```

With these variables set, the instantiation `llm = HelloAgentsLLM()` automatically routes to your local server.

## Summary

- **Clone** the datawhalechina/hello-agents repository to access tutorials, framework source in `hello_agents/`, and chapter examples in `code/`.
- **Install** the framework using `pip install "hello-agents==0.1.1"` and chapter-specific requirements from files like [`code/chapter7/requirements.txt`](https://github.com/datawhalechina/hello-agents/blob/main/code/chapter7/requirements.txt).
- **Configure** API keys in a `.env` file; the `HelloAgentsLLM` client auto-detects providers (OpenAI, ModelScope, vLLM, Ollama) based on environment variables as implemented in [`hello_agents/core/llm.py`](https://github.com/datawhalechina/hello-agents/blob/main/hello_agents/core/llm.py).
- **Extend** functionality by subclassing the abstract `Agent` class defined in [`hello_agents/core/agent.py`](https://github.com/datawhalechina/hello-agents/blob/main/hello_agents/core/agent.py) or using `MySimpleAgent` from [`code/chapter7/my_simple_agent.py`](https://github.com/datawhalechina/hello-agents/blob/main/code/chapter7/my_simple_agent.py) for tool-enabled workflows.
- **Verify** your installation by running a `SimpleAgent` instance that connects to your configured LLM provider.

## Frequently Asked Questions

### What Python version is required for hello-agents?

The framework requires Python 3.8 or higher. Create a virtual environment to ensure dependency isolation, as some chapters install additional packages like `sentence-transformers` or `qdrant-client` for specific memory and retrieval functionalities.

### Can I use hello-agents without an OpenAI API key?

Yes. According to the provider detection logic in [`hello_agents/core/llm.py`](https://github.com/datawhalechina/hello-agents/blob/main/hello_agents/core/llm.py), you can use ModelScope, Zhipu AI, or local models via vLLM and Ollama by setting the appropriate environment variables (`MODELSCOPE_API_KEY`, `LLM_BASE_URL`, etc.) in your `.env` file instead of `OPENAI_API_KEY`.

### How do I add custom tools to my agent?

Register your tool with the `ToolRegistry` class from [`hello_agents/tools/registry.py`](https://github.com/datawhalechina/hello-agents/blob/main/hello_agents/tools/registry.py). Create a tool class following the pattern in [`hello_agents/tools/builtin/calculator.py`](https://github.com/datawhalechina/hello-agents/blob/main/hello_agents/tools/builtin/calculator.py), then instantiate `ToolRegistry()`, call `registry.register_tool(YourTool())`, and pass the registry to your agent constructor. The [`code/chapter7/my_simple_agent.py`](https://github.com/datawhalechina/hello-agents/blob/main/code/chapter7/my_simple_agent.py) file demonstrates this pattern with `CalculatorTool` and the `[TOOL_CALL:calculator:...]` execution pattern.

### Where can I find the chapter-specific code examples?

Each chapter's executable code lives in `code/chapterX/`. For example, Chapter 7 examples are in `code/chapter7/`, including [`my_simple_agent.py`](https://github.com/datawhalechina/hello-agents/blob/main/my_simple_agent.py) and associated requirements files. These directories contain the exact scripts referenced in the documentation and require the chapter-specific dependencies to be installed before running.