Entorn de Desenvolupament

Objectiu

Configurar un entorn de treball complet, reproducible i professional per al curs d'Agents d'IA. Usarem Python 3.11+, entorns virtuals i gestió de secrets segura.

---

🖥️ Requisits de Sistema

💻

Sistema Operatiu

Linux (recomanat), macOS o Windows 11 amb WSL2. Les instruccions cobreixen els tres sistemes.

🐍

Python 3.11+

Obligatori. LangChain 0.3 requereix Python ≥3.9, però recomanem 3.11 per a millor rendiment.

💾

Maquinari Mínim

8 GB RAM (16 GB recomanat), 20 GB d'espai en disc, connexió a internet. GPU no necessària (usem APIs).

🔑

Claus d'API

Compte a OpenAI (mínim pla de pagament) i/o Anthropic per a les pràctiques. Cost estimat del curs: ~5-10€.

---

🐍 Instal·lació de Python

Linux (Ubuntu/Debian)macOSWindows (WSL2)Windows (natiu)

# Actualitzar el sistema
sudo apt update && sudo apt upgrade -y

# Instal·lar Python 3.11 i eines bàsiques
sudo apt install python3.11 python3.11-venv python3-pip git -y

# Verificar versió
python3.11 --version   # → Python 3.11.x
pip3 --version         # → pip 23.x.x

# Instalar Homebrew si no el tens
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Instal·lar Python
brew install python@3.11

# Verificar
python3 --version

# Habilitar WSL2 (PowerShell com administrador)
wsl --install
# Reiniciar i configurar Ubuntu

# Des de dins de WSL2, seguir instruccions de Linux

# Descarregar Python 3.11 de https://python.org/downloads/
# IMPORTANT: marcar "Add Python to PATH" durant la instal·lació

# Verificar
python --version     # → Python 3.11.x
pip --version

---

📦 Estructura de Projecte Recomanada

Per a tot el curs, usarem aquesta estructura:

agents-ia-curs/               ← Carpeta arrel del curs
├── .env                       ← Claus d'API (mai al git!)
├── .gitignore
├── requirements.txt           ← Dependències globals
│
├── practica1-primer-agent/    ← Una carpeta per pràctica
│   ├── .venv/                 ← Entorn virtual de la pràctica
│   ├── requirements.txt
│   └── *.py
│
├── practica2-rag/
│   ├── .venv/
│   ├── data/                  ← Documents per indexar
│   ├── chroma_db/             ← Vector store (generat)
│   └── *.py
│
└── projecte-final/
    ├── .venv/
    ├── src/
    ├── tests/
    └── README.md

---

🔧 Configuració de l'Entorn per Pràctica

# Per a cada pràctica, crear un entorn virtual propi
cd practica1-primer-agent
python3.11 -m venv .venv

# Activar (Linux/macOS)
source .venv/bin/activate

# Activar (Windows CMD)
.venv\Scripts\activate.bat

# Activar (Windows PowerShell)
.venv\Scripts\Activate.ps1

# El prompt canviarà a: (.venv) $

---

📋 requirements.txt del Curs

Crea un fitxer requirements.txt base per a totes les pràctiques:

# ══════════════════════════════════════════
# AGENTS D'IA — Requirements Base del Curs
# Versions testades i compatibles entre si
# ══════════════════════════════════════════

# ── Core LangChain ─────────────────────────
langchain==0.3.7
langchain-core==0.3.19
langchain-openai==0.2.6
langchain-community==0.3.7
langchain-anthropic==0.3.1   # Per usar Claude com a alternativa
langgraph==0.2.42             # Per a agents i fluxos complexos

# ── LlamaIndex ─────────────────────────────
llama-index==0.11.23
llama-index-llms-openai==0.3.9
llama-index-embeddings-openai==0.3.1

# ── LLMs i Embeddings ──────────────────────
openai==1.57.0                # Client oficial OpenAI
anthropic==0.40.0             # Client oficial Anthropic (Claude)
tiktoken==0.8.0               # Comptador de tokens

# ── Vector Stores ───────────────────────────
chromadb==0.5.23              # Vector store local (per a pràctiques)
faiss-cpu==1.9.0              # Vector store optimitzat (opcional)

