Agent state

The IndicatorAgentState TypedDict that flows through the QuantAgent LangGraph pipeline.

All four agents in QuantAgent share a single state dictionary typed as IndicatorAgentState. This TypedDict is defined in agent_state.py and is used as the schema for the LangGraph StateGraph.

Each agent reads fields it needs from the state and writes its outputs back into it. The state is initialized by you when calling graph.invoke(initial_state) and is fully populated by the time the graph reaches END.

IndicatorAgentState

from agent_state import IndicatorAgentState

Input fields

These fields must be provided in initial_state before invoking the graph.

Field	Type	Description
kline_data	dict	OHLCV dictionary with keys Datetime, Open, High, Low, Close (lists of values). Used as input by all agents.
time_frame	str	Candlestick interval string (e.g., "15min", "4hour", "1d"). Embedded in agent prompts.
stock_name	str	Ticker or asset name (e.g., "BTC", "AAPL"). Embedded in the Decision agent prompt.
analysis_results	str | None	Pass None on the first invocation.
messages	List[BaseMessage]	LangChain message history. Pass [] to start fresh.

Indicator agent outputs

Populated by create_indicator_agent after it runs.

Field	Type	Description
rsi	List[float]	Relative Strength Index values (last 28).
macd	List[float]	MACD line values (full series).
macd_signal	List[float]	MACD signal line values (last 28).
macd_hist	List[float]	MACD histogram values (last 28).
stoch_k	List[float]	Stochastic Oscillator slow %K values (last 28).
stoch_d	List[float]	Stochastic Oscillator slow %D values (last 28).
roc	List[float]	Rate of Change values (last 28).
willr	List[float]	Williams %R values (last 28).
indicator_report	str	Narrative summary of all computed indicators. Passed to the Decision agent.

Pattern agent outputs

Populated by create_pattern_agent after it runs.

Field	Type	Description
pattern_image	str	Base64-encoded PNG of the candlestick chart. Can be pre-populated to skip tool generation.
pattern_image_filename	str	Local file path of the saved chart image ("kline_chart.png").
pattern_image_description	str	Short description of the chart image.
pattern_report	str	Narrative identifying detected candlestick patterns. Passed to the Decision agent.

Trend agent outputs

Populated by create_trend_agent after it runs.

Field	Type	Description
trend_image	str	Base64-encoded PNG of the trendline-annotated chart. Can be pre-populated to skip tool generation.
trend_image_filename	str	Local file path of the saved chart ("trend_graph.png").
trend_image_description	str	Description including support/resistance line characteristics.
trend_report	str	Narrative describing trendline interaction and short-term directional prediction. Passed to the Decision agent.

Decision agent outputs

Populated by create_final_trade_decider after it runs.

Field	Type	Description
final_trade_decision	str	JSON string with keys forecast_horizon, decision (LONG/SHORT), justification, risk_reward_ratio.
decision_prompt	str	The full prompt string sent to the LLM. Useful for debugging.

Constructing initial_state

The minimal initial_state you need to pass to graph.invoke():

import pandas as pd

# Prepare kline_data from a DataFrame
df = pd.read_csv("btc_15min.csv")
kline_data = df[["Datetime", "Open", "High", "Low", "Close"]].to_dict(orient="list")

initial_state = {
    # Required inputs
    "kline_data": kline_data,
    "time_frame": "15min",
    "stock_name": "BTC-USD",

    # Required placeholders
    "analysis_results": None,
    "messages": [],
}

You can pre-populate pattern_image or trend_image in initial_state to skip the chart generation tool call in those agents. This is useful when you have already generated a chart externally or want to reuse a chart from a previous run.

Reading the final state

After graph.invoke() returns, the state dict contains all populated fields:

import json

final_state = tg.graph.invoke(initial_state)

# Parse the trade decision
decision = json.loads(final_state["final_trade_decision"])
print(decision["decision"])           # "LONG" or "SHORT"
print(decision["justification"])
print(decision["risk_reward_ratio"])

# Read individual agent reports
print(final_state["indicator_report"])
print(final_state["pattern_report"])
print(final_state["trend_report"])

# Access raw indicator values
print(final_state["rsi"])
print(final_state["macd_hist"])

Type definition

from typing import Annotated, List, TypedDict
from langchain_core.messages import BaseMessage

class IndicatorAgentState(TypedDict):
    # Inputs
    kline_data: Annotated[dict, "OHLCV dictionary used for computing technical indicators"]
    time_frame: Annotated[str, "time period for k line data provided"]
    stock_name: Annotated[dict, "stock name for prompt"]

    # Indicator agent
    rsi: Annotated[List[float], "Relative Strength Index values"]
    macd: Annotated[List[float], "MACD line values"]
    macd_signal: Annotated[List[float], "MACD signal line values"]
    macd_hist: Annotated[List[float], "MACD histogram values"]
    stoch_k: Annotated[List[float], "Stochastic Oscillator %K values"]
    stoch_d: Annotated[List[float], "Stochastic Oscillator %D values"]
    roc: Annotated[List[float], "Rate of Change values"]
    willr: Annotated[List[float], "Williams %R values"]
    indicator_report: Annotated[str, "Final indicator agent summary report"]

    # Pattern agent
    pattern_image: Annotated[str, "Base64-encoded K-line chart"]
    pattern_image_filename: Annotated[str, "Local file path to saved K-line chart image"]
    pattern_image_description: Annotated[str, "Brief description of the generated K-line image"]
    pattern_report: Annotated[str, "Final pattern agent summary report"]

    # Trend agent
    trend_image: Annotated[str, "Base64-encoded trend-annotated candlestick chart"]
    trend_image_filename: Annotated[str, "Local file path to saved trendline-enhanced chart"]
    trend_image_description: Annotated[str, "Description including support/resistance characteristics"]
    trend_report: Annotated[str, "Final trend analysis summary"]

    # Decision agent
    analysis_results: Annotated[str, "Computed result of the analysis or decision"]
    messages: Annotated[List[BaseMessage], "List of chat messages used in LLM prompt construction"]
    decision_prompt: Annotated[str, "Decision prompt for reflection"]
    final_trade_decision: Annotated[str, "Final LONG or SHORT decision JSON"]