# How to Configure and Use the Unified News Tool for Stock Analysis in TradingAgents-CN

> Learn to configure and use the unified news tool for AI driven stock analysis in TradingAgents-CN. Automatically fetch relevant news for A-share, HK, and US markets.

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

---

**The unified news tool (`create_unified_news_tool`) is a high-level wrapper that automatically detects whether a stock trades on A-share, Hong Kong, or U.S. markets and fetches the most relevant news using market-specific data sources.**

The `TradingAgents-CN` repository provides this tool in [`tradingagents/tools/unified_news_tool.py`](https://github.com/hsliuping/TradingAgents-CN/blob/main/tradingagents/tools/unified_news_tool.py) to simplify multi-market stock analysis. Instead of manually selecting different news APIs for Chinese, Hong Kong, and American equities, you can use a single function call that handles market detection, source selection, and result formatting automatically.

## What Is the Unified News Tool?

The unified news tool consists of two core components:

1. **`UnifiedNewsAnalyzer`** – A class that encapsulates the logic for identifying stock markets and routing requests to the appropriate data sources.
2. **`create_unified_news_tool`** – A factory function that instantiates the analyzer with a `Toolkit` and returns a callable function (`get_stock_news_unified`) that language models can invoke.

According to the source code in [`tradingagents/tools/unified_news_tool.py`](https://github.com/hsliuping/TradingAgents-CN/blob/main/tradingagents/tools/unified_news_tool.py), the tool supports three market categories:

- **A-share (中国)** – Chinese domestic stocks (e.g., `000001`, `600519`)
- **Hong Kong** – HKEX-listed equities (e.g., `00700`, `09988`)
- **U.S.** – American exchanges (e.g., `AAPL`, `TSLA`)

## How the Unified News Tool Works

The tool operates through a six-step pipeline that handles everything from market detection to result formatting.

### Step 1: Toolkit Injection

The `create_unified_news_tool` function receives a `Toolkit` instance that bundles all lower-level news sources (Google News, Finnhub, East Money, etc.). This toolkit is defined in [`tradingagents/agents/utils/agent_utils.py`](https://github.com/hsliuping/TradingAgents-CN/blob/main/tradingagents/agents/utils/agent_utils.py) at lines 42-52.

```python
from tradingagents.agents.utils.agent_utils import Toolkit

# Toolkit bundles get_google_news, get_realtime_stock_news, get_finnhub_news, etc.

toolkit = Toolkit(config={"online_tools": True})
unified_tool = create_unified_news_tool(toolkit)

```

### Step 2: Tool Creation and Naming

The factory function returns a callable with the name `get_stock_news_unified`, which the LLM uses to identify the tool during function calling. This is implemented at lines 552-557 in [`unified_news_tool.py`](https://github.com/hsliuping/TradingAgents-CN/blob/main/unified_news_tool.py).

### Step 3: Stock Type Detection

Inside `UnifiedNewsAnalyzer.get_stock_news_unified`, the `_identify_stock_type` method uses regular expressions to classify the ticker:

- **A-share**: 6-digit codes starting with `600`, `601`, `603`, `000`, `002`, `300`
- **Hong Kong**: 5-digit codes starting with `0` or `1` (e.g., `00700`)
- **U.S.**: Alphabetic tickers (e.g., `AAPL`)

This logic appears at lines 67-90 in [`unified_news_tool.py`](https://github.com/hsliuping/TradingAgents-CN/blob/main/unified_news_tool.py).

### Step 4: Data Source Selection

Based on the detected market, the analyzer routes to market-specific private methods:

- **A-share** → `_get_a_share_news`: Checks database cache first, then falls back to 东方财富 (East Money) real-time API, Google News Chinese, and OpenAI summarization.
- **Hong Kong** → `_get_hk_share_news`: Uses Google News Chinese, OpenAI, and real-time feeds.
- **U.S.** → `_get_us_share_news`: Prioritizes OpenAI, then Google News English, then Finnhub.

These flows are documented at lines 82-115 (A-share), 67-84 (HK), and 13-19 (US) in [`unified_news_tool.py`](https://github.com/hsliuping/TradingAgents-CN/blob/main/unified_news_tool.py).

### Step 5: Formatting and Model-Specific Handling

The `_format_news_result` method (lines 59-84) converts raw news into markdown-styled reports. If the `model_info` parameter indicates a Google/Gemini model, a special length-control routine trims content to stay within token limits.

### Step 6: Return to Agent

The formatted result is returned to the caller, typically the News Analyst agent defined in [`tradingagents/agents/analysts/news_analyst.py`](https://github.com/hsliuping/TradingAgents-CN/blob/main/tradingagents/agents/analysts/news_analyst.py).

## Configuration Requirements

To use the unified news tool effectively, you must enable online tools and optionally configure research depth.

### Enable Online Tools

By default, `DEFAULT_CONFIG` disables remote calls. You must explicitly set `online_tools` to `True`:

```python
from tradingagents.default_config import DEFAULT_CONFIG
from tradingagents.agents.utils.agent_utils import Toolkit

config = DEFAULT_CONFIG.copy()
config["online_tools"] = True  # Allow external API calls

toolkit = Toolkit(config=config)
unified_news = create_unified_news_tool(toolkit)

```

This pattern appears in the integration test at [`tests/test_unified_news_tool.py`](https://github.com/hsliuping/TradingAgents-CN/blob/main/tests/test_unified_news_tool.py) (lines 30-36).

### Model Information Parameter

Pass the `model_info` string (e.g., `"deepseek-chat"`, `"gemini-pro"`, `"gpt-4"`) when calling the tool. This triggers Google-specific length handling if the model identifier contains "gemini" or "google".

### Maximum News Count

The `max_news` parameter defaults to 10. You can increase this value, though the tool respects source-specific limits to prevent API rate limiting.

## Code Examples

### Standalone Usage

Fetch news for stocks across three different markets using a single function:

```python
from tradingagents.tools.unified_news_tool import create_unified_news_tool
from tradingagents.agents.utils.agent_utils import Toolkit

# Initialize toolkit with online access

toolkit = Toolkit(config={"online_tools": True})

# Create the unified news function

get_stock_news_unified = create_unified_news_tool(toolkit)
get_stock_news_unified.name = "get_stock_news_unified"

# A-share example: 平安银行 (Ping An Bank)

a_share_report = get_stock_news_unified(
    stock_code="000001",
    max_news=5,
    model_info="deepseek-chat"
)

# Hong Kong example: 腾讯控股 (Tencent)

hk_report = get_stock_news_unified(
    stock_code="00700",
    max_news=5,
    model_info="gemini-pro"
)

# US example: Apple Inc.

us_report = get_stock_news_unified(
    stock_code="AAPL",
    max_news=5,
    model_info="gpt-4"
)

print("A-share News:\n", a_share_report)
print("HK News:\n", hk_report)
print("US News:\n", us_report)

```

### Integration with News Analyst Agent

Use the tool within the agent workflow as implemented in the library:

```python
from tradingagents.agents.analysts.news_analyst import create_news_analyst
from tradingagents.agents.utils.agent_utils import Toolkit
from tradingagents.llm_adapters.deepseek_adapter import ChatDeepSeek

# Setup

toolkit = Toolkit(config={"online_tools": True})
llm = ChatDeepSeek(model="deepseek-chat", temperature=0.1)

# Create analyst with unified tool pre-configured

news_analyst = create_news_analyst(llm, toolkit)

# Execute analysis

state = {
    "company_of_interest": "AAPL",
    "trade_date": "2025-07-28",
    "messages": []
}
result = news_analyst(state)

# Extract final report

final_report = result["messages"][-1].content
print(final_report)

```

This mirrors the implementation in [`tradingagents/agents/analysts/news_analyst.py`](https://github.com/hsliuping/TradingAgents-CN/blob/main/tradingagents/agents/analysts/news_analyst.py) around lines 100-110.

### Adjusting Research Depth

Control data granularity using the `research_depth` configuration:

```python
from tradingagents.default_config import DEFAULT_CONFIG
from tradingagents.agents.utils.agent_utils import Toolkit

cfg = DEFAULT_CONFIG.copy()
cfg.update({
    "online_tools": True,
    "research_depth": "快速"  # Options: 快速, 基础, 标准, 深度, 全面

})

toolkit = Toolkit(config=cfg)
unified_tool = create_unified_news_tool(toolkit)

# Fetches minimal data for quick analysis

news = unified_tool(stock_code="600519", max_news=5, model_info="gpt-4")

```

## Key Implementation Files

| File | Purpose | Location |
|------|---------|----------|
| [`unified_news_tool.py`](https://github.com/hsliuping/TradingAgents-CN/blob/main/unified_news_tool.py) | Core implementation of `UnifiedNewsAnalyzer` and `create_unified_news_tool` | [`tradingagents/tools/unified_news_tool.py`](https://github.com/hsliuping/TradingAgents-CN/blob/main/tradingagents/tools/unified_news_tool.py) |
| [`news_analyst.py`](https://github.com/hsliuping/TradingAgents-CN/blob/main/news_analyst.py) | Agent that integrates the unified tool into LLM workflows | [`tradingagents/agents/analysts/news_analyst.py`](https://github.com/hsliuping/TradingAgents-CN/blob/main/tradingagents/agents/analysts/news_analyst.py) |
| [`agent_utils.py`](https://github.com/hsliuping/TradingAgents-CN/blob/main/agent_utils.py) | Defines `Toolkit` class that bundles lower-level news sources | [`tradingagents/agents/utils/agent_utils.py`](https://github.com/hsliuping/TradingAgents-CN/blob/main/tradingagents/agents/utils/agent_utils.py) |
| [`test_unified_news_tool.py`](https://github.com/hsliuping/TradingAgents-CN/blob/main/test_unified_news_tool.py) | Integration tests demonstrating end-to-end usage | [`tests/test_unified_news_tool.py`](https://github.com/hsliuping/TradingAgents-CN/blob/main/tests/test_unified_news_tool.py) |
| [`default_config.py`](https://github.com/hsliuping/TradingAgents-CN/blob/main/default_config.py) | Contains `DEFAULT_CONFIG` with `online_tools` flag | [`tradingagents/default_config.py`](https://github.com/hsliuping/TradingAgents-CN/blob/main/tradingagents/default_config.py) |

## Summary

- The **unified news tool** (`create_unified_news_tool`) provides a single interface for fetching stock news across A-share, Hong Kong, and U.S. markets.
- It automatically **detects market type** using regex patterns on the ticker symbol and routes to appropriate data sources (东方财富, Google News, Finnhub, OpenAI).
- **Configuration requires** setting `online_tools=True` in the `Toolkit` config to enable external API calls.
- The tool is **model-aware**: passing `model_info` triggers special handling for Google/Gemini token limits.
- Integration with the **News Analyst agent** follows the pattern shown in [`news_analyst.py`](https://github.com/hsliuping/TradingAgents-CN/blob/main/news_analyst.py), where the tool is created, named, and passed to the LLM's tool list.

## Frequently Asked Questions

### How does the unified news tool determine which market a stock belongs to?

The tool uses the `_identify_stock_type` method in [`unified_news_tool.py`](https://github.com/hsliuping/TradingAgents-CN/blob/main/unified_news_tool.py) (lines 67-90) to analyze the ticker format. A-share codes are identified as 6-digit numbers starting with specific prefixes (600, 601, 603, 000, 002, 300). Hong Kong stocks match 5-digit codes beginning with 0 or 1. U.S. tickers are detected as alphabetic strings. Based on this classification, the tool routes to `_get_a_share_news`, `_get_hk_share_news`, or `_get_us_share_news`.

### Why do I get empty results when using the unified news tool?

Empty results typically occur when `online_tools` is disabled in the configuration. The `Toolkit` class defaults to `online_tools=False` in `DEFAULT_CONFIG`, which prevents external API calls to Google News, Finnhub, or 东方财富. To fix this, explicitly set `config["online_tools"] = True` when initializing the `Toolkit`. Additionally, ensure you have valid API keys configured for the underlying data sources (Finnhub, OpenAI, etc.) in your environment variables.

### Can I use the unified news tool outside of the News Analyst agent?

Yes, the tool is designed to work both standalone and within agent workflows. You can import `create_unified_news_tool` directly from `tradingagents.tools.unified_news_tool` and invoke it with a `Toolkit` instance. This is demonstrated in the integration tests at [`tests/test_unified_news_tool.py`](https://github.com/hsliuping/TradingAgents-CN/blob/main/tests/test_unified_news_tool.py) (lines 30-62). When using standalone, remember to manually set the `.name` attribute if you plan to pass the function to an LLM's tool registry.

### How does the tool handle token limits for different LLM providers?

The tool accepts a `model_info` parameter that triggers model-specific formatting in `_format_news_result` (lines 59-84 of [`unified_news_tool.py`](https://github.com/hsliuping/TradingAgents-CN/blob/main/unified_news_tool.py)). When `model_info` contains "gemini" or "google", the tool activates a length-control routine that truncates content to stay within Gemini's context window limits. For other models like DeepSeek or GPT-4, the full content is returned unless the underlying API imposes its own limits. Always pass the correct model identifier to ensure optimal formatting.