12 KiB

Raw Blame History

Integrated Agentic Architecture - Implementation Guide

Overview

The screening and pump detection agents have been fully integrated into your langgraph-based agentic architecture. They now work alongside all existing agents (market analyst, bull/bear researchers, traders, risk managers, etc.) as part of a unified multi-agent system.

Architecture

Agent Hierarchy

START
  ├─ Screening Agent (Optional)
  │  ├─ Uses: Market Movers, Earnings Calendar, Trending Social, Insider Activity
  │  └─ Output: Stock candidates for deeper analysis
  │
  ├─ Pump Detection Agent (Optional)
  │  ├─ Uses: Volume Spike, Price Acceleration, Social Sentiment, RSI, Catalysts
  │  └─ Output: Pump probability score (0-100)
  │
  ├─ Market Analyst
  │  └─ Technical analysis: RSI, MACD, Moving Averages
  │
  ├─ Social Media Analyst
  │  └─ Sentiment analysis: Reddit, Twitter, StockTwits
  │
  ├─ News Analyst
  │  └─ News sentiment: Recent news, insider activity
  │
  ├─ Fundamentals Analyst
  │  └─ Financial analysis: P/E, Growth, Statements
  │
  ├─ Bull Researcher
  │  └─ Bullish thesis based on all findings
  │
  ├─ Bear Researcher
  │  └─ Bearish thesis based on all findings
  │
  ├─ Research Manager
  │  └─ Synthesizes debate into investment recommendation
  │
  ├─ Trader
  │  └─ Creates trading plan (entry, stop, targets)
  │
  └─ Risk Managers (Risky/Neutral/Safe)
     └─ Final risk-adjusted decision
END

Files Modified

tradingagents/agents/screening_agent.py
- Updated to follow langgraph pattern
- Exports create_screening_agent() function
- Integrates with agent state
tradingagents/agents/pump_detection_agent.py
- Updated to follow langgraph pattern
- Exports create_pump_detection_agent() function
- Integrates with agent state
tradingagents/agents/init.py
- Added exports for screening and pump detection agents
tradingagents/graph/trading_graph.py
- Added pump detection tool imports
- Added screening and pump detection tool nodes
- Added include_screening parameter
- Added include_pump_detection parameter
tradingagents/graph/setup.py
- Updated setup_graph() to accept new agent flags
- Integrated agents into graph flow
- Added conditional edges for optional agents

Usage

Basic Usage - All Agents

from tradingagents.graph.trading_graph import TradingAgentsGraph

# Create graph with ALL agents (screening, pump detection, analysts, researchers, traders)
graph = TradingAgentsGraph(
    selected_analysts=["market", "social", "news", "fundamentals"],
    include_screening=True,
    include_pump_detection=True,
)

# Run analysis
ticker = "NVDA"
trade_date = "2025-12-05"
final_state, signal = graph.propagate(ticker, trade_date)

# Access results
print(f"Pump Report: {final_state.get('pump_report')}")
print(f"Screening Report: {final_state.get('screening_report')}")
print(f"Final Decision: {final_state.get('final_trade_decision')}")

Usage - Pump Detection Only

graph = TradingAgentsGraph(
    include_pump_detection=True,
    # Skip screening, but keep analysis agents
    selected_analysts=["market", "social", "news", "fundamentals"],
)

final_state, signal = graph.propagate("NVDA", "2025-12-05")

Usage - Screening Only

graph = TradingAgentsGraph(
    include_screening=True,
    selected_analysts=["market"],  # Minimal analysis
)

# Get screening recommendations
screening_output = final_state.get('screening_report')

Usage - Original Graph (No Screening/Pump Detection)

graph = TradingAgentsGraph(
    # Defaults: include_screening=False, include_pump_detection=False
    selected_analysts=["market", "social", "news", "fundamentals"],
)

final_state, signal = graph.propagate("NVDA", "2025-12-05")

Agent Descriptions

Screening Agent

Purpose: Scans the market for interesting stock candidates
Tools: get_market_movers, get_earnings_calendar, get_insider_transactions, get_indicators, get_trending_social
Output: Comma-separated list of recommended tickers
When to Use: First step in market scanning
Enabled By: include_screening=True

Pump Detection Agent

Purpose: Analyzes stocks for pre-pump signals
Tools: detect_volume_spike, detect_price_acceleration, detect_social_sentiment_surge, detect_oversold_bounce, detect_catalyst_event, calculate_pump_score
Output: Pump probability score (0-100) with risk assessment
When to Use: For momentum/swing trading opportunities
Enabled By: include_pump_detection=True

Market Analyst

Purpose: Technical analysis
Tools: get_stock_data, get_indicators
Output: Technical trends and signals

Purpose: Social sentiment analysis
Tools: get_news (for social mentions)
Output: Sentiment report from social media

News Analyst

Purpose: News and insider sentiment
Tools: get_news, get_global_news, get_insider_sentiment, get_insider_transactions
Output: News impact and insider activity report

Fundamentals Analyst

Purpose: Company fundamental analysis
Tools: get_fundamentals, get_balance_sheet, get_cashflow, get_income_statement
Output: Financial health and growth analysis

Bull Researcher

Purpose: Builds bullish investment case
Input: All analyst reports
Output: Bullish thesis and recommendations

Bear Researcher

Purpose: Builds bearish investment case
Input: All analyst reports
Output: Bearish thesis and concerns

Research Manager

