How Real-Time News Streaming Works in TradingAgents-CN: A Technical Deep Dive

The real-time news streaming system in TradingAgents-CN aggregates live financial data from multiple APIs (Finnhub, Alpha Vantage, NewsAPI, and Chinese sources), normalizes it into a unified NewsItem format, and delivers urgency-ranked, de-duplicated markdown reports through the RealtimeNewsAggregator class.

Real-time news streaming is essential for quantitative trading systems that react to market-moving events. In the TradingAgents-CN repository, this capability is implemented through a layered architecture that prioritizes data freshness, source diversity, and intelligent filtering. The system is designed to handle multiple market types—A-shares, Hong Kong, and US equities—through a unified interface.

Market-Type Routing and Orchestration

The entry point for real-time news streaming is the get_realtime_stock_news function in tradingagents/dataflows/news/realtime_news.py. This high-level orchestrator performs market detection and source prioritization:

def get_realtime_stock_news(ticker: str, curr_date: str, hours_back: int = 6) -> str:
    # ① Determine market (A-share, HK, US) via suffix check

    # ② Try A-share specific source (AKShare → 东方财富) first

    # ③ If that fails or not A-share → instantiate RealtimeNewsAggregator

    # ④ Return the formatted markdown report

The function inspects the ticker suffix to detect market type. For A-share tickers ending in .SH or .SZ, it first attempts to fetch from 东方财富 (East Money) via the AKShare integration. If this returns no data, or when processing Hong Kong or US tickers, the system falls back to the generic RealtimeNewsAggregator class.

The RealtimeNewsAggregator Class

The core real-time news streaming engine is the RealtimeNewsAggregator class, which implements the get_realtime_stock_news method (lines 50-85 in realtime_news.py). This class manages a multi-stage pipeline: data ingestion, normalization, enrichment, and formatting.

Multi-Source Data Ingestion

The aggregator pulls from four distinct provider categories through private helper methods, each implementing failover logic:

Helper	Provider	Priority	Implementation
_get_finnhub_realtime_news	Finnhub (company-news endpoint)	1st	Lines 47-71
_get_alpha_vantage_news	Alpha Vantage (NEWS_SENTIMENT)	2nd	Lines 97-123
_get_newsapi_news	NewsAPI.org (search-by-ticker)	3rd	Lines 148-176
_get_chinese_finance_news	东方财富 (AKShare), 财联社 RSS	4th	Lines 303-388

Each helper constructs a time window using hours_back and the repository-wide timezone configuration from tradingagents/config/runtime_settings.py. Requests include a custom User-Agent: TradingAgents-CN/1.0 header for source attribution.

Data Normalization and the NewsItem Dataclass

Raw responses from disparate APIs are normalized into a uniform NewsItem dataclass (defined at lines 25-34):

@dataclass
class NewsItem:
    title: str
    content: str
    source: str
    publish_time: datetime
    url: str
    urgency: str  # "high", "medium", "low"

    relevance: float  # 0.0 to 1.0

This normalization ensures that downstream components can process news from Finnhub, Alpha Vantage, or Chinese RSS feeds using identical logic.

Urgency Assessment and Relevance Scoring

The enrichment layer adds intelligence through two scoring mechanisms:

Urgency Assessment (_assess_news_urgency, lines 505-535):

• Scans concatenated title and content for keyword patterns
• High urgency: "breaking", "earnings", "突发", "公告"
• Medium urgency: "update", "market", "上涨"
• Returns categorical labels used for UI prioritization

Relevance Scoring (_calculate_relevance, lines 536-570):

• Exact ticker match: 1.0
• Company name synonym match: 0.8
• Numeric Chinese code match: 0.9
• Fallback: 0.3

These scores enable the system to surface the most pertinent market-moving news first.

De-duplication and Filtering

After merging results from all providers, _deduplicate_news (lines 71-104) performs quality control:

• Short-title filtering: Removes items with titles ≤ 10 characters (likely noise)
• Case-insensitive duplicate detection: Eliminates identical headlines across sources
• Logging: Reports duplicate removal statistics for monitoring

This ensures users receive a concise, non-redundant news stream even when multiple APIs report the same breaking story.

Report Generation and Formatting

The final stage converts processed NewsItem objects into human-readable markdown via format_news_report (lines 442-470). The output includes:

• Header: Ticker symbol and generation timestamp
• Urgency sections: High (🚨), Medium (📢), and Low priority buckets
• Data freshness badge: "excellent", "good", or "average" based on the age of the newest article
• Structured list: Titles, sources, timestamps, and URLs

This markdown report is the standard output returned to calling agents or UI components.

Integration with the Broader System

The real-time news streaming pipeline integrates with several downstream components:

• News Analyst Agent (tradingagents/agents/analysts/news_analyst.py): Consumes the markdown report for sentiment analysis and trading signal generation
• Unified News Tool (tradingagents/tools/unified_news_tool.py): Wraps the aggregator for external API usage and CLI access
• News Filter Integration (tradingagents/utils/news_filter_integration.py): Provides an optional enhancement layer that applies additional semantic filtering or local model scoring on top of the base real-time stream

