CubeLabs

1. Qué es TradingAgents y por qué importa

TradingAgents es un framework open-source (Apache-2.0, ~104.000 estrellas en GitHub) que construye un equipo de analistas de IA capaz de evaluar un activo y emitir una decisión de compra, venta o mantenimiento. No es un bot de trading con reglas fijas: es un sistema donde varios agentes LLM especializados debaten entre sí antes de decidir.

La idea nace de un paper académico (arXiv:2412.20138) y su lema es simple: si una firma de inversión real separa el trabajo en analistas, investigadores, traders y gestores de riesgo, ¿por qué no replicar esa estructura con agentes conversacionales?

Qué lo hace distinto

• Roles, no prompts sueltos. Cada agente tiene una función, un conjunto de herramientas y un objetivo propio.
• Debate estructurado. Un investigador alcista y otro bajista confrontan tesis; el riesgo también se discute desde tres perfiles.
• Trazabilidad. Todo el razonamiento queda en un reporte final y en un registro de decisiones persistente.
• Multi-proveedor. Funciona con OpenAI, Anthropic, Google, DeepSeek, Qwen, GLM, MiniMax, OpenRouter o modelos locales vía Ollama.

2. La arquitectura: un grafo con roles de firma real

TradingAgents no es una cadena lineal de prompts: es un grafo dirigido donde cada nodo es un agente (o un grupo de agentes) y las aristas deciden qué se ejecuta después. El recorrido de una análisis es siempre el mismo:

Los cuatro analistas, uno a uno

• Fundamental Analyst: valora los estados financieros, métricas de rendimiento y posibles banderas rojas del negocio.
• Sentiment Analyst: agrega titulares, StockTwits y conversación de Reddit en una única lectura de ánimo del mercado a corto plazo.
• News Analyst: rastrea noticias globales e indicadores macro y traduce su impacto al activo concreto.
• Technical Analyst: usa indicadores clásicos (MACD, RSI) para detectar patrones y proyectar movimientos de precio.

Mapa del repositorio

TradingAgents/
├── main.py                    # script mínimo de ejemplo
├── cli/                       # interfaz de terminal (Typer + Rich)
├── tradingagents/
│   ├── default_config.py      # TODA la configuración
│   ├── agents/
│   │   ├── analysts/          # fundamental, market, news, sentiment, social
│   │   ├── researchers/       # bull_researcher, bear_researcher
│   │   ├── managers/          # research_manager, portfolio_manager
│   │   ├── risk_mgmt/         # aggressive, conservative, neutral debators
│   │   └── trader/            # trader.py
│   ├── dataflows/             # yfinance, alpha_vantage, fred, polymarket, reddit
│   ├── graph/                 # trading_graph.py, propagation, reflection, checkpointer
│   └── llm_clients/           # adaptadores por proveedor
└── tests/

Cada carpeta que ves ahí corresponde a un rol del organigrama. Cuando la ejecución avanza, lo hace nodo a nodo siguiendo ese grafo.

3. Instalación paso a paso

Necesitas Python 3.10 o superior. El proyecto recomienda crear un entorno dedicado para no ensuciar tu instalación global.

git clone https://github.com/TauricResearch/TradingAgents.git
cd TradingAgents

conda create -n tradingagents python=3.12
conda activate tradingagents

pip install .

cp .env.example .env
# edita .env y pon tu clave (por ejemplo DEEPSEEK_API_KEY)

Verifica que funciona

tradingagents --help

Si aparece la ayuda del CLI, el motor está listo. La primera ejecución real descargará datos de mercado, así que necesitarás conexión a internet.

4. Elegir y configurar tu proveedor LLM

El motor es agnóstico del modelo. Todo se controla con variables de entorno en el fichero .env, y el framework distingue entre un modelo de razonamiento profundo (deep_think_llm) y otro rápido y barato (quick_think_llm).

Ejemplo de .env mínimo

DEEPSEEK_API_KEY=sk-...
TRADINGAGENTS_LLM_PROVIDER=deepseek
TRADINGAGENTS_DEEP_THINK_LLM=deepseek-reasoner
TRADINGAGENTS_QUICK_THINK_LLM=deepseek-chat
TRADINGAGENTS_OUTPUT_LANGUAGE=Spanish

Las variables que empiezan por TRADINGAGENTS_ sobrescriben la configuración por defecto sin tocar código. Los valores se convierten al tipo del valor original: un true sigue siendo booleano, un 3 sigue siendo entero.

5. El CLI interactivo: tu primera operación

La forma más directa de usar TradingAgents es su interfaz de terminal, construida con Typer para los comandos y Rich para el renderizado en vivo.

tradingagents          # comando instalado
python -m cli.main     # alternativa: desde el código fuente

Al arrancar verás una pantalla donde eliges ticker, fecha de análisis, proveedor LLM, modelos y profundidad de investigación. Después, el CLI va mostrando los informes a medida que se generan, con el estado de cada agente y el consumo de tokens en tiempo real.

Mercados y tickers soportados

Funciona con cualquier mercado que cubra Yahoo Finance, usando el sufijo del exchange:

El subcomando analyze

El CLI expone un comando analyze con dos opciones de control de estado:

tradingagents analyze --checkpoint           # activa la recuperación tras fallo
tradingagents analyze --clear-checkpoints    # borra checkpoints y empieza limpio

6. Uso como librería: TradingAgentsGraph

El CLI es cómodo para explorar, pero el verdadero poder está en programar con el framework. Todo gira en torno a la clase TradingAgentsGraph y su método propagate().

Ejemplo mínimo

