Development Environment Setup

This guide covers setting up a complete development environment for AI agent projects, from Python installation to IDE configuration.

Prerequisites

Python Version

Most projects require Python 3.10 or higher. Some advanced projects require Python 3.11+.

Check Python Version

python --version
# or
python3 --version

Install Python

macOS
Ubuntu/Debian
Windows

# Using Homebrew
brew install [email protected]

# Verify installation
python3.11 --version

# Update package list
sudo apt update

# Install Python 3.11
sudo apt install python3.11 python3.11-venv python3.11-dev

# Verify installation
python3.11 --version

Download Python from python.org
Run installer
Important: Check “Add Python to PATH”
Verify in Command Prompt:

python --version

Virtual Environments

Always use virtual environments to isolate project dependencies.

Using venv (Built-in)

# Navigate to project directory
cd my-ai-agent

# Create virtual environment
python -m venv .venv

# Activate virtual environment
# On macOS/Linux:
source .venv/bin/activate

# On Windows:
.venv\Scripts\activate

# Verify activation (should show (.venv) prefix)
which python

Using uv (Faster Alternative)

uv is a fast Python package installer and resolver, used in many projects.

Install uv

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
irm https://astral.sh/uv/install.ps1 | iex

# Verify installation
uv --version

Create Virtual Environment with uv

# Create venv
uv venv

# Activate (same as above)
source .venv/bin/activate  # macOS/Linux
.venv\Scripts\activate     # Windows

Installing Dependencies

Projects use either requirements.txt or pyproject.toml for dependency management.

Projects with pyproject.toml

Most modern projects use pyproject.toml.

Using pip

# Install in editable mode
pip install -e .

# Or install from pyproject.toml
pip install .

Using uv (Recommended - Faster)

# Install dependencies
uv pip install -e .

# Install with specific Python version
uv pip install -e . --python python3.11

Projects with requirements.txt

# Using pip
pip install -r requirements.txt

# Using uv (faster)
uv pip install -r requirements.txt

Example pyproject.toml

From advance_ai_agents/deep_researcher_agent/pyproject.toml:

[project]
name = "deep-researcher-agent"
version = "0.1.0"
description = "Multi-stage research workflow agent"
requires-python = ">=3.10"
dependencies = [
    "agno",
    "openai",
    "scrapegraph-py",
    "python-dotenv",
    "mcp",
    "streamlit",
    "pydantic",
]

[project.urls]
Homepage = "https://github.com/Arindam200/awesome-ai-apps"
Repository = "https://github.com/Arindam200/awesome-ai-apps"

IDE Setup

VS Code (Recommended)

Install VS Code

Download from code.visualstudio.com

Essential Extensions

Install these extensions:

Python (ms-python.python)
- IntelliSense, linting, debugging
Pylance (ms-python.vscode-pylance)
- Fast type checking and auto-completion
Python Debugger (ms-python.debugpy)
- Debug Python code
Ruff (charliermarsh.ruff)
- Fast linting and formatting

Configure VS Code

Create .vscode/settings.json in project root:

{
  "python.defaultInterpreterPath": ".venv/bin/python",
  "python.terminal.activateEnvironment": true,
  "python.analysis.typeCheckingMode": "basic",
  "python.formatting.provider": "none",
  "[python]": {
    "editor.formatOnSave": true,
    "editor.defaultFormatter": "charliermarsh.ruff",
    "editor.codeActionsOnSave": {
      "source.organizeImports": true
    }
  },
  "ruff.lint.args": ["--line-length=100"],
  "files.exclude": {
    "**/.venv": true,
    "**/__pycache__": true,
    "**/*.pyc": true
  }
}

Launch Configuration

Create .vscode/launch.json for debugging:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Python: Current File",
      "type": "debugpy",
      "request": "launch",
      "program": "${file}",
      "console": "integratedTerminal",
      "envFile": "${workspaceFolder}/.env"
    },
    {
      "name": "Python: Main",
      "type": "debugpy",
      "request": "launch",
      "program": "main.py",
      "console": "integratedTerminal",
      "envFile": "${workspaceFolder}/.env"
    },
    {
      "name": "Streamlit App",
      "type": "debugpy",
      "request": "launch",
      "module": "streamlit",
      "args": ["run", "app.py"],
      "console": "integratedTerminal",
      "envFile": "${workspaceFolder}/.env"
    }
  ]
}

PyCharm

Configure Interpreter

Open project in PyCharm
Go to Settings > Project > Python Interpreter
Click gear icon > Add Interpreter > Existing
Select .venv/bin/python

Configure .env File

Install EnvFile plugin
Edit run configuration
Enable “EnvFile”
Add path to .env file

Common Tools

Git

Required for cloning repositories.

