# Prerequisites for Installing Hello-Agents: Complete Setup Guide

> Install Hello-Agents with ease. Discover the essential prerequisites including Python 3.10+, key packages, API keys, and Git for seamless setup.

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

---

**To install and run Hello-Agents, you need Python 3.10+, core pip packages (`requests`, `tavily-python`, `openai`), valid API keys for an LLM provider and Tavily, and Git to clone the repository.**

The Hello-Agents tutorial from Datawhale China provides a hands-on introduction to building AI agents. Before running the example scripts like [`code/chapter1/FirstAgentTest.py`](https://github.com/datawhalechina/hello-agents/blob/main/code/chapter1/FirstAgentTest.py), you must configure your environment according to the specifications detailed in `Extra-Chapter/Extra07-环境配置.md`.

## System Requirements

Hello-Agents requires a modern Python interpreter and version control tools to get started.

### Python 3.10 or Newer

The codebase relies on modern Python syntax and type hints introduced in Python 3.10. As documented in the environment configuration guide, versions prior to 3.10 are not supported.

```bash

# Verify your Python version

python --version  # Must be 3.10 or higher

```

### Git for Cloning

You need Git to obtain the source code, tutorials, and example notebooks from the repository.

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

```

## Python Dependencies

The core runtime depends on specific versions of HTTP and AI service libraries. According to `Extra-Chapter/Extra07-环境配置.md`, you must install:

- `requests>=2.31.0` – For HTTP requests to weather and other APIs
- `tavily-python>=0.3.0` – For the Tavily search API used in travel-assistant examples
- `openai>=1.0.0` – For OpenAI-compatible LLM clients
- `python-dotenv>=1.0.0` – (Optional) For loading `.env` configuration files

### Virtual Environment Setup

While optional, creating a virtual environment is highly recommended to isolate Hello-Agents dependencies from your global Python installation.

```bash

# Create and activate virtual environment

python -m venv venv

# Windows

venv\Scripts\activate

# macOS / Linux

source venv/bin/activate

```

### Installing Core Packages

Install the dependencies using pip after activating your environment:

```bash
pip install requests tavily-python openai python-dotenv

```

## API Credentials Configuration

Hello-Agents requires external API access to function. You must supply **LLM** and **Tavily** keys, with an optional ModelScope key for specific use cases.

### Required Environment Variables

The repository includes a template `.env.example` file (located in `code/chapter7/.env.example`) showing the required variables:

```text
LLM_API_KEY=your_llm_key
LLM_BASE_URL=https://aihubmix.com/v1
LLM_MODEL_ID=coding-glm-4.7-free
TAVILY_API_KEY=your_tavily_key

```

Copy the template and fill in your actual credentials:

```bash
cp .env.example .env

# Edit .env with your preferred text editor

```

These secrets are never checked into the repository. The `python-dotenv` library loads them automatically when running examples.

### Testing Your Configuration

Verify your setup by testing the API connections as shown in the documentation:

```python
import os
from tavily import TavilyClient
from openai import OpenAI

# Test Tavily connection

tavily = TavilyClient(api_key=os.getenv("TAVILY_API_KEY"))
print(tavily.search("Shanghai"))

# Test LLM connection

client = OpenAI(
    api_key=os.getenv("LLM_API_KEY"), 
    base_url=os.getenv("LLM_BASE_URL")
)
resp = client.chat.completions.create(
    model=os.getenv("LLM_MODEL_ID"),
    messages=[{"role": "user", "content": "Hello"}],
    max_tokens=5,
)
print(resp.choices[0].message.content)

```

## Optional Components

Certain chapters and demos require additional tools beyond the core prerequisites.

### Local LLM Inference Tools

For running local models via VLLM or Ollama (referenced in Chapter 4), install the respective runtime:

- **VLLM** – For high-throughput local inference (requires CUDA-compatible GPU for optimal performance)
- **Ollama** – For local model management without complex setup

### Game Engine for AI Town

The AI-Town simulation case requires **Godot** engine installation. Consult the specific chapter sections in `docs/chapter4/第四章 智能体经典范式构建.md` for version requirements.

### CUDA and GPU Drivers

If you plan to run local LLMs through VLLM on GPU, you need compatible NVIDIA drivers and CUDA toolkit. Without GPU support, you must rely on remote LLM services (AIHubmix, ModelScope, etc.) as documented in the installation guide.

## Step-by-Step Installation

Follow this complete workflow to get Hello-Agents running locally:

1. **Clone the repository**

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

```

2. **Create and activate virtual environment**

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

```

3. **Install dependencies**

```bash
pip install requests tavily-python openai python-dotenv

```

4. **Configure credentials**

```bash
cp code/chapter7/.env.example .env

# Edit .env to add your LLM_API_KEY, LLM_BASE_URL, LLM_MODEL_ID, and TAVILY_API_KEY

```

5. **Run the first example**

```bash
python code/chapter1/FirstAgentTest.py

```

## Summary

- **Python 3.10+** is mandatory for modern syntax support and type hints used throughout the codebase.
- **Core packages** include `requests>=2.31.0`, `tavily-python>=0.3.0`, and `openai>=1.0.0`, managed best within a virtual environment.
- **API credentials** for an LLM provider and Tavily must be configured via environment variables or a `.env` file based on the template in `code/chapter7/.env.example`.
- **Optional tools** like VLLM, Ollama, and Godot are only needed for specific chapters covering local model inference or the AI-Town simulation.
- **GPU support** via CUDA is optional but recommended for local LLM execution; remote APIs work without dedicated hardware.

## Frequently Asked Questions

### Can I use Python 3.9 to install Hello-Agents?

No. The repository requires Python 3.10 or newer according to `Extra-Chapter/Extra07-环境配置.md`. The codebase utilizes type hint syntax and features introduced in Python 3.10, making earlier versions incompatible.

### Do I need a GPU to run Hello-Agents examples?

No, a GPU is optional. You can run all examples using remote LLM services (AIHubmix, ModelScope, or OpenAI). However, if you plan to run local models via VLLM as demonstrated in Chapter 4, a CUDA-compatible GPU is strongly recommended for reasonable performance.

### Where should I store my API keys for Hello-Agents?

Store API keys in a `.env` file in your project root. Copy the template from `code/chapter7/.env.example` and fill in `LLM_API_KEY`, `LLM_BASE_URL`, `LLM_MODEL_ID`, and `TAVILY_API_KEY`. The `python-dotenv` library loads these variables automatically when running scripts.

### What if I don't have a Tavily API key?

The Tavily API key is required for search functionality in the travel-assistant examples like [`code/chapter1/FirstAgentTest.py`](https://github.com/datawhalechina/hello-agents/blob/main/code/chapter1/FirstAgentTest.py). You can obtain a key from the Tavily website. Without it, examples utilizing web search capabilities will fail, though you can still test basic LLM connectivity.