Prerequisites for Installing Hello-Agents: Complete Setup Guide

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, 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.

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

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.

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

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:

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:

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:

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

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

2. Create and activate virtual environment

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

3. Install dependencies

pip install requests tavily-python openai python-dotenv

4. Configure credentials

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

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

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