DEV Community

Henry Lin
Henry Lin

Posted on

RD-Agent Tutorial - Chapter 1: Basic Introduction

RD-Agent Tutorial - Chapter 1: Basic Introduction

1.1 Project Overview and Core Philosophy

Introduction to RD-Agent

RD-Agent (Research & Development Agent) is an open-source automated R&D framework developed by Microsoft Research, specifically designed for building data-driven AI solutions. This project achieved first place in the industry-standard machine learning engineering benchmark MLE-bench, making it the best-performing machine learning agent to date.

Core Philosophy: The R&D Framework

The design philosophy of RD-Agent is based on two core components:

  • R (Research): πŸ”¬ Research Component

    • Automatically propose new hypotheses and ideas
    • Analyze limitations of existing solutions
    • Generate innovative solutions based on domain knowledge

  • D (Development): πŸ› οΈ Development Component

    • Transform research ideas into executable code
    • Implement and validate hypotheses
    • Continuously optimize and improve solutions

MLE-bench Benchmark Performance

Agent Low (%) Medium (%) High (%) All (%)
R&D-Agent o1-preview 48.18 Β± 2.49 8.95 Β± 2.36 18.67 Β± 2.98 22.4 Β± 1.1
R&D-Agent o3(R)+GPT-4.1(D) 51.52 Β± 6.21 7.89 Β± 3.33 16.67 Β± 3.65 22.45 Β± 2.45
AIDE o1-preview 34.3 Β± 2.4 8.8 Β± 1.1 10.0 Β± 1.9 16.9 Β± 1.1

Core Advantages and Application Value

1. Automated Data-Driven R&D Process

  • End-to-end Automation: Complete workflow from data analysis to model deployment
  • Intelligent Decision Support: Automatically generate solutions based on data insights
  • Continuous Learning: Learn from historical experience and continuously improve

2. Multi-Agent Collaboration Architecture 

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”    β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”    β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚   Research Agent β”‚    β”‚ Development     β”‚    β”‚  Evaluation      β”‚
β”‚                 │◄──►│ Agent           │◄──►│ Agent           β”‚
β”‚β€’ Hypothesis      β”‚    β”‚β€’ Code           β”‚    β”‚β€’ Performance    β”‚
β”‚  generation      β”‚    β”‚  implementation   β”‚    β”‚  evaluation     β”‚
β”‚β€’ Strategy        β”‚    β”‚β€’ Testing        β”‚    β”‚β€’ Feedback       β”‚
β”‚  planning        β”‚    β”‚β€’ Optimization   β”‚    β”‚β€’ quality control β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜    β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜    β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
Enter fullscreen mode Exit fullscreen mode

3. Continuous Learning and Evolution Capabilities

  • CoSTEER Framework: Collaborative Strategy Evolution Framework
  • Knowledge Accumulation: Automatically build and maintain domain knowledge base
  • Adaptive Optimization: Dynamically adjust strategies based on feedback

Application Scenarios and Target Users

🏒 Quantitative Investment Teams

  • Automatic Factor Mining: Discover effective factors from massive data
  • Strategy Development: Automatically generate and optimize trading strategies
  • Risk Management: Intelligent risk control and portfolio optimization
  • Cost Efficiency: Achieve 2x returns at less than $10 cost compared to traditional methods

πŸ”¬ Data Scientists

  • Automated Feature Engineering: Intelligent feature generation and selection
  • Model Selection Optimization: Automated model architecture search
  • Experiment Management: Systematic experiment tracking and comparison
  • Pipeline Construction: End-to-end machine learning pipeline auto-construction

πŸŽ“ Researchers and Scholars

  • Paper Reproduction: Automatically extract and implement models from papers
  • Research Assistant: Intelligent literature analysis and knowledge extraction
  • Experiment Design: Scientific experiment planning and execution
  • Research Documentation: Automated research achievement documentation

πŸ† Kaggle Competition Participants

  • End-to-end Automation: From data exploration to model submission
  • Feature Engineering: Intelligent feature creation and combination
  • Model Ensemble: Multi-model fusion strategy optimization
  • Time Management: Efficient competition time allocation

