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. The Agents feature controls the Agents page, its nav link and its pop-out window; running agents from the chart's Agents menu and AutoTrading's New Agent Bulk Run is available regardless.
Open Agents from the nav (or pop the editor out into its own window). 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 connected broker account.
Agent types
Create agent asks which kind you want, then for a name:
| Type | What it is |
|---|---|
| Trading Agent | A node graph that trades on a schedule — most of this page. Every new one starts as a Draft and already contains one Schedule trigger node, the entry point that every other node hangs off. |
| Test Agent | Your connected AI backtests an IDE algo or a trading agent across parameters and date ranges, then reports how robust it is. See AI Test and Optimization agents. |
| Optimization Agent | Your connected AI runs grid / genetic optimizations within your bounds, confirms the best sets, and summarizes the results. |
Test and Optimization agents show "Not available in this build." when that feature is switched off.
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. The model can also call read-only tools (OHLCV, indicators, fundamentals, screener, account, positions) scoped to this run — see QuantCraft Tools. | A free-text prompt. See QuantCraft AI. |
| Execution | Opens or closes trades. Backtests use a paper account; forward / bulk runs submit to the selected connected broker 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 (email is the only method). 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 (Create agent → Trading Agent → name it). 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, and an Execution node only offers Notification children). - 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, and its only children can be Notification nodes.
- 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). Trigger, Strategy and Execution nodes also have a Parameters tab — see Exposed parameters. 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.
Prefer to describe the agent in words? Use the AI Builder.
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 (connected broker 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, plus a required JSON response schema. |
| URL | A URL that returns JSON, plus a required JSON response schema. |
The schema describes the JSON the script or URL returns; its fields are what a Strategy node's Custom data item lets you compare. Saving without one shows "Enter a JSON response 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 Node 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). |
| Include calendar data (dividends, splits) | Premium-gated. Adjusts positions for splits and credits dividends, like an IDE backtest — see Calendar data. |
Scheduler tab
| Field | Notes |
|---|---|
| Symbol source | Selected Stocks & Crypto, or Screener (trade whatever a saved screen matches, re-screened as the test goes — see Screener). |
| Symbol catalog | Connected broker 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.
Optimization tab — appears when the agent has exposed parameters. Tick Run as optimization to search over them (grid or genetic) instead of running once; the button then reads Start optimization instead of Start test.
Requirements & controls
- An active connected trading 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. Pause takes effect after the node that's currently running finishes.
- 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, plus the Screener rebalance schedule and split / dividend rows when those apply. 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.
Exposed parameters and optimization
On a Trigger, Strategy or Execution node, the Parameters tab lets you mark numeric settings (an interval, an indicator period, a threshold, an order size…) as exposed, with a range. Exposed parameters are what the Test modal's Optimization tab searches over, and what an AI Optimization agent tunes. See Optimization for how grid and genetic search work.
AI Builder
The AI Builder button (sparkle icon) in a Trading agent's header opens a chat beside the canvas. Describe the agent in plain English and your connected AI model adds, configures and links the nodes for you — and can write Agent Scripts into your workspace.
- Ask mode answers questions about the graph without changing it; Build mode makes changes.
- Changes apply live, and each reply has Keep / Undo.
- You can attach files to your messages.
- It uses the same model connection as QuantCraft AI; its token use counts toward the agent's token badge.
AI Test and Optimization agents
Test and Optimization agents don't have a node graph. You give the AI a target — an IDE algo or a Trading agent — plus Instructions for the AI, and limits: Max iterations (one iteration = one backtest; the AI plans them all up front), Max AI rounds, Max AI tokens and Max backtest windows. Tick Allow market data tools to let it use QuantCraft Tools (off by default). You can attach files to the instructions.
When you start one, the AI works in its own AI-controlled pop-out windows — running backtests and optimizations, saving findings to memory — and finishes with a summary. The agent's page has Overview, Sessions, Windows and Memory tabs, so you can follow each session, see its iteration plan and runs, and close windows.
Backtest and optimization results — including an AI's summary of them — describe historical data only and do not guarantee live results.
Saving, managing, and monitoring
- Save clears the Draft badge and keeps a saved copy of the graph. Every edit still auto-saves locally, but once you change a saved agent the Draft badge returns with an Undo button, which (after a confirmation) puts the graph back to your last save.
- In the sidebar, right-click an agent to Rename, Duplicate, or Delete. Duplicating clones the graph as a new draft.
- Share agents as files (desktop app): the header's ⋯ menu has Export…, which saves the agent as a
.qcafile, and the sidebar menu has Import… to load one or more.qcafiles. Agent Script references are re-linked to your workspace on import. - 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, AutoTrading New Agent Bulk Run) use the selected connected broker account and can submit live orders when that account is live. QuantCloud runners run IDE algorithms only — not agents.
- 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, Execution nodes attach only to Strategy or AI Prompt nodes, and an Execution node's children can only be Notification 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
- QuantCraft Tools — read-only tools AI Prompt nodes and AI agents can call
- AutoTrading — Agent Bulk Run and local forward monitoring
- Screener — filter equities by fundamentals to use as bulk-run targets
- Account model — the paper account, metrics, commission / slippage
- Fundamentals — fundamentals data
- Fama-French factors — Fama-French factors
- Indicator series — chart indicator overlays