Agents reference

Factory functions that create the four agent nodes used in the QuantAgent graph.

QuantAgent uses four specialized agent nodes connected in a fixed sequence:

Indicator Agent → Pattern Agent → Trend Agent → Decision Maker

Each agent is created by a factory function that returns a LangGraph-compatible node function (a callable that accepts a state dict and returns a partial state dict).

create_indicator_agent(llm, toolkit)

from indicator_agent import create_indicator_agent

Creates the Indicator Agent node. This agent computes five technical indicators over the OHLCV data and produces a narrative analysis report.

Parameters

Parameter	Type	Description
llm	BaseChatModel	The LLM that calls indicator tools and synthesizes the report. Bound with tool-calling capability.
toolkit	TechnicalTools	Toolkit instance exposing the indicator methods as LangChain tools.

Tools used

• compute_macd — MACD line, signal, and histogram
• compute_rsi — Relative Strength Index
• compute_roc — Rate of Change
• compute_stoch — Stochastic Oscillator %K and %D
• compute_willr — Williams %R

Execution model

The agent uses a tool-call loop with a maximum of 5 iterations. On each iteration it checks whether the LLM has emitted further tool calls. Once the LLM produces a plain-text response with no additional tool calls, the loop exits and the text is stored as indicator_report.

If the LLM returns empty content (common with multi-step Claude responses), the agent scans backwards through the message history for the most recent non-empty text content.

State output

Key	Type	Description
indicator_report	str	Narrative summary of all computed indicators.
messages	list	Updated message list including all tool calls and responses.

create_pattern_agent(agent_llm, graph_llm, toolkit)

from pattern_agent import create_pattern_agent

Creates the Pattern Agent node. This agent generates a candlestick chart image and uses a vision LLM to identify classical price patterns.

Parameters

Parameter	Type	Description
agent_llm	BaseChatModel	Used for the tool-calling step to invoke generate_kline_image.
graph_llm	BaseChatModel	Vision-capable LLM used to analyze the generated chart image.
toolkit	TechnicalTools	Toolkit instance exposing generate_kline_image.

Tool used

• generate_kline_image — Generates a candlestick chart of the most recent 40 candles and returns a base64-encoded PNG.

Execution model

1. Check for precomputed image

   If pattern_image is already present in the state, the tool-calling step is skipped.

2. Generate chart

   agent_llm is prompted to call generate_kline_image with the current kline_data.

3. Vision analysis

   graph_llm receives the base64 image alongside a list of 16 classical candlestick pattern definitions. The LLM identifies the best matching pattern and explains its reasoning.

Failed LLM or tool calls are automatically retried up to 3 times with an 8-second wait.

Recognized patterns include: Inverse Head and Shoulders, Double Bottom, Rounded Bottom, Hidden Base, Falling/Rising Wedge, Ascending/Descending Triangle, Bullish/Bearish Flag, Rectangle, Island Reversal, V-shaped Reversal, Rounded Top, Expanding Triangle, Symmetrical Triangle.

State output

Key	Type	Description
pattern_report	str	Narrative identifying the detected candlestick pattern(s) and reasoning.
messages	list	Updated message list.

create_trend_agent(agent_llm, graph_llm, toolkit)

from trend_agent import create_trend_agent

Creates the Trend Agent node. This agent generates a trendline-annotated chart and uses a vision LLM to assess the prevailing market direction.

Parameters

Parameter	Type	Description
agent_llm	BaseChatModel	Used for the tool-calling step to invoke generate_trend_image.
graph_llm	BaseChatModel	Vision-capable LLM used to analyze the annotated chart.
toolkit	TechnicalTools	Toolkit instance exposing generate_trend_image.

Tool used

• generate_trend_image — Generates a candlestick chart overlaid with fitted support (blue) and resistance (red) trendlines derived from recent closing prices, highs, and lows.

Execution model

1. Check for precomputed image

   If trend_image is already present in the state, the tool-calling step is skipped.

2. Generate annotated chart

   agent_llm is prompted to call generate_trend_image with the current kline_data.

3. Vision analysis

   graph_llm analyzes how price interacts with the trendlines—bouncing, breaking through, or compressing—and predicts the short-term direction (upward, downward, or sideways).

Failed calls are retried up to 3 times with a 4-second wait.

State output

Key	Type	Description
trend_report	str	Narrative describing trendline interaction and directional prediction.
trend_image	str	Base64-encoded PNG of the annotated chart.
trend_image_filename	str	Local filename where the chart was saved ("trend_graph.png").
trend_image_description	str	Short description of the chart.
messages	list	Updated message list.

create_final_trade_decider(llm)

from decision_agent import create_final_trade_decider

Creates the Decision Maker node. This agent synthesizes the three upstream reports and issues an actionable LONG or SHORT trade directive.

Parameters

Parameter	Type	Description
llm	BaseChatModel	The LLM used to produce the final decision. Does not use tools.

Decision logic

The LLM is instructed to:

1. Prioritize decisions where all three reports (Indicator, Pattern, Trend) align in the same direction.
2. Give higher weight to strong, confirmed signals — MACD crossovers, RSI divergence, breakout confirmation.
3. Default to the dominant trendline slope when reports are mixed (e.g., SHORT in a descending channel).
4. Always output either LONG or SHORT. HOLD is prohibited in the HFT context.
5. Suggest a risk-reward ratio between 1.2 and 1.8.

Decision JSON output format

The final_trade_decision field contains a JSON string with the following structure:

{
  "forecast_horizon": "Predicting next 3 candlesticks (45 minutes)",
  "decision": "LONG",
  "justification": "MACD bullish crossover confirmed by ascending support trendline bounce. RSI recovering from 38. Bullish flag pattern approaching breakout.",
  "risk_reward_ratio": "1.5"
}

forecast_horizon · string

Human-readable description of the prediction window (e.g., "Predicting next 3 candlesticks (45 minutes)").

decision · string

Trade direction: "LONG" or "SHORT".

justification · string

Concise reasoning grounded in the three upstream reports.

risk_reward_ratio · string

Float between 1.2 and 1.8 as a string (e.g., "1.5").

State output

Key	Type	Description
final_trade_decision	str	JSON string containing the trade decision (see format above).
decision_prompt	str	The full prompt string sent to the LLM, useful for debugging.
messages	list	List containing the LLM response message.

Graph execution order

The agents are chained in this fixed sequence inside SetGraph.set_graph():

Each agent reads from the shared IndicatorAgentState and writes its outputs back into it. The Decision Maker has access to all three reports when it runs.