Purpose: Synthesizes bull/bear debate
Input: Bull and bear perspectives
Output: Final investment recommendation (BUY/HOLD/SELL)

Trader

Purpose: Creates trading execution plan
Input: Investment recommendation
Output: Entry price, stop loss, profit targets, position sizing

Risk Managers

Purpose: Final risk assessment
Input: Trading plan
Output: Risk-adjusted final decision

State Keys

The unified AgentState contains:

{
    "messages": [...],                      # Conversation history
    "company_of_interest": "NVDA",          # Ticker symbol
    "trade_date": "2025-12-05",             # Analysis date
    
    # Optional agent outputs
    "screening_report": "...",              # From Screening Agent
    "pump_report": "...",                   # From Pump Detection Agent
    
    # Analyst outputs
    "market_report": "...",                 # From Market Analyst
    "sentiment_report": "...",              # From Social Analyst
    "news_report": "...",                   # From News Analyst
    "fundamentals_report": "...",           # From Fundamentals Analyst
    
    # Debate and decision
    "investment_debate_state": {...},       # Bull vs Bear debate
    "trader_investment_plan": "...",        # From Trader
    "risk_debate_state": {...},             # Risk assessment
    "final_trade_decision": "...",          # Final recommendation
}

Tool Nodes in Graph

Tools Available by Node Type

market_tools: get_stock_data, get_indicators

social_tools: get_news

news_tools: get_news, get_global_news, get_insider_sentiment, get_insider_transactions

fundamentals_tools: get_fundamentals, get_balance_sheet, get_cashflow, get_income_statement

screening_tools: get_market_movers, get_earnings_calendar, get_insider_transactions, get_indicators, get_trending_social

pump_detection_tools: detect_volume_spike, detect_price_acceleration, detect_social_sentiment_surge, detect_oversold_bounce, detect_catalyst_event, calculate_pump_score

Conditional Logic

The graph uses conditional edges to:

Skip screening/pump detection if not enabled
Route to next agent after each analysis
Continue debate between bull/bear researchers
Finalize decision through risk managers

Integration Points

Adding Custom Agents

To add your own agent to the architecture:

Create agent function in tradingagents/agents/custom_agent.py:

def create_custom_agent(llm):
    def custom_agent_node(state):
        # Your agent logic
        return {"messages": state["messages"] + [result]}
    return custom_agent_node

Export from __init__.py:

from .custom_agent import create_custom_agent
__all__ = [..., "create_custom_agent"]

Add to graph setup:

graph_setup.setup_graph(
    selected_analysts=["market"],
    include_custom_agent=True,  # Add your flag
)

Adding Custom Tools

To add tools available to all agents:

Create tool in tradingagents/agents/utils/:

@tool
def my_custom_tool(...):
    """Tool description"""
    return result

Add to tool node in trading_graph.py:

def _create_tool_nodes(self):
    return {
        "market": ToolNode([get_stock_data, my_custom_tool]),
        ...
    }

Testing

Run Integrated Demo

python integrated_agents_demo.py

Shows architecture overview and usage examples.

Run Full Analysis

from tradingagents.graph.trading_graph import TradingAgentsGraph

graph = TradingAgentsGraph(
    include_screening=True,
    include_pump_detection=True,
    selected_analysts=["market", "social", "news", "fundamentals"],
    debug=True,  # Enable debug mode to see agent thinking
)

final_state, signal = graph.propagate("NVDA", "2025-12-05")

Performance Considerations

Agent Execution Time: Each agent runs sequentially, adding ~5-30 seconds per agent
Total Time Estimate:
- Screening: 10-20 seconds
- Pump Detection: 10-20 seconds
- Each Analyst: 10-20 seconds
- Researchers/Traders: 10-20 seconds
- Total: 1-4 minutes for full analysis
API Calls: Each agent may call multiple APIs (yfinance, Alpha Vantage, etc.)
Optimization: Set debug=False to skip verbose output

Troubleshooting

"Agent not found" Error

Check agent is exported from agents/__init__.py
Verify parameter name matches (e.g., include_pump_detection)

Missing Tool Error

Ensure tool node is created in _create_tool_nodes()
Verify tool is imported at top of file

State Key Error

Agent results are stored with specific keys (e.g., pump_report)
Check key name matches agent output

API Errors

Ensure API keys are set (Alpha Vantage, etc.)
Fall back to yfinance (free, no key needed)
Check internet connection

Best Practices

Start Simple: Enable one agent at a time to debug
Use Debug Mode: Set debug=True to see agent reasoning
Monitor Performance: Track execution time, adjust as needed
Validate Results: Check outputs make sense before trading
Combine Signals: Use multiple agent perspectives for better decisions
Document Decisions: Log final recommendations for analysis

Summary

You now have a fully integrated multi-agent system where:

✅ Screening Agent finds opportunities market-wide ✅ Pump Detection Agent spots pre-pump signals ✅ Analysis Agents provide technical, social, news, fundamental insights ✅ Research Agents debate bull vs bear perspectives ✅ Trading Agent creates execution plans ✅ Risk Managers ensure proper risk management ✅ All agents share state and build on each other's analysis ✅ Flexible architecture lets you enable/disable agents as needed

This creates a sophisticated multi-perspective trading analysis system that combines:

Market screening
Momentum detection
Technical analysis
Social sentiment
News analysis
Fundamentals
Debate and consensus
Risk management

All working together in a unified langgraph-based agentic framework!

12 KiB Raw Blame History