The system also relies on shared utilities including timezone management from tradingagents/config/runtime_settings.py and centralized logging via tradingagents/utils/logging_manager.py.

Code Examples

Direct API Usage

For most use cases, the high-level function provides the simplest interface:

from tradingagents.dataflows.news.realtime_news import get_realtime_stock_news

# Retrieve a 6-hour real-time news feed for A-share "600036.SH"

report_md = get_realtime_stock_news(
    ticker="600036.SH",
    curr_date="2024-09-10",   # Used for Google fallback only

    hours_back=6
)

print(report_md)   # Markdown report ready for UI rendering

This approach automatically handles market detection, A-share prioritization, and fallback to the multi-source aggregator.

Manual Aggregator Control

For custom pipelines requiring direct access to raw NewsItem objects:

from tradingagents.dataflows.news.realtime_news import RealtimeNewsAggregator

agg = RealtimeNewsAggregator()
items = agg.get_realtime_stock_news(
    ticker="AAPL",   # US stock

    hours_back=4,
    max_news=5
)

for i, itm in enumerate(items, 1):
    print(f"{i}. [{itm.urgency.upper()}] {itm.title} ({itm.source})")
    print(f"   Published: {itm.publish_time.isoformat()}")
    print(f"   URL: {itm.url}\n")

This returns up to 5 NewsItem objects with pre-calculated urgency and relevance scores, suitable for custom filtering or storage.

Advanced Filtering Integration

To apply additional semantic filtering on top of the real-time stream:

from tradingagents.utils.news_filter_integration import apply_news_filtering_patches

# Obtain the enhanced realtime news function with built-in filtering

enhanced_fn = apply_news_filtering_patches()

# Call with filtering enabled

report = enhanced_fn(
    ticker="600519.SH",
    curr_date="2024-09-10",
    enable_filter=True,
    min_score=40,
    use_semantic=False,
    use_local_model=False
)

print(report)

This optional layer allows integration of local models or semantic scoring while maintaining the core real-time streaming capabilities.

Summary

• TradingAgents-CN implements real-time news streaming through a layered architecture centered on the RealtimeNewsAggregator class in tradingagents/dataflows/news/realtime_news.py.
• The system automatically detects market types (A-share, Hong Kong, US) and prioritizes Chinese financial portals for domestic tickers before falling back to international APIs.
• Data is sourced from four provider tiers: Finnhub, Alpha Vantage, NewsAPI, and Chinese-specific feeds (东方财富 via AKShare, 财联社 RSS).
• Every article is normalized into a NewsItem dataclass and enriched with urgency scoring (high/medium/low) and relevance calculations (0.0-1.0 scale).
• The pipeline includes de-duplication, short-title filtering, and markdown report generation with urgency-based sections and data freshness badges.
• Downstream integration points include the News Analyst agent, Unified News Tool, and optional semantic filtering via news_filter_integration.py.

Frequently Asked Questions

How does TradingAgents-CN handle different stock markets in the news retriever?

The system uses suffix detection to identify market types. For A-share tickers ending in .SH or .SZ, it first attempts to fetch from 东方财富 (East Money) via the AKShare integration in tradingagents/dataflows/providers/china/akshare.py. If no data is returned or the ticker belongs to Hong Kong or US markets, the system falls back to the RealtimeNewsAggregator class, which queries international providers like Finnhub and Alpha Vantage. This prioritization ensures Chinese domestic stocks receive the most relevant local financial news first.

What APIs does the real-time news streaming system use?

The RealtimeNewsAggregator implements a four-tier fallback strategy. It sequentially queries Finnhub (company news endpoint), Alpha Vantage (NEWS_SENTIMENT), NewsAPI.org (search-by-ticker), and Chinese-specific sources including 东方财富 via AKShare and 财联社 RSS feeds. Each provider is wrapped in a private helper method (_get_finnhub_realtime_news, _get_alpha_vantage_news, etc.) that handles HTTP requests with a custom User-Agent: TradingAgents-CN/1.0 header and timezone-aware time windows.

How does the system determine which news items are most urgent?

Urgency assessment occurs in the _assess_news_urgency method (lines 505-535 of realtime_news.py). The system scans the concatenated title and content for keyword patterns indicating breaking developments. High urgency keywords include "breaking", "earnings", "突发", and "公告", while medium urgency includes terms like "update" or "market". Each NewsItem receives an urgency label ("high", "medium", or "low") that determines its placement in the final markdown report, with high-urgency items marked with 🚨 symbols for immediate visibility.

Can I filter or customize the news output beyond the default settings?

Yes, the system provides multiple extension points. For basic customization, you can instantiate RealtimeNewsAggregator directly and adjust parameters like hours_back (time window) and max_news (result limit). For advanced filtering, the apply_news_filtering_patches function in tradingagents/utils/news_filter_integration.py returns an enhanced version of the news function that supports semantic scoring, local model integration, and minimum relevance thresholds (via min_score parameter). Additionally, the _deduplicate_news method can be overridden to customize short-title filtering (default removes titles ≤ 10 characters) and duplicate detection logic.

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