# ── Document Loaders ────────────────────────
pypdf==5.1.0                  # Llegir PDFs
python-docx==1.1.2            # Llegir .docx
unstructured==0.16.11         # Loader universal (HTML, MD, etc.)
beautifulsoup4==4.12.3        # Scraping web
requests==2.32.3              # HTTP requests

# ── Eines per a Agents ──────────────────────
duckduckgo-search==6.3.7      # Cerca web gratuïta
wikipedia==1.4.0              # Cerca a Wikipedia
python-dotenv==1.0.1          # Gestió de .env

# ── Observabilitat ──────────────────────────
# langsmith                   # Opcional: traçar agents (compte gratuït)

# ── Utilitats ───────────────────────────────
pydantic==2.10.3              # Validació de dades
rich==13.9.4                  # Output bonic al terminal
python-dateutil==2.9.0

# ── Testing ─────────────────────────────────
pytest==8.3.4
pytest-asyncio==0.24.0

# Instal·lar totes les dependències
pip install -r requirements.txt

# Verificar instal·lació
python -c "import langchain; import llama_index; print('✅ Tot instal·lat!')"

---

🔑 Gestió de Claus d'API

Crear el fitxer .env

# Crear el fitxer (mai pujar a git!)
cat > .env << 'EOF'
# ═══════════════════════════════════════════════
# CLAUS D'API — NO PUJAR MAI A GIT!
# ═══════════════════════════════════════════════

# OpenAI (obligatori per a la majoria de pràctiques)
# Obtenir a: https://platform.openai.com/api-keys
OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxxxxxx

# Anthropic / Claude (opcional, per a pràctiques alternatives)
# Obtenir a: https://console.anthropic.com/
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxx

# LangSmith (opcional, per a observabilitat)
# Obtenir a: https://smith.langchain.com/
LANGCHAIN_API_KEY=ls__xxxxxxxxxxxxxxxxxxxx
LANGCHAIN_TRACING_V2=true
LANGCHAIN_PROJECT=curs-agents-ia

# Configuració general
LANGCHAIN_VERBOSE=false   # Canviar a true per debugging
EOF

Crear .gitignore

cat > .gitignore << 'EOF'
# Secrets
.env
.env.local
*.key

# Entorns virtuals
.venv/
venv/
env/

# Python
__pycache__/
*.pyc
*.pyo
*.pyd
.Python
*.egg-info/
dist/
build/

# Vector stores (grans, es generen localment)
chroma_db/
faiss_index/
*.pkl

# IDE
.vscode/
.idea/
*.swp

# Jupyter
.ipynb_checkpoints/
*.ipynb

# macOS
.DS_Store

# Logs
*.log
EOF

Llegir les claus al codi

import os
from dotenv import load_dotenv

# Carregar el fitxer .env
load_dotenv()

# Obtenir les claus
openai_key = os.getenv("OPENAI_API_KEY")
anthropic_key = os.getenv("ANTHROPIC_API_KEY")

# Verificació (bon hàbit al inici de cada script)
def verificar_entorn():
    """Verifica que les claus necessàries estan configurades."""
    required = ["OPENAI_API_KEY"]
    missing = [k for k in required if not os.getenv(k)]

    if missing:
        raise EnvironmentError(
            f"❌ Variables d'entorn no trobades: {missing}\n"
            f"   Crea el fitxer .env amb les claus necessàries."
        )

    print("✅ Entorn configurat correctament")
    print(f"   OpenAI: {'✓' if os.getenv('OPENAI_API_KEY') else '✗'}")
    print(f"   Anthropic: {'✓' if os.getenv('ANTHROPIC_API_KEY') else '✗'}")
    print(f"   LangSmith: {'✓' if os.getenv('LANGCHAIN_API_KEY') else '✗'}")

verificar_entorn()

---

💰 Estimació de Costos

Control de costos

Les APIs d'OpenAI i Anthropic cobren per token. Configura límits de despesa al dashboard.

