Workflow:HKUDS AI Trader End to End US Stock Trading
| Knowledge Sources | |
|---|---|
| Domains | LLM_Ops, Algorithmic_Trading, Autonomous_Agents |
| Last Updated | 2026-02-09 14:00 GMT |
Overview
End-to-end process for running an LLM-powered autonomous trading agent that backtests US stock (NASDAQ-100) trading strategies using the Model Context Protocol (MCP) tool framework.
Description
This workflow orchestrates the complete AI-Trader pipeline for US equities. It covers three sequential phases: fetching historical OHLCV price data from Alpha Vantage for all NASDAQ-100 constituents, merging individual stock JSON files into a unified JSONL format consumable by the trading agent, and then launching the LLM-based trading agent that uses MCP tool servers to look up prices, execute simulated trades, and manage portfolio positions over a configurable date range. The agent iterates day-by-day through the backtesting window, making autonomous buy/sell decisions via an LLM reasoning loop with tool calls.
Usage
Execute this workflow when you want to run a full backtest of an LLM trading agent on US stocks. You need an Alpha Vantage API key for data fetching, an OpenAI-compatible LLM API endpoint, and a JSON configuration file specifying the model, date range, and agent parameters. The output is a position log (JSONL) and conversation logs for each trading day.
Execution Steps
Step 1: Fetch Price Data
Download daily or intraday OHLCV price data from the Alpha Vantage API for all NASDAQ-100 constituent symbols plus the QQQ index ETF. Each symbol's data is saved as an individual JSON file in the data directory. The fetcher handles API rate limits and stores raw time series responses.
Key considerations:
- Requires a valid Alpha Vantage API key set as an environment variable
- Rate-limited API; fetching all 100+ symbols may require batching
- Supports both daily and intraday (hourly) intervals depending on the fetch script used
Step 2: Merge Price Data into JSONL
Transform individual per-symbol JSON files into a single merged JSONL file. During merging, the script renames price fields (open becomes buy price, close becomes sell price) and masks the latest day's sell price to prevent look-ahead bias. Only symbols matching the NASDAQ-100 constituent list are included.
Key considerations:
- Field renaming enforces the buy/sell price abstraction used by the agent
- The latest date entry retains only the buy price, preventing future data leakage
- The merged.jsonl file is the sole data source consumed by the MCP price lookup tool
Step 3: Start MCP Tool Servers
Launch all MCP (Model Context Protocol) tool servers that the trading agent depends on. The service manager starts five HTTP-based tool servers: Math operations, local price lookup, news/search, stock trade execution, and crypto trade execution. Each server runs on a configurable port and exposes tools via the Streamable HTTP MCP transport.
Key considerations:
- All services must be running before the agent starts
- Port conflicts are automatically detected with optional auto-reassignment
- The price lookup tool reads from the merged JSONL and masks future dates based on the simulation's current date
Step 4: Configure and Launch Trading Agent
Load the JSON configuration file that specifies the LLM model, date range, initial cash, and agent behavior parameters. The CLI entry point dynamically selects the correct agent class (BaseAgent for US stocks), validates dates, and initializes the agent with MCP client connections and the LLM model.
Key considerations:
- Configuration supports multiple models; only enabled models are executed
- Agent type is auto-detected from config (BaseAgent, BaseAgent_Hour, BaseAgentAStock, BaseAgentCrypto)
- OpenAI-compatible API endpoint and key must be configured (via config or environment variables)
- Special handling exists for DeepSeek models which return tool call arguments as JSON strings
Step 5: Execute Daily Trading Loop
For each trading day in the date range, the agent runs a multi-step reasoning loop. It receives a system prompt containing current positions, yesterday's closing prices, and today's buy prices, then iteratively calls MCP tools (price lookup, news search, buy/sell operations, math) until it emits a finish signal or reaches the maximum step limit. Each day's conversation and tool interactions are logged to JSONL files.
Key considerations:
- The agent registers initial positions (all-cash portfolio) on first run
- Weekend and holiday dates are automatically skipped using trading calendar data
- Each trading day session is independent with fresh conversation context
- A no-trade record is written if the agent decides not to execute any trades
- Retry logic handles transient LLM API failures with exponential backoff
Step 6: Review Results
After all trading days are processed, the agent outputs a final position summary showing cash balance and stock holdings. Position history is stored in a JSONL file that can be used by the metrics calculator to compute performance statistics (Cumulative Return, Sortino Ratio, Volatility, Maximum Drawdown) or visualized through the built-in web dashboard.
Key considerations:
- Position files persist across runs, enabling resume from the last processed date
- The web dashboard (MkDocs-based) can serve results locally for interactive exploration
- Performance metrics require both position data and price data for portfolio valuation