TradingAgents Debug Mode and Trace Logging: A Complete Troubleshooting Guide

Enable debug mode in TradingAgents by setting debug=True when instantiating TradingAgentsGraph to capture full LangGraph execution traces, pretty-print intermediate messages, and persist detailed JSON logs for troubleshooting multi-agent trading workflows.

The TradingAgents framework provides robust debugging capabilities that allow developers to inspect every step of complex multi-agent trading decisions. By activating debug mode and trace logging, you can monitor the complete LangGraph pipeline execution, from initial market analysis through final trade decisions, using implementations found in tradingagents/graph/trading_graph.py and cli/main.py.

How Debug Mode Works in TradingAgents

When debug=True is passed to the TradingAgentsGraph constructor, the framework switches from standard invocation to streaming mode with comprehensive trace collection. Instead of calling self.graph.invoke() directly, the propagate method iterates over self.graph.stream() and captures every chunk emitted during the graph execution.

The core logic resides in tradingagents/graph/trading_graph.py. When debug mode is active, the method initializes an empty trace list and populates it with every chunk from the stream. Each chunk's final message is immediately pretty-printed to the console, providing real-time visibility into agent communications and tool calls.

The Debug Execution Path in trading_graph.py

The following implementation shows the conditional logic that switches between standard and debug execution modes:

if self.debug:
    # Debug mode with tracing

    trace = []
    for chunk in self.graph.stream(init_agent_state, **args):
        if len(chunk["messages"]) == 0:
            pass
        else:
            chunk["messages"][-1].pretty_print()
            trace.append(chunk)

    final_state = trace[-1]
else:
    # Standard mode without tracing

    final_state = self.graph.invoke(init_agent_state, **args)

When debug mode is enabled, every graph step is streamed, printed, and stored in memory, while standard mode runs silently with only the final state returned.

Enabling Debug Mode and Trace Logging

You can activate debug mode through three primary interfaces: programmatic instantiation, the interactive CLI, or standalone scripts. Each method provides the same underlying trace collection while adapting to different workflow requirements.

Programmatic Debugging

For ad-hoc analysis or automated testing, instantiate TradingAgentsGraph with debug=True and a custom configuration:

from tradingagents.graph.trading_graph import TradingAgentsGraph
from tradingagents.default_config import DEFAULT_CONFIG

# Optional: customize LLM providers or debate rounds

config = DEFAULT_CONFIG.copy()
config["max_debate_rounds"] = 2

# Enable debug mode

graph = TradingAgentsGraph(debug=True, config=config)

# Execute with live trace output

final_state, decision = graph.propagate("AAPL", "2024-04-30")
print("Decision:", decision)

Key points:

• debug=True activates streaming mode and live pretty-printing
• The returned final_state contains structured outputs including agent reports and debate states
• The complete trace remains accessible within the graph instance for post-run inspection

CLI-Driven Debug Run

The interactive command-line interface automatically enables debug mode when constructing the graph. Located in cli/main.py, this interface builds the graph with debug=True and manages trace collection automatically.

# Launch the interactive CLI with built-in debug tracing

python -m tradingagents.cli.main

During execution, the CLI:

• Displays a live Rich layout showing real-time agent statuses
• Accumulates streamed chunks in a local trace variable
• Extracts final_state = trace[-1] upon completion
• Writes comprehensive JSON logs to eval_results/<ticker>/TradingAgentsStrategy_logs/

One-Off Script Execution

The repository includes a minimal example in main.py demonstrating standalone debug usage:

from tradingagents.graph.trading_graph import TradingAgentsGraph
from tradingagents.default_config import DEFAULT_CONFIG

config = DEFAULT_CONFIG.copy()
config["deep_think_llm"] = "gpt-5-mini"
config["quick_think_llm"] = "gpt-5-mini"

ta = TradingAgentsGraph(debug=True, config=config)

# Stream with trace logging enabled

_, decision = ta.propagate("NVDA", "2024-05-10")
print(decision)

Running this script prints step-by-step execution traces to the console and stores the final state in the evaluation results directory.

Trace Persistence and Log Locations

Debug mode generates persistent logs in specific directory structures for post-run analysis. The TradingAgentsGraph._log_state method handles JSON serialization of the complete execution history.

JSON State Logs

In debug mode, the framework writes accumulated states to:

with open(
    f"eval_results/{self.ticker}/TradingAgentsStrategy_logs/full_states_log_{trade_date}.json",
    "w",
    encoding="utf-8",
) as f:
    json.dump(self.log_states_dict, f, indent=4)

This file contains the full log_states_dict including the final state with all agent deliberations, tool outputs, and intermediate reasoning steps.

CLI Message Logs

When using the interactive CLI, additional logging occurs through decorators defined around line 64 in cli/main.py. This generates a message_tool.log file recording every message and tool call emitted during the streamed execution, complementing the structured JSON output with human-readable text logs.

Summary

• Debug activation: Set debug=True in TradingAgentsGraph constructor to enable streaming execution and trace collection
• Real-time visibility: The propagate method in tradingagents/graph/trading_graph.py calls pretty_print() on every chunk's final message when debug mode is active
• Trace storage: All streamed chunks are appended to an in-memory trace list, with final_state = trace[-1] providing the complete decision context
• Log locations: JSON state logs write to eval_results/{ticker}/TradingAgentsStrategy_logs/, while the CLI generates additional message_tool.log files
• Multiple interfaces: Debug mode works identically across programmatic API, interactive CLI (cli/main.py), and standalone scripts (main.py)

Frequently Asked Questions

How do I enable debug mode in TradingAgents without using the CLI?

Instantiate the TradingAgentsGraph class with the debug=True parameter in your Python script. Import the class from tradingagents.graph.trading_graph, create your configuration dictionary, and pass both to the constructor before calling propagate().

What is the difference between debug mode and standard mode?

In standard mode, TradingAgentsGraph.propagate() calls self.graph.invoke() and returns only the final state. In debug mode, it streams execution via self.graph.stream(), captures every chunk in a trace list, pretty-prints intermediate messages, and extracts the final state from the last trace element.

Where are the debug logs stored after running TradingAgents?

Debug logs are persisted in two locations: structured JSON files containing full state histories are written to eval_results/{ticker}/TradingAgentsStrategy_logs/full_states_log_{trade_date}.json, and when using the CLI, text-based message logs are saved as message_tool.log in the same directory.

Can I customize which components are traced in debug mode?

While the built-in debug mode captures all LangGraph stream chunks, you can modify the logging behavior by adjusting the configuration dictionary passed to TradingAgentsGraph. The default_config.py file provides the base configuration that can be overridden to adjust LLM callbacks and verbosity levels, though the core trace collection logic remains consistent across all debug-enabled runs.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}