---
id: "RF-LLM-005"
title: "Integración de Herramientas (Tools)"
type: "Requirement"
status: "Done"
priority: "Alta"
epic: "OQI-007"
project: "trading-platform"
version: "1.0.0"
created_date: "2025-12-05"
updated_date: "2026-01-04"
---

# RF-LLM-005: Integración de Herramientas (Tools)

**Épica:** OQI-007 - LLM Strategy Agent
**Versión:** 1.0
**Fecha:** 2025-12-05
**Estado:** Planificado
**Prioridad:** P0 - Crítico

---

## Descripción

El agente LLM debe poder ejecutar herramientas (tools) para obtener información en tiempo real, realizar cálculos y ejecutar acciones en la plataforma. Las herramientas permiten al agente interactuar con sistemas externos y proporcionar respuestas precisas basadas en datos actuales.

---

## Requisitos Funcionales

### RF-LLM-005.1: Herramienta de Market Data
- El agente debe consultar precio actual de cualquier símbolo
- El agente debe obtener OHLCV de múltiples timeframes
- El agente debe consultar indicadores técnicos calculados
- El agente debe obtener datos históricos para análisis
- El agente debe manejar símbolos de stocks y crypto

### RF-LLM-005.2: Herramienta de Portfolio
- El agente debe consultar posiciones actuales del usuario
- El agente debe obtener P&L de posiciones
- El agente debe consultar historial de trades
- El agente debe calcular métricas de portfolio
- El agente debe verificar capital disponible

### RF-LLM-005.3: Herramienta de Noticias
- El agente debe buscar noticias relevantes por símbolo
- El agente debe obtener sentiment de noticias
- El agente debe filtrar noticias por fecha
- El agente debe identificar noticias de impacto alto

### RF-LLM-005.4: Herramienta de ML Signals
- El agente debe consultar predicciones del ML Engine
- El agente debe obtener nivel de confianza de predicciones
- El agente debe acceder a features usados en predicción
- El agente debe obtener histórico de precisión del modelo

### RF-LLM-005.5: Herramienta de Paper Trading
- El agente debe poder crear órdenes de paper trading
- El agente debe consultar órdenes pendientes
- El agente debe cancelar órdenes si el usuario lo solicita
- El agente debe calcular impacto de orden propuesta

### RF-LLM-005.6: Herramienta de Alerts
- El agente debe crear alertas de precio
- El agente debe listar alertas activas
- El agente debe modificar/eliminar alertas
- El agente debe configurar alertas de indicadores

### RF-LLM-005.7: Herramienta de Cálculos
- El agente debe calcular position sizing
- El agente debe calcular risk/reward ratios
- El agente debe convertir monedas
- El agente debe calcular correlaciones entre activos

### RF-LLM-005.8: Herramienta de Watchlist
- El agente debe agregar símbolos a watchlist
- El agente debe consultar watchlist actual
- El agente debe remover símbolos de watchlist
- El agente debe obtener resumen de watchlist

---

## Criterios de Aceptación

```gherkin
Feature: Integración de Herramientas

Scenario: Consultar precio actual
  Given el usuario pregunta "¿Cuál es el precio de BTC?"
  When el agente usa la herramienta get_price
  Then obtiene precio actualizado (max 15 seg delay)
  And responde con precio formateado
  And incluye cambio porcentual 24h

Scenario: Crear orden de paper trading
  Given soy usuario Premium
  And tengo paper trading habilitado
  When digo "Compra 10 acciones de AAPL"
  Then el agente usa herramienta create_paper_order
  And confirma los parámetros antes de ejecutar
  And muestra orden creada

Scenario: Consultar señales ML
  Given soy usuario Pro
  When pregunto "¿Qué dice el ML sobre TSLA?"
  Then el agente usa herramienta get_ml_signals
  And muestra predicción con confianza
  And explica los features principales

Scenario: Crear alerta de precio
  Given digo "Avísame cuando AAPL llegue a $190"
  When el agente procesa la solicitud
  Then usa herramienta create_alert
  And confirma alerta creada
  And muestra listado de alertas activas

Scenario: Herramienta no disponible por plan
  Given soy usuario Free
  When digo "Crea una orden de paper trading"
  Then el agente detecta herramienta restringida
  And informa que requiere plan Pro
  And sugiere upgrade
```

---

## Reglas de Negocio

| Regla | Descripción |
|-------|-------------|
| RN-001 | Confirmar antes de ejecutar acciones (órdenes, alertas) |
| RN-002 | Paper trading solo para Pro/Premium |
| RN-003 | ML signals solo para Pro/Premium |
| RN-004 | Máximo 10 herramienta-calls por mensaje |
| RN-005 | Cache de market data: 5 segundos |
| RN-006 | No ejecutar trades reales (solo paper) |
| RN-007 | Logging de todas las herramientas ejecutadas |

