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

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.

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.

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.

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:

pip install -r code/chapter7/requirements.txt

4. Configure API Credentials

The HelloAgentsLLM class in hello_agents/core/llm.py automatically detects your LLM provider by reading environment variables. Create a .env file in the repository root:

# .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:

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:

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: Defines the abstract Agent base class that all concrete agents implement.
• hello_agents/core/llm.py: Implements HelloAgentsLLM, the unified client with auto-detection logic for multiple providers.
• 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: 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 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, which extends the base agent with tool execution. Run this example from the code/chapter7/ directory:

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:

# .env for vLLM

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

Or for Ollama:

# .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.
• 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.
• Extend functionality by subclassing the abstract Agent class defined in hello_agents/core/agent.py or using MySimpleAgent from 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, 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. Create a tool class following the pattern in 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 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 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.

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