Lumibot: Backtestable AI Agents and Python Algorithmic Trading

Build deterministic trading strategies, AI trading agents, and AI trading teams for stocks, options, crypto, futures, forex, SEC filings, FRED macro data, technical indicators, and real brokers. Backtest, paper trade, or run live with the same Python code.

Lumibot is a Python framework for building deterministic strategies, AI trading teams, and hybrid trading systems that backtest, paper trade, and run live through real brokers.

Use normal Python for rules, indicators, schedules, position sizing, and risk controls. Add AI agents when you want a strategy to research market data, SEC filings, macro data, news, technical indicators, and account state before making a decision.

The same strategy lifecycle works from historical backtests to paper trading and live trading, so you can inspect behavior before connecting a real account.

Lumibot also supports AI trading agents inside the strategy lifecycle, including DuckDB-powered time-series analysis, external MCP tools, replayable agent runs, and trading permissions that keep research agents read-only.

Getting Started

After you have installed Lumibot on your computer, you can create a strategy and backtest it using free data available from Yahoo Finance, or use your own data. Here’s how to get started:

Step 1: Install Lumibot

Note

Ensure you have installed the latest version of Lumibot. Upgrade using the following command:

pip install lumibot --upgrade

Install the package on your computer:

pip install lumibot

Step 2: Create a Strategy for Backtesting

Here’s some code to get you started:

from datetime import datetime
from lumibot.backtesting import YahooDataBacktesting
from lumibot.strategies import Strategy

# A simple strategy that buys AAPL on the first day and holds it
class MyStrategy(Strategy):
    def on_trading_iteration(self):
        if self.first_iteration:
            aapl_price = self.get_last_price("AAPL")
            quantity = self.portfolio_value // aapl_price
            order = self.create_order("AAPL", quantity, "buy")
            self.submit_order(order)

# Pick the dates that you want to start and end your backtest
backtesting_start = datetime(2020, 11, 1)
backtesting_end = datetime(2020, 12, 31)

# Run the backtest
MyStrategy.backtest(
    YahooDataBacktesting,
    backtesting_start,
    backtesting_end,
)

Step 3: Take Your Bot Live