Activitat	Model Recomanat	Cost Aproximat
Pràctica 1 — Agent bàsic	gpt-4o-mini	~0.10€
Pràctica 2 — RAG (indexació)	text-embedding-3-small	~0.05€
Pràctica 2 — RAG (queries)	gpt-4o-mini	~0.20€
Pràctica 3 — Multi-tool	gpt-4o-mini	~0.30€
Pràctica 4 — Multi-agent	gpt-4o	~0.50€
Projecte Final	gpt-4o / Claude 3.5	~1-2€
TOTAL CURS ESTIMAT		~2-5€

Consells per minimitzar costos

1. Usa gpt-4o-mini per a proves i gpt-4o per a l'entrega final
2. Configura max_tokens=500 mentre desenvolupes
3. Usa temperature=0 per a respostes deterministes (evita reexecucions)
4. Configura un límit de despesa de 10€/mes al dashboard d'OpenAI

---

🛠️ VS Code — Extensions Recomanades

# Instal·lar extensions via línia de comandes
code --install-extension ms-python.python
code --install-extension ms-python.vscode-pylance
code --install-extension ms-python.black-formatter
code --install-extension ms-toolsai.jupyter
code --install-extension bradlc.vscode-tailwindcss
code --install-extension yzhang.markdown-all-in-one

settings.json recomanat

{
  "python.defaultInterpreterPath": "./.venv/bin/python",
  "python.formatting.provider": "black",
  "editor.formatOnSave": true,
  "python.linting.enabled": true,
  "python.linting.pylintEnabled": false,
  "python.linting.flake8Enabled": true,
  "files.exclude": {
    "**/__pycache__": true,
    "**/.venv": true,
    "**/chroma_db": true
  }
}

---

✅ Verificació Final de l'Entorn

Executa aquest script per verificar que tot està correctament configurat:

#!/usr/bin/env python3
"""
Script de verificació de l'entorn del curs d'Agents d'IA
Executa: python verificar_entorn.py
"""

import sys
import os

print("=" * 50)
print("🔍 VERIFICACIÓ DE L'ENTORN — Curs Agents d'IA")
print("=" * 50)

# 1. Versió de Python
version = sys.version_info
status = "✅" if version >= (3, 11) else "❌"
print(f"\n{status} Python {version.major}.{version.minor}.{version.micro}")
if version < (3, 11):
    print("   ⚠️  Es requereix Python 3.11 o superior")

# 2. Dependències
deps = {
    "langchain": "0.3.0",
    "langchain_openai": "0.2.0",
    "langgraph": "0.2.0",
    "llama_index": "0.11.0",
    "openai": "1.50.0",
    "chromadb": "0.5.0",
    "dotenv": None,
}

print("\n📦 Dependències:")
for package, min_version in deps.items():
    try:
        mod = __import__(package)
        ver = getattr(mod, "__version__", "desconeguda")
        print(f"   ✅ {package} ({ver})")
    except ImportError:
        print(f"   ❌ {package} — NO INSTAL·LAT")
        print(f"      Executa: pip install {package.replace('_', '-')}")

# 3. Variables d'entorn
from dotenv import load_dotenv
load_dotenv()

print("\n🔑 Claus d'API:")
keys = {
    "OPENAI_API_KEY": "OpenAI (obligatori)",
    "ANTHROPIC_API_KEY": "Anthropic/Claude (opcional)",
    "LANGCHAIN_API_KEY": "LangSmith (opcional)",
}
for key, desc in keys.items():
    value = os.getenv(key)
    if value:
        masked = value[:8] + "..." + value[-4:]
        print(f"   ✅ {desc}: {masked}")
    else:
        icon = "❌" if "obligatori" in desc else "⚠️ "
        print(f"   {icon} {desc}: NO CONFIGURAT")

# 4. Test de connexió (opcional)
print("\n🌐 Test de connexió OpenAI:")
try:
    from openai import OpenAI
    client = OpenAI()
    # Crida mínima per verificar connexió
    models = client.models.list()
    print(f"   ✅ Connexió OK — {len(list(models))} models disponibles")
except Exception as e:
    print(f"   ❌ Error de connexió: {e}")

print("\n" + "=" * 50)
print("✅ Verificació completada!")
print("=" * 50)