---

## Catálogo de Herramientas

### Herramientas de Lectura (Todos los planes)

| Tool ID | Nombre | Descripción | Rate Limit |
|---------|--------|-------------|------------|
| T-001 | `get_price` | Obtener precio actual | 60/min |
| T-002 | `get_ohlcv` | Obtener velas OHLCV | 30/min |
| T-003 | `get_indicators` | Obtener indicadores técnicos | 30/min |
| T-004 | `get_news` | Buscar noticias por símbolo | 10/min |
| T-005 | `get_watchlist` | Obtener watchlist del usuario | 60/min |
| T-006 | `calculate` | Cálculos financieros | 100/min |

### Herramientas Pro (Pro/Premium)

| Tool ID | Nombre | Descripción | Rate Limit |
|---------|--------|-------------|------------|
| T-007 | `get_ml_signals` | Obtener señales ML | 30/min |
| T-008 | `get_portfolio` | Obtener portfolio actual | 30/min |
| T-009 | `create_paper_order` | Crear orden paper trading | 10/min |
| T-010 | `cancel_paper_order` | Cancelar orden | 20/min |
| T-011 | `create_alert` | Crear alerta de precio | 20/min |
| T-012 | `manage_alerts` | Listar/modificar alertas | 30/min |

### Herramientas Premium

| Tool ID | Nombre | Descripción | Rate Limit |
|---------|--------|-------------|------------|
| T-013 | `backtest_strategy` | Ejecutar backtest | 5/min |
| T-014 | `get_correlations` | Análisis de correlaciones | 10/min |
| T-015 | `portfolio_analysis` | Análisis avanzado portfolio | 10/min |
| T-016 | `export_data` | Exportar datos a CSV | 5/min |

---

## Esquema de Tool Calls

```yaml
# Ejemplo: get_price
tool_call:
  name: "get_price"
  parameters:
    symbol: "AAPL"

tool_response:
  success: true
  data:
    symbol: "AAPL"
    price: 185.50
    change_24h: 2.35
    change_percent: 1.28
    volume: 45000000
    timestamp: "2025-12-05T15:30:00Z"

# Ejemplo: create_paper_order
tool_call:
  name: "create_paper_order"
  parameters:
    symbol: "AAPL"
    side: "buy"
    quantity: 10
    order_type: "market"

tool_response:
  success: true
  data:
    order_id: "paper-12345"
    status: "pending_confirmation"
    estimated_cost: 1855.00
    message: "Confirma la orden: Comprar 10 AAPL a mercado (~$1,855)"
```

---

## Flujo de Ejecución de Tools

```
┌─────────────────────────────────────────────────────────────┐
│ 1. Usuario envía mensaje                                     │
│    "Compra 5 TSLA si el precio baja a $240"                 │
└──────────────────────────┬──────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────────┐
│ 2. LLM analiza intent                                        │
│    - Acción: crear alerta + orden condicional                │
│    - Tools necesarios: get_price, create_alert               │
└──────────────────────────┬──────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────────┐
│ 3. Verificar permisos                                        │
│    - ¿Usuario tiene plan Pro? ✓                              │
│    - ¿Rate limit OK? ✓                                       │
└──────────────────────────┬──────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────────┐
│ 4. Ejecutar tool: get_price("TSLA")                         │
│    Response: { price: 245.30, ... }                          │
└──────────────────────────┬──────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────────┐
│ 5. Ejecutar tool: create_alert                               │
│    { symbol: "TSLA", condition: "<=", price: 240 }          │
└──────────────────────────┬──────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────────┐
│ 6. LLM genera respuesta con resultados                       │
│    "He creado una alerta para TSLA a $240..."               │
└─────────────────────────────────────────────────────────────┘
```

---

## Dependencias

### Épicas Requeridas
- **OQI-001:** Autenticación (verificar plan del usuario)
- **OQI-003:** Market data y paper trading
- **OQI-006:** ML Signals

### Servicios Internos
- MarketDataService
- PaperTradingService
- AlertService
- MLSignalService
- PortfolioService

---

## Especificaciones Técnicas Relacionadas

- [ET-LLM-005: Arquitectura de Tools](../especificaciones/ET-LLM-005-arquitectura-tools.md)
- [ET-LLM-006: Rate Limiting y Seguridad](../especificaciones/ET-LLM-006-seguridad.md)

---

## Historias de Usuario Relacionadas

- US-LLM-009: Consultar datos de mercado vía chat
- US-LLM-010: Crear órdenes de paper trading vía chat

---

*Documento de requerimientos - Sistema NEXUS*
*Trading Platform*