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

> Discover how TradingAgents-CN streams real-time news. Explore data aggregation, normalization, and urgency ranking with the RealtimeNewsAggregator for financial insights.

- Repository: [hsliuping/TradingAgents-CN](https://github.com/hsliuping/tradingagents-cn)
- Tags: deep-dive
- Published: 2026-02-16

---

**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`](https://github.com/hsliuping/TradingAgents-CN/blob/main/tradingagents/dataflows/news/realtime_news.py). This high-level orchestrator performs market detection and source prioritization:

```python
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`](https://github.com/hsliuping/TradingAgents-CN/blob/main/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`](https://github.com/hsliuping/TradingAgents-CN/blob/main/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):

```python
@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`](https://github.com/hsliuping/TradingAgents-CN/blob/main/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`](https://github.com/hsliuping/TradingAgents-CN/blob/main/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`](https://github.com/hsliuping/TradingAgents-CN/blob/main/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`](https://github.com/hsliuping/TradingAgents-CN/blob/main/tradingagents/config/runtime_settings.py) and centralized logging via [`tradingagents/utils/logging_manager.py`](https://github.com/hsliuping/TradingAgents-CN/blob/main/tradingagents/utils/logging_manager.py).

## Code Examples

### Direct API Usage

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

```python
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:

```python
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:

```python
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`](https://github.com/hsliuping/TradingAgents-CN/blob/main/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`](https://github.com/hsliuping/TradingAgents-CN/blob/main/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`](https://github.com/hsliuping/TradingAgents-CN/blob/main/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`](https://github.com/hsliuping/TradingAgents-CN/blob/main/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`](https://github.com/hsliuping/TradingAgents-CN/blob/main/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.