1.2 System Requirements and Environment Preparation

Hardware and Software Requirements

Operating System Support

  • Linux: βœ… Fully supported (Ubuntu 18.04+, CentOS 7+)
  • Windows: ❌ Currently not supported
  • macOS: ❌ Currently not supported

Important Note: RD-Agent currently supports only Linux systems. If you are using Windows or macOS, it is recommended to use Docker, WSL2, or a virtual machine to run a Linux environment.

Python Version Requirements

  • Python 3.10: βœ… Fully supported (recommended)
  • Python 3.11: βœ… Fully supported
  • Python 3.9: ⚠️ Some features may be limited
  • Python 3.12+: ⚠️ May have compatibility issues

Memory and Computing Resource Recommendations

Use Case Memory Requirement CPU Requirement Storage Space
Lightweight Use 4GB+ 2 cores+ 10GB+
Medium Scale 8GB+ 4 cores+ 50GB+
Large Scale 16GB+ 8 cores+ 100GB+
Production 32GB+ 16 cores+ 500GB+

Docker Environment Configuration

Docker Installation and Configuration

RD-Agent heavily relies on Docker to provide isolated runtime environments, ensuring experiment reproducibility.

Ubuntu/Debian Docker Installation:

# Update package index
sudo apt-get update

# Install necessary packages
sudo apt-get install \
    apt-transport-https \
    ca-certificates \
    curl \
    gnupg \
    lsb-release

# Add Docker official GPG key
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

# Set up stable repository
echo \
  "deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker Engine
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io
Enter fullscreen mode Exit fullscreen mode

CentOS/RHEL Docker Installation:

# Install necessary packages
sudo yum install -y yum-utils

# Add Docker repository
sudo yum-config-manager \
    --add-repo \
    https://download.docker.com/linux/centos/docker-ce.repo

# Install Docker Engine
sudo yum install docker-ce docker-ce-cli containerd.io

# Start Docker service
sudo systemctl start docker
sudo systemctl enable docker
Enter fullscreen mode Exit fullscreen mode

Running Docker Without sudo Permissions

This is a required configuration step! RD-Agent requires that the current user can run Docker commands without using sudo.

# Create docker user group (if it doesn't exist)
sudo groupadd docker

# Add current user to docker group
sudo usermod -aG docker $USER

# Reload user group permissions (or re-login)
newgrp docker

# Verify configuration is successful
docker run hello-world
Enter fullscreen mode Exit fullscreen mode

Expected Output:

Hello from Docker!
This message shows that your installation appears to be working correctly.
...
Enter fullscreen mode Exit fullscreen mode

LLM API Preparation

Supported LLM Providers

RD-Agent supports multiple large language model providers through LiteLLM:

Provider Supported Models Recommended Use Cost Considerations
OpenAI GPT-4, GPT-4-turbo, GPT-3.5-turbo General purpose, high quality output $$$
Azure OpenAI GPT-4, GPT-3.5-turbo Enterprise applications, compliance requirements $$$
DeepSeek deepseek-chat, deepseek-coder Code generation, cost-effective $
Anthropic Claude-3.x Long text processing, analysis tasks $$
Google Gemini Pro Multimodal requirements $$

API Key Acquisition Guide

OpenAI API Key Acquisition:

  1. Visit OpenAI API Official Site
  2. Register/login to your account
  3. Go to "API Keys" page
  4. Click "Create new secret key"
  5. Copy and securely save the API key

Azure OpenAI Configuration:

  1. Login to Azure Portal
  2. Create Azure OpenAI resource
  3. Get API key, endpoint, and deployment name
  4. Record API version information

DeepSeek API Key Acquisition:

  1. Visit DeepSeek API Platform
  2. Register account and complete verification
  3. Go to API key management page
  4. Generate new API key

Cost Budget Recommendations

