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

Clone the repository, install dependencies from the shared 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:

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, 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 files. The canonical list resides in Co-creation-projects/czxgg0630-ProductAnalysisAgent/requirements.txt, though individual chapters may include their own variants.

Install the core dependencies:

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

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

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:

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:

python code/chapter7/my_main.py

The 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:

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:

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, 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 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—if it produces output without ImportError or connection errors, your local setup is functional.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}