Agents
Agents let you build a trading automation visually, without writing a full strategy script. On the QuantCraft — Agents canvas you wire together nodes that fetch data, make a decision (with rules or an AI prompt), place trades, and send alerts — then run the whole flow as a historical backtest or a forward (live/paper) run. Agents appear in the app when the Agents feature is enabled for your build.
Open Agents from the nav (or pop the editor out into its own window). Every new agent starts as a Draft and already contains one Schedule trigger node — the entry point that every other node hangs off. Agents lean on other parts of QuantCraft: the AI assistant powers AI Prompt nodes; backtests use the paper account, and forward runs can submit to your selected Alpaca account.
Node types
Add nodes from the picker (the Schedule trigger is seeded for you and is not in the picker).
| Node | What it does | What you configure |
|---|---|---|
| Schedule trigger | Runs the agent on a fixed schedule. Entry point of every agent — cannot be deleted and has no parents. | Frequency + interval. |
| Data | Fetches inputs: OHLCV, fundamentals, Fama-French factors, or custom data. One Data node can carry several sources. | One or more data sources. |
| Strategy | Turns upstream data into a true/false decision that gates its children. | Strategy items (rules) + how they combine. |
| AI Prompt | Asks an AI a yes/no question about upstream data; the answer gates its children. | A free-text prompt. See QuantCraft AI. |
| Execution | Opens or closes trades. Backtests use a paper account; forward / bulk runs submit to the selected Alpaca account when credentials are present. Can only attach to a Strategy or AI Prompt node. | One or more order actions. |
| Notification | Sends an email alert. Can attach to any node. | Email rule(s) + a "Disable in backtest" toggle. |
Gating nodes are Strategy and AI Prompt — they produce a boolean and control whether their children run.
Building an agent
- Create an agent in the sidebar. It appears as a Draft with a Schedule trigger already placed.
- Add a node — click a node's
+(add-child) button, or right-click a node → Node Actions → New Child Node. The picker only offers nodes that are valid children of the one you clicked (for example, an Execution node only appears under a Strategy or AI Prompt node). - Connect nodes — drag a node's reparent handle onto another node. Rules:
- A node may have at most 2 parents.
- Cycles are not allowed.
- A Data node becomes the parent of the gating node it feeds.
- An Execution node can only attach to a Strategy or AI Prompt node.
- Click an edge to delete that link.
- Configure a node — click it to open the drawer inspector, which has type-specific tabs (Rules / Sources, plus Output; Strategy and AI Prompt also get a Received data tab). Every rule or source row is click-to-edit.
- Set the upstream gate — for children of a gating node, the drawer shows an Upstream gate summary. Open it to choose how the parents combine (AND / OR) and what result each parent must produce (true / false). Convention: gate an entry on true and the matching exit on false.
Data flows down the graph: a Strategy or AI Prompt node reads all the OHLCV, fundamentals, and factor data from every Data node above it.
Configuring nodes
Schedule trigger
| Field | Options |
|---|---|
| Frequency | Seconds, Minutes, Hours, Days, or Bars. |
| Interval | A whole number ≥ 1 (e.g. every 5 bars). |
For a backtest, the schedule is set by the Test modal's Scheduler tab, which overrides this node. The node's schedule applies to forward runs.
Data sources
A Data node can hold several sources at once.
| Kind | What you set |
|---|---|
| System · OHLCV | Provider (Alpaca or QuantCraft), timeframe, and a start/end window (each can be "now", a relative "N units ago", or an absolute date/time). |
| System · Fundamentals | Reporting period (Quarterly or Annual), shift (≥ 0), and periods (≥ 1). |
| System · Fama-French | The factor dataset (one per Data node). |
| Script | A QuantCraft Agent Script, with an optional JSON schema. |
| URL | A URL that returns JSON, with an optional JSON schema. |
A node allows at most one Fama-French source and at most one Fundamentals source per reporting period.
Strategy items
A Strategy node combines one or more items. Which item kinds are available depends on the upstream Data (for example, Indicator rules need upstream OHLCV, and a Fundamentals item needs an upstream fundamentals source).
Item kinds: Script, Indicator, Fundamentals, Trade Activity, Account Status, Custom data, Fama-French.
Comparison operators
| Operator | Meaning |
|---|---|
| Equals / Not equals | = / ≠ |
| Greater than / Greater or equal | > / ≥ |
| Less than / Less or equal | < / ≤ |
| Crosses above / Crosses below | Series crosses the compared value |
| Between / Outside | Inside or outside a range |
| Rising / Falling | Series trending up / down (no right-hand value) |
| % change greater than / % change less than | Percent move vs a baseline |
Indicators — the full chart indicator registry is available. Single-output indicators include SMA, EMA, WMA, RSI, ATR, OBV, VWAP, CCI, ROC, Williams %R, Parabolic SAR, HMA, DEMA, TEMA, Supertrend, VWMA, MFI, Awesome Oscillator, CMF, and A/D Line. Multi-output indicators — Bollinger Bands, MACD, Stochastic, Donchian, ADX, Ichimoku, Keltner, Stochastic RSI, and PPO — let you pick which line to compare (e.g. MACD line vs its signal). See Indicator series.
Trade Activity metrics: number of open trades, total quantity of open trades, plus the same counts restricted to the current symbol. Account Status metrics: equity, balance, floating P/L.
Use Combine items with (node level) and Combine rules with (per item) to join conditions with AND or OR.
Execution actions
Each action is an Entry (open), Exit (close), or Script. The symbol comes from the run configuration — you don't type it here.
Entry (places an order)
| Field | Options |
|---|---|
| Side | Buy / Sell |
| Size | Quantity (shares) or Notional ($) |
| Order type | Market, Limit, Stop, Stop limit, Trailing stop |
| Time in force | Day, GTC, OPG (at open), CLS (at close), IOC, FOK |
| Limit / stop price | Required for limit / stop / stop-limit types |
| Trail | Price ($) or percent (%) for trailing stops |
| Order class | Simple, Bracket, OCO, OTO (bracket classes add take-profit / stop-loss legs) |
| Extras | Extended hours, client order id |
Exit (closes a position): Quantity (shares) or Percentage of position. Script: runs a QuantCraft Agent Script.
Notification
A rule sends an Email to a recipient, with an optional custom message and an "include previous output" toggle. The node-level Disable in backtest toggle skips emails during an Agent Test.
Backtesting an agent
Click Test in the editor header to open Test agent (backtest).
Setup tab
| Field | Notes |
|---|---|
| Start / End date | UTC calendar days (defaults to roughly the last month). |
| Initial cash | Starting paper balance (default 100,000). |
Scheduler tab
| Field | Notes |
|---|---|
| Symbol catalog | Alpaca or QuantCraft. |
| Stocks / Crypto | Multi-select the symbols to run. |
| Timeframe | Bar granularity. |
| Bar interval | Trigger every N bars (1 = every bar). |
| Fundamentals per symbol | Appears when the graph uses a Fundamentals source — Premium only. |
The Scheduler tab replaces the Schedule trigger node for the backtest only; forward runs still follow the node.
Requirements & controls
- An active Trade (Alpaca) account is required — it's used to prefetch market data, so Test won't start without it.
- While a run is in progress the Test button becomes Pause / Resume and Stop.
- Your last-used Test settings are remembered.
Results — on success the header switches to a Test Results tab: OHLC chart with indicator overlays, trade history, equity curve, and account metrics. Multi-symbol runs share one paper account, so trades and metrics are combined (not per symbol). Each node's Output tab streams live logs (data fetched, strategy pass/fail, AI answers, order fills, email intents); Strategy and AI Prompt nodes also show the exact inputs on their Received data tab.
Saving, managing, and monitoring
- Save clears the Draft badge. Every edit auto-saves locally regardless — Save just marks the agent as no longer a draft.
- In the sidebar, right-click an agent to Rename, Duplicate, or Delete. Duplicating clones the graph as a new draft.
- During a run, each node card shows a live status badge — waiting, running, ok, failed, or skipped — and streams events into its Output tab.
Good to know
- Backtest vs forward execution. Agent Test (backtest) uses a simulated paper account. Forward runs (chart Agents menu, Auto Trading New Agent Bulk Run, Quant Cloud) use the selected Alpaca account and can submit live orders when that account is live.
- Schedule applies once a run is started. The editor does not auto-start agents in the background. After you start a forward / bulk / chart run, cadence comes from the Schedule trigger (or the Test modal Scheduler override for backtests).
- Structural limits: at most 2 parents per node, no cycles, and Execution nodes attach only to Strategy or AI Prompt nodes.
- Fundamentals in a backtest is Premium-gated (same free-data access as other fundamentals UI when enabled).
See also
- QuantCraft AI — the AI Prompt node and how its model is chosen
- Auto Trading — Agent Bulk Run and local forward monitoring
- Account model — the paper account, metrics, commission / slippage
- Fundamentals — fundamentals data
- Fama-French factors — Fama-French factors
- Indicator series — chart indicator overlays