Usage Intensity Monthly Budget Applicable Scenarios
Learning & Trial $10-50 Tutorial learning, small-scale experiments
Medium Usage $50-200 Project development, medium-scale applications
Heavy Usage $200-1000 Production environment, large-scale applications
Enterprise $1000+ Enterprise deployment, continuous operation

1.3 Installation and Basic Configuration

Installation Method Selection

User Version Installation (Recommended)

For most users, installing directly via PyPI is the simplest approach:

# Create conda environment (recommended)
conda create -n rdagent python=3.10
conda activate rdagent

# Or use venv
python3.10 -m venv rdagent_env
source rdagent_env/bin/activate

# Install RD-Agent
pip install rdagent
Enter fullscreen mode Exit fullscreen mode

Developer Version Installation

If you want to experience the latest features or participate in development, install from source:

# Clone repository
git clone https://github.com/microsoft/RD-Agent.git
cd RD-Agent

# Create development environment
conda create -n rdagent-dev python=3.10
conda activate rdagent-dev

# Install development dependencies
make dev

# Or manual installation
pip install -e .
pip install -r requirements/dev.txt
Enter fullscreen mode Exit fullscreen mode

Dependency Management and Virtual Environments

Why do you need a virtual environment?

  • Avoid package version conflicts
  • Ensure environment consistency
  • Facilitate environment management and migration

Recommended environment management methods:

# Using conda (recommended)
conda create -n rdagent python=3.10
conda activate rdagent

# Or use pyenv + venv
pyenv install 3.10.12
pyenv local 3.10.12
python -m venv rdagent_env
source rdagent_env/bin/activate
Enter fullscreen mode Exit fullscreen mode

Basic Environment Configuration

.env File Configuration Details

RD-Agent uses .env files to manage environment variable configurations. Create a .env file in the project root directory:

# Create .env file in project directory
touch .env
Enter fullscreen mode Exit fullscreen mode

LiteLLM Unified Backend Configuration

Method 1: Unified API Basic Configuration (Recommended for Beginners)

# OpenAI configuration example
CHAT_MODEL=gpt-4o
EMBEDDING_MODEL=text-embedding-3-small
OPENAI_API_KEY=sk-your-openai-api-key-here
OPENAI_API_BASE=https://api.openai.com/v1
Enter fullscreen mode Exit fullscreen mode

Method 2: Separated API Configuration (Advanced Users)

# Chat model configuration
CHAT_MODEL=gpt-4o
OPENAI_API_KEY=sk-your-openai-api-key-here
OPENAI_API_BASE=https://api.openai.com/v1

# Embedding model configuration (using different provider)
EMBEDDING_MODEL=litellm_proxy/BAAI/bge-large-en-v1.5
LITELLM_PROXY_API_KEY=your-siliconflow-api-key
LITELLM_PROXY_API_BASE=https://api.siliconflow.cn/v1
Enter fullscreen mode Exit fullscreen mode

Multiple LLM Provider Configuration Examples

OpenAI Standard Configuration:

# Basic configuration
CHAT_MODEL=gpt-4o
EMBEDDING_MODEL=text-embedding-3-small
OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxxxxxxxxxxxx
OPENAI_API_BASE=https://api.openai.com/v1

# Optional: Special reasoning model configuration
# REASONING_THINK_RM=True  # Enable thinking process removal
Enter fullscreen mode Exit fullscreen mode

Azure OpenAI Configuration:

# Azure OpenAI configuration
CHAT_MODEL=azure/gpt-4o-deployment-name
EMBEDDING_MODEL=azure/embedding-deployment-name
AZURE_API_KEY=your-azure-api-key
AZURE_API_BASE=https://your-resource.openai.azure.com/
AZURE_API_VERSION=2024-02-15-preview
Enter fullscreen mode Exit fullscreen mode

DeepSeek Cost-Effective Configuration:

# DeepSeek chat model (cost-effective)
CHAT_MODEL=deepseek/deepseek-chat
DEEPSEEK_API_KEY=sk-your-deepseek-api-key