Once you have backtested your strategy and understand how it behaves on historical data, you can take your bot to paper trading or live trading. Notice how the strategy code is exactly the same. Here’s an example using Alpaca (you can create a free Paper Trading account here in minutes: https://alpaca.markets/).

from lumibot.brokers import Alpaca
from lumibot.strategies.strategy import Strategy
from lumibot.traders import Trader

ALPACA_CONFIG = {
     "API_KEY": "YOUR_ALPACA_API_KEY",
     "API_SECRET": "YOUR_ALPACA_SECRET",
     "PAPER": True  # Set to True for paper trading, False for live trading
 }

# A simple strategy that buys AAPL on the first day and holds it
class MyStrategy(Strategy):
   def on_trading_iteration(self):
      if self.first_iteration:
            aapl_price = self.get_last_price("AAPL")
            quantity = self.portfolio_value // aapl_price
            order = self.create_order("AAPL", quantity, "buy")
            self.submit_order(order)

trader = Trader()
broker = Alpaca(ALPACA_CONFIG)
strategy = MyStrategy(broker=broker)

# Run the strategy live
trader.add_strategy(strategy)
trader.run_all()

Important

Remember to start with a paper trading account to ensure everything works as expected before moving to live trading.

AI Trading Team

LumiBot is built for AI agents that reason, call external tools, and make trading decisions on every bar during a backtest – then run the exact same code live. This is real agentic backtesting: the LLM is inside the simulation loop, not bolted onto the side.

Classic Python strategies are still first-class. LumiBot lets you choose the right level of intelligence: fixed rules, AI agents, or a hybrid where Python handles the hard gates and agents reason through evidence.

• Backtest AI trading agents with real external data from 20,000+ MCP servers

• LLM in the loop on every bar – the agent reasons over point-in-time market state, calls tools, and submits orders

• Replay caching makes warm backtest reruns deterministic and fast (zero LLM calls on rerun)

• Any LLM provider per agent – use a cheaper model for evidence gathering and a stronger model for debate/trading

• Built-in SEC fundamentals and filings – agents can inspect income statements, balance sheets, cash flow, company facts, and annual reports

• Built-in FRED macro data – agents can inspect rates, inflation, labor, growth, liquidity, credit spreads, and market-risk series

• Trading permissions – research agents can use read-only tools while portfolio-manager agents place orders

• Same code for backtest and live – write once, backtest it, deploy it

• External MCP servers are just a URL – no local scripts, no npm installs

Key AI agent docs:

• AI Trading Agents and Agentic Backtesting – main guide: agentic backtesting framework, MCP trading tools, and competitive positioning

• Design Your AI Trading Team – design single-agent, multi-agent, debate, team, and hybrid flows

• AI Trading Team Examples – copy-paste AI trading team examples, including leveraged ETFs, large-cap stocks, Ray Dalio idea meritocracy, Warren Buffett value, Bill Ackman concentrated, and Citadel sector pods

• SEC Fundamentals – SEC fundamentals and filing research tools

• FRED Macro Data – FRED macro data tools and point-in-time behavior

• Agent Built-In Tools – built-in tools, indicators, and trading permissions

• AI Agents Quick Start – quick start with code examples for AI agent backtesting

• Canonical AI Agent Demos – three reference demos: news sentiment, macro risk, and M2 liquidity

• AI Agent Observability – traces, replay cache, warnings, and debugging workflow

Design Your AI Trading Team

An AI trading team is just a group of agents with different jobs inside the same LumiBot strategy. You can build a single-agent strategy, a specialist research flow, bull/bear/neutral teams, model-vs-model debates, deterministic execution gates, or agent reviewers layered on top of normal Python logic.

Example: Research, Bull, Bear, and Trader Agents

Here is one example pattern: a researcher gathers evidence, bull and bear agents debate the trade, and a trader agent decides what to buy or sell.

In this pattern, each agent has a job:

1. Research Agent: builds the evidence pack from market data, filings, fundamentals, news, macro data, and indicators.

2. Bull Agent: turns that evidence into the strongest long thesis.

3. Bear Agent: challenges the thesis, looks for risk, and argues for avoiding, delaying, or reducing the trade.

4. Trader / Portfolio Manager Agent: checks cash, positions, open orders, and risk limits, then decides whether to trade.

The copy-paste example below implements that exact team. It uses Gemini Flash Lite because it is fast and inexpensive for experiments.

To run it with a broker in paper mode, set your AI and Alpaca credentials and run the file:

export GEMINI_API_KEY='your-key-here'
export ALPACA_API_KEY='your-alpaca-key'
export ALPACA_API_SECRET='your-alpaca-secret'
export ALPACA_IS_PAPER=true
python ai_trading_team_bull_bear_leveraged_etf.py

To backtest the same strategy instead, change IS_BACKTESTING = False to IS_BACKTESTING = True in the runner:

export GEMINI_API_KEY='your-key-here'
python ai_trading_team_bull_bear_leveraged_etf.py

Save this as ai_trading_team_bull_bear_leveraged_etf.py. If an AI key is missing or invalid, LumiBot stops and prints a clear provider key error with a link to create a key.

import os
from datetime import datetime

from lumibot.strategies.strategy import Strategy


class AITradingTeamBullBearLeveragedETFStrategy(Strategy):
    parameters = {
        "universe": ["TQQQ", "SQQQ", "UPRO", "SPXU", "UDOW", "SDOW", "TNA", "TZA", "TECL", "TECS", "SOXL", "SOXS", "WEBL", "WEBS", "FAS", "FAZ", "LABU", "LABD", "ERX", "ERY", "GUSH", "DRIP", "DRN", "DRV", "TMF", "TMV", "NUGT", "DUST"],
    }

    def initialize(self):
        self.sleeptime = "1D"
        model = os.environ.get("AI_TRADING_TEAM_MODEL", "gemini-3.1-flash-lite")
        # The first three agents are read-only. They can reason, but cannot trade.
        self.agents.create(
            name="researcher",
            model=model,
            allow_trading=False,
            system_prompt="Rank the ETFs by upside. Be direct.",
        )
        self.agents.create(
            name="bull",
            model=model,
            allow_trading=False,
            system_prompt="Argue for the strongest money-making trade.",
        )
        self.agents.create(
            name="bear",
            model=model,
            allow_trading=False,
            system_prompt="Point out the biggest risk, briefly.",
        )
        # Only this final agent can submit orders through Lumibot.
        self.agents.create(
            name="trader",
            model=model,
            allow_trading=True,
            system_prompt="Buy one ETF from the universe aggressively. Use nearly all cash.",
        )

    def on_trading_iteration(self):
        # Each trading day, pass the same market context through the team.
        context = {
            "date": self.get_datetime().date().isoformat(),
            "universe": self.parameters["universe"],
        }
        research = self.agents["researcher"].run(
            task_prompt="Pick the strongest ETF.",
            context=context,
        )
        bull = self.agents["bull"].run(
            task_prompt="Make the bull case.",
            context={**context, "research": research.summary},
        )
        bear = self.agents["bear"].run(
            task_prompt="Make the bear case.",
            context={**context, "research": research.summary, "bull": bull.summary},
        )
        self.agents["trader"].run(
            task_prompt="Sell anything that is not the pick, then buy the best ETF with nearly all available cash.",
            context={**context, "research": research.summary, "bull": bull.summary, "bear": bear.summary},
        )


if __name__ == "__main__":
    IS_BACKTESTING = False

    if IS_BACKTESTING:
        from lumibot.backtesting import YahooDataBacktesting

        AITradingTeamBullBearLeveragedETFStrategy.backtest(
            YahooDataBacktesting,
            datetime(2026, 4, 7),
            datetime(2026, 5, 22),
        )
    else:
        from lumibot.brokers import Alpaca
        from lumibot.traders import Trader

        ALPACA_CONFIG = {
            "API_KEY": os.environ["ALPACA_API_KEY"],
            "API_SECRET": os.environ["ALPACA_API_SECRET"],
            "PAPER": os.environ.get("ALPACA_IS_PAPER", "true").lower() != "false",
        }

        broker = Alpaca(ALPACA_CONFIG)
        strategy = AITradingTeamBullBearLeveragedETFStrategy(broker=broker)

        trader = Trader()
        trader.add_strategy(strategy)
        trader.run_all()

Example backtest artifact from this sample strategy:

The result is intentionally eye-catching, but the exact percentage is not the point. The point is that the full AI trading team runs inside Lumibot’s normal broker and backtest loops, so the decisions, orders, and artifacts are inspectable before you connect real money. Backtests are not expected future performance.

See this AI trading team running live on BotSpot

More AI Trading Team Examples

These examples show different ways to organize an AI trading team. Each page explains the inspiration, the agent flow, how to run it with a broker in paper mode, and how to backtest it.

1. Citadel Sector Pods AI Trading Team – inspired by the pod-style structure associated with Ken Griffin’s Citadel: sector specialists pitch their best ideas, a risk manager challenges crowding and drawdown risk, and a portfolio manager rotates into the strongest sector ETF. Watch it live on BotSpot.

2. Warren Buffett Value AI Trading Team – uses AI agents like a patient value-investing desk: one agent digs into business quality and annual reports, one demands valuation discipline, and the portfolio manager only buys the best long-term compounder. Watch it live on BotSpot.

3. Ray Dalio Idea Meritocracy AI Trading Team – turns Bridgewater-style thoughtful disagreement into a macro ETF workflow, with growth, inflation, liquidity, and disagreement agents arguing before the trader acts. Watch it live on BotSpot.

4. Bill Ackman Concentrated AI Trading Team – inspired by Pershing Square-style concentrated investing: find one great business, make the activist bull case, attack it like a short seller, then let the portfolio manager take a focused position if the thesis survives. Watch it live on BotSpot.

5. Bull/Bear Leveraged ETF AI Trading Team – a fast, aggressive demo where bull and bear agents debate leveraged long and inverse ETFs before the trader rotates into one high-conviction ETF. Watch it live on BotSpot.

6. Bull/Bear Large-Cap Stocks AI Trading Team – the same debate structure applied to familiar large-cap stocks, which makes it easier to inspect each agent’s reasoning before using more volatile instruments. Watch it live on BotSpot.

Cash Accounting

Lumibot supports explicit cash accounting for both backtests and live broker telemetry. Use the strategy cash methods for deposits, withdrawals, direct cash adjustments, and financing setup, then review the resulting cash-adjusted returns in the standard backtest artifacts.

• Backtests keep external cashflows out of strategy performance

• Live cloud payloads can include normalized broker cash_events

• Listener storage keeps raw normalized events in a dedicated event table

Start with Cash Accounting for the end-to-end guide.

Additional Resources

If you would like to learn how to modify your strategies, we suggest that you first learn about Lifecycle Methods, then Strategy Methods, and Strategy Properties. You can find the documentation for these in the menu, with the main pages describing what they are, then the sub-pages describing each method and property individually.

We also have some more sample code that you can check out here: https://github.com/Lumiwealth/lumibot/tree/dev/lumibot/example_strategies

Next, explore the AI agent docs if you want a strategy that researches evidence, debates bull and bear cases, checks risk, and trades from the same Python lifecycle.

Need Extra Help?

If you want a guided path instead of piecing everything together from docs, start with the AI Trading Bootcamp. It teaches the full workflow: turn an idea into a Lumibot strategy, backtest it, inspect the artifacts, connect a broker, and decide when it is ready for paper or live trading.

BotSpot is the cheaper, easier way to run Lumibot once you want hosted data, parallel backtests, broker connections, monitoring, alerts, audit history, and scheduled deployment without maintaining your own trading server.

Learn the full workflow

The AI Trading Bootcamp is the fastest path if you want guided help building Lumibot strategies with AI. Learn how to structure a strategy, run a backtest, read the artifacts, connect a broker, and decide what should happen before anything trades live.

Join the AI Trading Bootcamp

Why run Lumibot on BotSpot?

BotSpot removes the infrastructure work around the strategy when you are ready to build, test, or run it in the cloud:

• Hosted data and artifacts: backtest without assembling every data feed yourself.
• Parallel backtests: compare strategy variants on BotSpot servers instead of tying up your laptop.
• Cheaper scheduled runs: run periodic bots without paying for always-on infrastructure per strategy.
• Broker connections and monitoring: keep logs, charts, alerts, account checks, audit history, and kill switches in one place.
• MCP tools: let Codex, Claude Code, Cursor, and other coding agents launch backtests, inspect artifacts, and prepare runs.

Try a sample strategy on BotSpot Connect BotSpot MCP

Why Lumibot?

AI trading projects have proved that people want agentic trading workflows. Lumibot’s edge is that those workflows run inside a real Python trading framework. You can backtest the agent decisions, inspect the artifacts, add normal Python guardrails, paper trade, and connect to brokers without rewriting the strategy.

That matters because an AI trading demo is not the same thing as a trading system. Without backtests and broker-aware strategy code, you are mostly trusting prompts. Lumibot lets you iterate faster: test the agent flow on historical data, see what it would have bought or sold, tighten the Python risk checks, then run the same lifecycle in paper or live trading.

Compared With AI Trading Agent Projects

Project	AI trading teams	Backtest decisions	Paper/live broker path	Hosted deploy/monitoring
Lumibot + BotSpot	Flexible teams, single agents, debates, hybrid flows, and deterministic gates	Yes: replayable decisions, orders, traces, artifacts, charts, logs	Yes: Alpaca, IBKR, Tradier, Schwab, Tradovate, ProjectX, Bitunix, selected CCXT	Yes: hosted data, parallel backtests, deployment, monitoring, MCP, alerts, kill switches
TradingAgents	Yes, focused on a specific multi-agent research structure	Research/demo oriented	Not the main focus	No
ai-hedge-fund	Yes, focused on named investor-style agents	Demo/backtest oriented	Not the main focus	No
OpenAlice	Yes, one-person Wall Street agent concept	Experimental	Local/self-run focus	No
QuantDinger	Yes	Yes	Crypto, IBKR, MT5, Alpaca	Self-hosted
Vibe-Trading	Yes, personal trading agent flow	Yes	Agent platform focus	Platform-specific
AI-Trader	Yes	Platform focus	Platform focus	Platform-specific
OpenBB	Tooling for agents	Not a strategy backtester	No broker execution framework	OpenBB platform
Qlib	Research/ML agents	Quant research backtests	Limited live focus	No

Read the detailed comparison page: AI Trading Project Comparison.

Compared With Backtesting Libraries

Library	Same code: backtest + live	Assets	AI agent runtime	Broker/live path	Hosted deployment
Lumibot	Yes	Stocks, options, crypto, futures, forex	Built-in	Alpaca, IBKR, Tradier, Schwab, Tradovate, ProjectX, Bitunix, selected CCXT	BotSpot
Backtrader	Yes	Stocks, limited crypto/futures, outdated forex	No	IB only/outdated	No
Freqtrade	Crypto	Crypto	FreqAI/ML	Crypto exchanges	No
Zipline	No	Stocks	No	None	No
Backtesting.py	No	Stocks, crypto, futures, forex	No	None	No
vectorbt	No	Stocks, crypto, futures, forex	No	No	No
NautilusTrader	Yes	Stocks, crypto, futures, forex, limited options	No	Exchange adapters	No
Hummingbot	Crypto	Crypto market making	Scripts/controllers	Crypto exchanges	Ecosystem/enterprise options

Table of Contents

• Home
• Build Bots with AI
• BotSpot MCP Integration
  • Last verified
  • Canonical endpoints
  • Important transport note
  • Authentication modes
  • Create an API key
  • Client quickstarts
  • What BotSpot MCP enables
  • Known chaining requirement
  • Validation checklist (copy/paste)
  • Local debugging (recommended)
  • Troubleshooting
  • More resources
• GitHub
• Getting Started
  • Build AI Trading Agents
  • Need Help Building Or Running Strategies?
  • Getting Started With Lumibot
  • Adding Trading Fees
  • Profiling to Improve Performance
  • Frequently Asked Questions
• Imports and Startup
  • Supported Import Styles
  • Lazy Import Semantics
  • Symbol Parsing
• AI Trading Agents and Agentic Backtesting
  • AI Agents Quick Start
  • Design Your AI Trading Team
  • AI Trading Team Examples
  • Agent Built-In Tools
  • Canonical AI Agent Demos
  • AI Agent Observability
  • Agent Memory
  • Agent Notifications
  • Why This Is Different
  • Quick Start
  • How @agent_tool Works
  • External Data Patterns
  • Built-in Tools
  • System Prompts
  • Agent Handoffs
  • DuckDB and Time-Series Data
  • Replay Cache
  • Observability
  • Canonical Demos
  • Frequently Asked Questions
  • Error Handling and Reliability
• AI Trading Project Comparison
  • Quick Comparison
  • Detailed Comparisons
  • Why Lumibot Is Different
• Cash Accounting
  • Strategy cash methods
  • Backtest artifacts
  • Broker cash events
  • Long-form reference
  • Documentation map
• Lifecycle Methods
  • Summary
  • def initialize
  • def on_trading_iteration
  • def before_market_opens
  • def before_starting_trading
  • def before_market_closes
  • def after_market_closes
  • def on_abrupt_closing
  • def on_bot_crash
  • def trace_stats
  • def tearsheet_custom_metrics
  • def on_new_order
  • def on_partially_filled_order
  • def on_filled_order
  • def on_canceled_order
  • def on_parameters_updated
• Strategy Methods
  • Order Management
  • Account Management
  • Data
  • Chart Functions
  • Parameters
  • Options
  • DateTime
  • Miscellaneous
• Strategy Properties
  • self.cash
  • self.portfolio_value
  • self.first_iteration
  • self.is_backtesting
  • self.quote_asset
  • self.name
  • self.initial_budget
  • self.minutes_before_closing
  • self.minutes_before_opening
  • self.sleeptime
  • self.last_on_trading_iteration_datetime
  • self.timezone
  • self.pytz
  • self.unspent_money
• Entities
  • Asset
  • Bars
  • Data
  • Order
  • Position
  • Trading Fee
  • Trading Slippage
  • Smart Limit Config
  • Chains Entity
• Indicators
  • Why this matters
  • Built-in pandas-ta-classic passthrough
  • Custom indicators
  • Cache key and staleness
  • Current-bar semantics
  • API reference
  • Migration guide
• SEC Fundamentals
  • Point-In-Time Behavior
  • Caching
  • Agent Tools
  • Related Macro Data
  • Filing Search
• FRED Macro Data
  • Strategy API
  • Agent Tools
  • API Key Behavior
  • Backtest Date Safety
  • Cache
• Backtesting
  • Managed Backtesting on BotSpot
  • Agentic Backtesting
  • Files Generated from Backtesting
• Brokers
  • Alpaca
  • Bitunix
  • Crypto Brokers (Using CCXT)
  • Interactive Brokers
  • Interactive Brokers Legacy
  • ProjectX / TopstepX
  • Schwab
  • Tradier
  • Tradovate
• Reference
  • Variable Backup & Restore
  • Futures Trading
  • Smart Limit Orders
  • OptionsHelper
  • Environment Variables
• Code Examples
  • AI Agents
  • Stocks
  • Positions and Orders
  • Persistent Variables
  • Logging and Debugging
  • Options
  • Options Strategies with OptionsHelper
  • Cryptocurrency
  • Crypto Futures (Bitunix)
  • Futures (DataBento)
  • FOREX
  • AI-Powered Trading (PerplexityHelper)
• Deployment Guide
  • Option A — Deploy on BotSpot (Recommended)
  • Option B — Self-hosted Deployment (Render or Replit)
  • Example Strategy for Deployment
  • Choosing Your Self-hosted Platform
  • Deploying to Render
  • Deploying to Replit
  • Secrets Configuration
  • Broker Configuration
  • Tradier Configuration
  • Tradovate Configuration
  • Alpaca Configuration
  • Coinbase Configuration
  • Kraken Configuration
  • Additional CCXT Exchange Examples
  • Interactive Brokers Configuration
  • Interactive Brokers-Legacy Configuration
  • Schwab Configuration
  • Bitunix Configuration
  • DataBento Configuration
  • ProjectX Configuration
  • General Environment Variables
  • Final Steps
  • Conclusion
• Common Mistakes and How to Avoid Them
  • Critical Mistakes (Will Break Your Strategy)
  • Data Mistakes
  • Options Mistakes
  • Order Mistakes
  • Visualization Mistakes
  • Code Organization Mistakes
• Frequently Asked Questions (FAQ)
  • Getting Started
  • AI Trading Agents
  • Backtesting
  • Strategy Development
  • Options Trading
  • Crypto Trading
  • Futures Trading
  • Brokers
  • Data and Market Information
  • Deployment
  • Debugging and Troubleshooting
  • Advanced Topics
• Get Pre-Built Strategies

Indices and tables

• Index

• Module Index

• Search Page