# Install Git
# macOS
brew install git

# Ubuntu/Debian
sudo apt install git

# Windows: Download from git-scm.com

# Configure Git
git config --global user.name "Your Name"
git config --global user.email "[email protected]"

Docker (Optional)

For running vector databases and services locally.

Install Docker Desktop

Download from docker.com

Run Qdrant Locally

docker run -p 6333:6333 qdrant/qdrant

Run PostgreSQL with pgvector

docker run -p 5432:5432 \
  -e POSTGRES_PASSWORD=password \
  -e POSTGRES_DB=vectordb \
  pgvector/pgvector:pg16

Node.js (For MCP Servers)

Required for MCP integrations.

# macOS
brew install node

# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Windows: Download from nodejs.org

# Verify installation
node --version
npm --version

Environment Variables

Create .env File

# Copy example file
cp .env.example .env

# Edit with your editor
nano .env
# or
code .env

Load Environment Variables

All projects use python-dotenv:

from dotenv import load_dotenv
import os

load_dotenv()  # Loads .env file

# Access variables
api_key = os.getenv("OPENAI_API_KEY")

Project Structure

Typical AI agent project structure:

my-ai-agent/
├── .env                    # API keys (never commit!)
├── .env.example            # Template (commit this)
├── .gitignore              # Git ignore rules
├── .venv/                  # Virtual environment
├── README.md               # Project documentation
├── pyproject.toml          # Dependencies and metadata
├── main.py                 # Main entry point
├── app.py                  # Streamlit app (if applicable)
├── src/                    # Source code
│   ├── __init__.py
│   ├── agents.py           # Agent definitions
│   ├── tools.py            # Custom tools
│   └── config.py           # Configuration
├── tests/                  # Unit tests
│   ├── __init__.py
│   └── test_agents.py
└── tmp/                    # Temporary files (gitignored)
    └── lancedb/            # Local vector database

Running Projects

Standard Python Script

# Activate virtual environment
source .venv/bin/activate

# Run main script
python main.py

Streamlit Applications

Many RAG and advanced agents use Streamlit:

# Run Streamlit app
streamlit run app.py

# Specify port
streamlit run app.py --server.port 8501

# Auto-reload on changes
streamlit run app.py --server.runOnSave true

FastAPI Services

Some agents expose REST APIs:

# Run with uvicorn
uvicorn main:app --reload

# Specify host and port
uvicorn main:app --host 0.0.0.0 --port 8000

Troubleshooting

ModuleNotFoundError

# Ensure virtual environment is activated
source .venv/bin/activate

# Reinstall dependencies
pip install -e .

ImportError: No module named ‘dotenv’

pip install python-dotenv

Permission Denied (macOS/Linux)

# Make script executable
chmod +x main.py

SSL Certificate Errors

# macOS: Install certificates
/Applications/Python\ 3.11/Install\ Certificates.command

Port Already in Use

# Find process using port 8501
lsof -i :8501

# Kill process
kill -9 <PID>

# Or use different port
streamlit run app.py --server.port 8502

Quick Start Checklist

Python 3.10+ installed
Virtual environment created and activated
Dependencies installed (pip install -e .)
.env file created with API keys
IDE configured with Python interpreter
Git configured
Docker installed (if using vector databases)
Node.js installed (if using MCP)
Project runs successfully (python main.py)

Next Steps

API Keys

Configure API keys for AI models and services

Dependency Management

Learn pip, uv, and pyproject.toml

Best Practices

Production-ready patterns and code quality

Multi-Agent Patterns

Start building multi-agent systems

Frameworks

Patterns

Development

​Prerequisites

​Python Version

​Check Python Version

​Install Python

​Virtual Environments

​Using venv (Built-in)

​Using uv (Faster Alternative)

​Install uv

​Create Virtual Environment with uv

​Installing Dependencies

​Projects with pyproject.toml

​Using pip

​Using uv (Recommended - Faster)

​Projects with requirements.txt

​Example pyproject.toml

​IDE Setup

​VS Code (Recommended)

​Install VS Code

​Essential Extensions

​Configure VS Code

​Launch Configuration

​PyCharm

​Configure Interpreter

​Configure .env File

​Common Tools

​Git

​Docker (Optional)

​Install Docker Desktop

​Run Qdrant Locally

​Run PostgreSQL with pgvector

​Node.js (For MCP Servers)

​Environment Variables

​Create .env File

​Load Environment Variables

​Project Structure

​Running Projects

​Standard Python Script

​Streamlit Applications

​FastAPI Services

​Troubleshooting

​ModuleNotFoundError

​ImportError: No module named ‘dotenv’

​Permission Denied (macOS/Linux)

​SSL Certificate Errors

​Port Already in Use

​Quick Start Checklist

​Next Steps