Agent Workflow Guide

This guide walks through the complete workflow for an AI agent interacting with Lona — from registration to strategy creation, backtesting, and analysis.

Quick Reference

Step 1: Register (if needed)

If the MCP server is not auto-registered (no LONA_AGENT_ID configured), call lona_register_agent first:

{
  "agent_id": "my-trading-agent",
  "agent_name": "My Trading Agent",
  "source": "my-platform"
}

The tool automatically handles registration:

• If LONA_AGENT_REGISTRATION_SECRET is configured, uses the fast path (no rate limits)
• Otherwise, requests an invite code and registers in one step

If the server has LONA_AGENT_ID set, registration happens automatically on startup — skip this step.

Step 2: Create a Strategy

Recommended: Use lona_create_strategy_from_description to create a strategy from a natural language description. The platform uses AI to generate proper Backtrader  Python code.

{
  "description": "A momentum strategy that buys when RSI crosses above 30 and sells when it crosses below 70, with a 2% trailing stop loss and ATR-based position sizing"
}

This returns a strategyId ready for backtesting, plus the generated code and an explanation.

Choosing an AI Provider

You can optionally specify which AI provider and model to use for code generation:

{
  "description": "BTC 4H trend following with ZigZag(8%, 12 bars). Buy on higher lows, sell on lower highs.",
  "provider": "anthropic",
  "model": "claude-opus-4-6"
}

Available providers: xai, openai, anthropic, google, openrouter. Each has reasoning/thinking enabled for higher-quality code generation. If omitted, the default provider is Anthropic (Claude Opus 4.6 with adaptive thinking).

Note: Regardless of which provider generates the code, AI code validation always uses Anthropic Opus 4.6 to ensure the highest quality review.

Use openrouter for access to 300+ models (e.g., moonshotai/kimi-k2.5, qwen/qwen3-max-thinking).

Do NOT write code manually

Lona strategies use Backtrader (bt.Strategy). The AI code generator understands the framework conventions (params tuples, __init__ for indicators, next() for trading logic). Let it handle code generation.

If you already have Backtrader code, use lona_create_strategy instead.

Step 3: Get Market Data

Lona provides two sources of data:

Pre-loaded global data

Call lona_list_symbols with isGlobal: true to browse hundreds of pre-loaded symbols (US equities, crypto, forex):

{
  "isGlobal": true,
  "limit": 20
}

Each symbol has an id you’ll use in the backtest.

Download from Binance

For cryptocurrency data, use lona_download_market_data:

{
  "symbol": "BTCUSDT",
  "interval": "1h",
  "start_date": "2024-01-01",
  "end_date": "2024-12-01"
}

This downloads, processes, and uploads the data to your account in one step.

Step 4: Run a Backtest

Call lona_run_backtest with the strategy ID and data IDs:

{
  "strategy_id": "your-strategy-id",
  "data_ids": ["symbol-id-from-step-3"],
  "start_date": "2024-01-01",
  "end_date": "2024-12-01",
  "initial_cash": 100000,
  "commission": 0.001
}

This returns a reportId immediately. The backtest runs asynchronously.

Step 5: Poll for Results

Call lona_get_report_status with the report ID to check progress:

{
  "id": "your-report-id"
}

Status values: PENDING → EXECUTING → PROCESSING → COMPLETED or FAILED.

Step 6: Get Performance Metrics

Once COMPLETED, call lona_get_report for a summary or lona_get_full_report for detailed metrics:

• Total return and annualized return
• Sharpe ratio and max drawdown
• Win rate and number of trades
• Per-symbol breakdown (for multi-asset strategies)

If the backtest FAILED, lona_get_full_report includes stderr output to diagnose the issue.

Step 7: Visualize (Optional)

Call lona_get_report_chart for an interactive candlestick chart with buy/sell markers.

Complete Tools Reference

Strategy Tools

Data Tools

Backtest Tools

Common Pitfalls

1. Writing Backtrader code manually — Use lona_create_strategy_from_description instead. The AI knows the framework conventions.
2. Using wrong endpoints — Always use the MCP tools. The runner is at /runner/run, not /runner/execute.
3. Missing global symbols — Set isGlobal: true when listing symbols to see pre-loaded market data.
4. Not polling for results — Backtests are async. Always poll with lona_get_report_status before reading results.
5. Forgetting to register — If you get authentication errors, ensure lona_register_agent was called first.