# How to Run the Hello-Agents Project Locally: A Complete Setup Guide

> Master running the hello-agents project locally. Clone the repo, install dependencies, set up Ollama, and launch your first agent with this complete setup guide.

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

---

**Clone the repository, install dependencies from the shared [`requirements.txt`](https://github.com/datawhalechina/hello-agents/blob/main/requirements.txt), configure a local LLM backend like Ollama, and execute any chapter script (e.g., `python code/chapter7/my_main.py`) to instantiate and run your first agent.**

Hello-Agents, maintained by Datawhale China, is a hands-on tutorial repository that teaches agent development through executable Python examples. To run the hello-agents project locally, you need Python 3.9 or higher, a virtual environment, and a compatible LLM backend such as Ollama or OpenAI. This guide walks through the exact commands and file paths needed to get the `code` folder examples running on your machine.

## Prerequisites and Environment Setup

Before installing packages, prepare an isolated Python environment. The repository structure places all runnable examples inside the `code/` directory, with each chapter containing standalone scripts that instantiate the **`Agent`** class and call its **`run()`** method.

Clone the repository and create a virtual environment:

```bash
git clone https://github.com/datawhalechina/hello-agents.git
cd hello-agents
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

```

According to the "local reading" section in [`README_EN.md`](https://github.com/datawhalechina/hello-agents/blob/main/README_EN.md), the `code` folder contains all runnable examples designed for hands-on learning.

## Install Dependencies from requirements.txt

Most chapters share a common dependency stack listed in the repository's [`requirements.txt`](https://github.com/datawhalechina/hello-agents/blob/main/requirements.txt) files. The canonical list resides in **[`Co-creation-projects/czxgg0630-ProductAnalysisAgent/requirements.txt`](https://github.com/datawhalechina/hello-agents/blob/main/Co-creation-projects/czxgg0630-ProductAnalysisAgent/requirements.txt)**, though individual chapters may include their own variants.

Install the core dependencies:

```bash
pip install -r Co-creation-projects/czxgg0630-ProductAnalysisAgent/requirements.txt

```

For chapter-specific minimal installs, target the individual requirements files:

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

```

These files typically include **openai**, **langchain**, **tiktoken**, **pydantic**, and **pytest** for the test harness. The environment configuration documentation in `Extra-Chapter/Extra07-环境配置.md` references these requirements for setting up your development environment.

## Configure Your Local LLM Backend

Hello-Agents supports three primary backends for local execution. The repository explicitly recommends the **Qwen 0.5B** model for lightweight local runs.

Choose one of the following configurations:

- **Ollama (Recommended)**: Run `ollama run qwen:0.5b` to start a local server. This is the simplest option for beginners.
- **vLLM**: For high-throughput local serving, use `python -m vllm.entrypoints.openai --model Qwen/Qwen1.5-0.5B-Chat`.
- **OpenAI API**: For cloud access, create a `.env` file based on the `.env.example` templates found in each chapter directory and set your `OPENAI_API_KEY`.

Keep your chosen backend running in a separate terminal while executing agent scripts.

## Execute Sample Agent Scripts

With dependencies installed and the LLM backend active, run the tutorial scripts located in chapter-specific subdirectories.

### Run the Chapter 4 ReAct Agent Example

Execute the introductory ReAct implementation:

```bash
python code/chapter4/01_context_builder_basic.py

```

This script creates a **`ReActAgent`**, processes a user query, and prints the generated response. The core logic demonstrates the fundamental agent paradigm covered in Chapter 4.

### Run the Chapter 7 Custom Framework

For the full-stack "Build Your Agent Framework" tutorial:

```bash
python code/chapter7/my_main.py

```

The **[`my_main.py`](https://github.com/datawhalechina/hello-agents/blob/main/my_main.py)** file wires together the **`SimpleAgent`**, registers a calculator tool, and executes a demo conversation. This serves as the primary entry point for understanding custom agent framework construction.

### Run the Chapter 9 Context Engineering Pipeline

Test the persistent context storage mechanism:

```bash
python code/chapter9/02_context_builder_with_agent.py

```

This example demonstrates how a **context builder** stores intermediate results and feeds them back to the LLM on subsequent turns, illustrating advanced context engineering patterns.

## Verify Installation with pytest

Each chapter includes test files prefixed with `test_` that validate the implementation using **pytest**. Run these to confirm your environment is correctly configured:

```bash
pytest code/chapter7/test_*.py

```

Successful test execution confirms that dependencies, LLM connectivity, and local environment variables are properly wired. The Chapter 8 documentation specifically mentions running these tests as part of the experiential learning workflow.

## Summary

Running the hello-agents project locally requires three main components: a Python 3.9+ virtual environment, installation of dependencies from the consolidated [`requirements.txt`](https://github.com/datawhalechina/hello-agents/blob/main/requirements.txt), and an active LLM backend. Key takeaways include:

- Clone from `https://github.com/datawhalechina/hello-agents` and use the `code/` directory for all examples.
- Install dependencies via `pip install -r Co-creation-projects/czxgg0630-ProductAnalysisAgent/requirements.txt`.
- Use **Ollama** with `qwen:0.5b` for the simplest local setup.
- Execute entry points like [`code/chapter7/my_main.py`](https://github.com/datawhalechina/hello-agents/blob/main/code/chapter7/my_main.py) to run specific tutorials.
- Verify functionality using `pytest` against chapter-specific test files.

## Frequently Asked Questions

### What Python version is required to run hello-agents locally?

The project requires **Python 3.9 or higher**. While the code may run on older versions, the dependencies (particularly LangChain and Pydantic) and type hints used throughout the `code/` directory are validated against Python 3.9+ semantics.

### Which LLM backend is recommended for beginners?

**Ollama** is the recommended backend for local execution. Running `ollama run qwen:0.5b` provides a lightweight, open-source model that requires no API keys and minimal configuration. The repository explicitly mentions this setup in the README as the default for local runs.

### How do I configure API keys for cloud LLM providers?

Create a `.env` file in your working directory based on the `.env.example` templates found in each chapter folder. Set your `OPENAI_API_KEY` (or other provider keys) there. The `Extra-Chapter/Extra07-环境配置.md` file contains detailed instructions for environment variable configuration and `.env` file setup.

### How do I verify that the installation is working correctly?

Run the pytest suites included in each chapter directory using `pytest code/chapter*/test_*.py`. Additionally, execute a simple agent script like [`code/chapter4/01_context_builder_basic.py`](https://github.com/datawhalechina/hello-agents/blob/main/code/chapter4/01_context_builder_basic.py)—if it produces output without ImportError or connection errors, your local setup is functional.