from tradingagents.graph.trading_graph import TradingAgentsGraph
from tradingagents.default_config import DEFAULT_CONFIG

ta = TradingAgentsGraph(debug=True, config=DEFAULT_CONFIG.copy())

# forward propagate
_, decision = ta.propagate("NVDA", "2026-01-15")
print(decision)

propagate() devuelve dos cosas: el estado final del grafo (todos los informes intermedios, debates y razonamientos) y la decisión sintetizada. El estado es oro puro si quieres auditar por qué el sistema llegó a una conclusión.

Con configuración personalizada

config = DEFAULT_CONFIG.copy()
config["llm_provider"] = "deepseek"
config["deep_think_llm"] = "deepseek-reasoner"   # razonamiento complejo
config["quick_think_llm"] = "deepseek-chat"      # tareas rápidas
config["max_debate_rounds"] = 2                  # más confrontación bull/bear

ta = TradingAgentsGraph(debug=True, config=config)
_, decision = ta.propagate("NVDA", "2026-01-15")
print(decision)

El flujo interno, paso a paso

7. La configuración completa (DEFAULT_CONFIG)

tradingagents/default_config.py es la única fuente de verdad de la configuración. Cada clave puede sobrescribirse desde el código o desde una variable de entorno.

Rutas de trabajo

Por defecto el framework crea una carpeta ~/.tradingagents/ con tres subcarpetas:

~/.tradingagents/
├── logs/      # informes de resultados  (TRADINGAGENTS_RESULTS_DIR)
├── cache/     # caché de datos y checkpoints SQLite (TRADINGAGENTS_CACHE_DIR)
└── memory/    # trading_memory.md — el registro de decisiones

8. Fuentes de datos, mercados y benchmark

Los agentes no inventan cifras: cada afirmación numérica se apoya en un proveedor de datos configurable. La configuración data_vendors define exactamente qué fuente sirve a cada categoría.

config["data_vendors"] = {
    "core_stock_apis":      "yfinance,alpha_vantage",  # fallback ordenado
    "technical_indicators": "yfinance",
    "fundamental_data":     "yfinance",
    "news_data":            "yfinance",
    "macro_data":           "fred",
    "prediction_markets":   "polymarket",
}

La cadena que escribes es la cadena exacta que se usa: el framework no redirige silenciosamente a proveedores que no has elegido. Si quieres tolerancia a fallos, lista varios separados por comas y el sistema intentará el siguiente cuando el primero falle.

Claves gratuitas que merece la pena añadir

• FRED (FRED_API_KEY): datos macro de la Reserva Federal — tipos, inflación, empleo. Clave gratuita en el sitio de FRED.
• Alpha Vantage (ALPHA_VANTAGE_API_KEY): alternativa para precios, fundamentales e indicadores técnicos.
• Polymarket: mercados de predicción, sin clave. Útil como termómetro de expectativas.

El benchmark y el alfa por región

Cuando el sistema evalúa su propio acierto, no mide el retorno bruto: mide el retorno frente a un índice de referencia. El mapa benchmark_map elige el índice automáticamente según el sufijo del ticker.

9. Memoria, checkpoint y reproducibilidad

Un sistema multiagente serio necesita recordar y sobrevivir a fallos. TradingAgents persiste dos tipos de estado.

El registro de decisiones (siempre activo)

Cada ejecución completada añade su decisión a ~/.tradingagents/memory/trading_memory.md. En el siguiente análisis del mismo ticker, el sistema:

• recupera el retorno real obtenido (bruto y alfa frente al índice);
• genera una reflexión de un párrafo sobre qué funcionó y qué no;
• inyecta las decisiones recientes del mismo ticker y lecciones de otros tickers en el prompt del gestor de cartera.

Es un bucle de aprendizaje ligero: no reentrena ningún modelo, pero arrastra experiencia entre ejecuciones. La ruta se puede cambiar con TRADINGAGENTS_MEMORY_LOG_PATH.

Checkpoint y reanudación

La recuperación es opt-in mediante --checkpoint. Con ella activa, LangGraph guarda estado tras cada nodo y un fallo no obliga a empezar de cero.

# CLI
tradingagents analyze --checkpoint

# Python
config = DEFAULT_CONFIG.copy()
config["checkpoint_enabled"] = True
ta = TradingAgentsGraph(config=config)

Las bases SQLite por ticker viven en ~/.tradingagents/cache/checkpoints/<TICKER>.db y se limpian solas al terminar con éxito. Para forzar un arranque limpio: tradingagents analyze --clear-checkpoints.

10. Límites, buenas prácticas y aviso

Llegados aquí sabes montar la firma completa. Ahora la parte que separa un experimento interesante de un malentendido peligroso.

Qué hace bien

• Estructurar el razonamiento: obligar a que varias perspectivas se contradigan antes de decidir.
• Ser auditable: cada informe, debate y decisión queda registrado.
• Ser portable: el mismo pipeline con un modelo local o con la API más potente del mercado.

Qué no hace

• No garantiza rentabilidad. El propio proyecto avisa de que los resultados de backtest dependen del modelo, la temperatura, el rango de fechas y la calidad de los datos.
• No elimina el riesgo de alucinación en los agentes, aunque la identidad de la empresa y las cifras de precio sí estén ancladas a datos verificados.
• No sustituye a un asesor financiero ni constituye asesoramiento de inversión.

Buenas prácticas al experimentar

Extensiones naturales

Con la base montada, los siguientes pasos son: añadir un analista propio en agents/analysts/, conectar un proveedor de datos distinto en dataflows/, o envolver propagate() en tu propio servicio para analizar una cartera entera de forma programada.