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

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 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, 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 at lines 42-52.

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.

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.

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.

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.

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:

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 (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:

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:

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 around lines 100-110.

Adjusting Research Depth

Control data granularity using the research_depth configuration:

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	Core implementation of UnifiedNewsAnalyzer and create_unified_news_tool	tradingagents/tools/unified_news_tool.py
news_analyst.py	Agent that integrates the unified tool into LLM workflows	tradingagents/agents/analysts/news_analyst.py
agent_utils.py	Defines Toolkit class that bundles lower-level news sources	tradingagents/agents/utils/agent_utils.py
test_unified_news_tool.py	Integration tests demonstrating end-to-end usage	tests/test_unified_news_tool.py
default_config.py	Contains DEFAULT_CONFIG with online_tools flag	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, 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 (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 (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). 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.

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