# SiliconFlow embedding model (DeepSeek has no embedding model)
EMBEDDING_MODEL=litellm_proxy/BAAI/bge-m3
LITELLM_PROXY_API_KEY=sk-your-siliconflow-api-key
LITELLM_PROXY_API_BASE=https://api.siliconflow.cn/v1

# Reasoning model configuration
REASONING_THINK_RM=True
Enter fullscreen mode Exit fullscreen mode

Mixed Configuration (Recommended for Advanced Users):

# High-performance chat model
CHAT_MODEL=gpt-4o
OPENAI_API_KEY=sk-your-openai-api-key

# Cost-effective embedding model
EMBEDDING_MODEL=litellm_proxy/BAAI/bge-large-en-v1.5
LITELLM_PROXY_API_KEY=sk-your-siliconflow-api-key
LITELLM_PROXY_API_BASE=https://api.siliconflow.cn/v1

# Other configuration
REASONING_THINK_RM=False
Enter fullscreen mode Exit fullscreen mode

Health Check and Verification

rdagent health_check Usage

After installation, perform a system health check first:

# Complete health check
rdagent health_check

# Skip environment variable check
rdagent health_check --no-check-env

# Skip Docker check
rdagent health_check --no-check-docker

# Only check port usage
rdagent health_check --no-check-env --no-check-docker
Enter fullscreen mode Exit fullscreen mode

Expected Successful Output:

βœ… Docker is installed and working correctly
βœ… Port 19899 is available
βœ… Environment variables are configured correctly
βœ… LLM API connection successful
βœ… All systems check passed!
Enter fullscreen mode Exit fullscreen mode

Common Configuration Issue Troubleshooting

Issue 1: Docker Permission Error

❌ Error: Got permission denied while trying to connect to the Docker daemon socket
Enter fullscreen mode Exit fullscreen mode

Solution:

# Ensure user is in docker group
sudo usermod -aG docker $USER
newgrp docker
# Re-run health check
rdagent health_check
Enter fullscreen mode Exit fullscreen mode

Issue 2: Invalid API Key

❌ Error: Invalid API key provided
Enter fullscreen mode Exit fullscreen mode

Solution:

# Check API key in .env file
cat .env | grep API_KEY
# Ensure key is correct and valid
# Reconfigure API key
Enter fullscreen mode Exit fullscreen mode

Issue 3: Port Already in Use

❌ Error: Port 19899 is already in use
Enter fullscreen mode Exit fullscreen mode

Solution:

# Check port usage
netstat -tlnp | grep 19899
# Kill occupying process or change port
rdagent ui --port 19900
Enter fullscreen mode Exit fullscreen mode

Issue 4: Network Connection Problem

❌ Error: Failed to connect to API endpoint
Enter fullscreen mode Exit fullscreen mode

Solution:

# Check network connectivity
curl -I https://api.openai.com/v1/models
# Configure proxy (if needed)
export https_proxy=http://proxy.company.com:8080
export http_proxy=http://proxy.company.com:8080
Enter fullscreen mode Exit fullscreen mode

Environment Verification Checklist

Before starting to use RD-Agent, please confirm the following checklist:

  • [ ] Operating System: Linux environment
  • [ ] Python Version: 3.10 or 3.11
  • [ ] Virtual Environment: Dedicated environment activated
  • [ ] Docker: Installed and can run without sudo
  • [ ] Network Connection: Can access LLM API endpoints
  • [ ] API Keys: Valid with sufficient balance
  • [ ] Storage Space: At least 10GB available space
  • [ ] Port: Port 19899 available (or other specified port)
  • [ ] Permissions: Current user has read/write permissions to project directory

You have now completed the basic installation and configuration of RD-Agent. The next chapter will detail the core functions and usage methods of RD-Agent.

Quick Verification of Installation

After completing all configurations, let's perform a quick functional verification:

# Activate environment
conda activate rdagent

# Verify installation
python -c "import rdagent; print('RD-Agent installed successfully!')"

# Run health check
rdagent health_check

# View available commands
rdagent --help
Enter fullscreen mode Exit fullscreen mode

If all steps complete successfully, you are now ready to start using the powerful features of RD-Agent!

Top comments (0)