trading-agents-simplified

---
name: trading-agents
description: Multi-agent stock trading signal analysis framework with two-round debate mechanism. Triggered when users provide a stock ticker for investment analysis. Input a stock ticker, analyze through 7 SubAgents in 4 layers (Information Gathering → Opinion Formation → Two-Round Debate → Final Decision), output BUY/SELL/HOLD recommendation with rationale. Trigger phrases: "analyze this stock", "give me investment advice", "is this stock worth buying", "analyze XX stock", "stock investment analysis".
license: MIT
author: laigen
requires:
  env:
    - name: TUSHARE_TOKEN
      required: true
    - name: BRAVE_API_KEY
      required: false
  pip:
    - tushare>=1.3.0
    - pandas>=1.5.0
    - numpy>=1.21.0
---

# TradingAgents - Stock Trading Signal Analysis Assistant

Multi-agent collaborative stock trading signal analysis framework with **two-round debate mechanism**, inspired by the open-source TradingAgents project.

## Environment Requirements

### Required Environment Variables

| Variable | Required | Description |
|----------|:--------:|-------------|
| **TUSHARE_TOKEN** | ✅ | Tushare Pro API Token, get at: https://tushare.pro/register |
| **BRAVE_API_KEY** | ⚪ | Brave Search API Key (optional, for news search enhancement) |

### Python Dependencies

Install required packages before using this skill:

```bash
pip install tushare>=1.3.0 pandas>=1.5.0 numpy>=1.21.0
```

### Secure Configuration

> **Security Warning**: Do NOT paste your API tokens in chat messages.

**Set Environment Variables**

Before running this skill, ensure the following environment variables are set:

```bash
export TUSHARE_TOKEN=your_token_here
export BRAVE_API_KEY=your_brave_key_here  # optional
```

**Avoid**:
- Do NOT add tokens to `~/.bashrc`, `~/.zshrc`, or other shell config files
- Do NOT include tokens in reports or SubAgent communications
- Do NOT paste tokens in chat messages

### Side Effects

This skill will:
- **Write** reports to `~/.openclaw/workspace/memory/reports/trading-agents-*.md`
- **Connect** to Tushare Pro API (`api.tushare.pro`)
- **Use** web_search for news and sentiment data

No data is transmitted externally beyond these API calls.

## Security Rules

### Credential Protection

1. **Only read TUSHARE_TOKEN and BRAVE_API_KEY** from environment variables
2. **Never read other configuration files** (e.g., openclaw.json, .bashrc, etc.)
3. **Never include API keys or tokens** in:
   - SubAgent inter-communications
   - Generated reports
   - Any output files

### Report Content Rules

All generated reports and SubAgent communications **MUST NOT** contain:
- API keys (TUSHARE_TOKEN, BRAVE_API_KEY)
- Passwords or secrets
- Any credential values

If a SubAgent receives or generates content containing sensitive credentials, it must **redact** them before passing to other agents or writing to files.

## Workflow (4-Layer Architecture)

```
Input: Stock Ticker (e.g., 300750.SZ)
  ↓
┌─────────────────────────────────────────────────────┐
│  Layer 1: Information Gathering (Parallel)          │
│  ├─ SubAgent 1: Fundamental Analyst                 │
│  ├─ SubAgent 2: Market Analyst                      │
│  ├─ SubAgent 3: News Analyst                        │
│  └─ SubAgent 4: Social Media Analyst                │
└─────────────────────────────────────────────────────┘
  ↓
┌─────────────────────────────────────────────────────┐
│  Layer 2: Opinion Formation (Parallel)              │
│  ├─ SubAgent 5: Bull Researcher (Initial Report)    │
│  └─ SubAgent 6: Bear Researcher (Initial Report)    │
└─────────────────────────────────────────────────────┘
  ↓
┌─────────────────────────────────────────────────────┐
│  Layer 2.5: Two-Round Debate (Sequential)           │
│  ├─ Round 1:                                        │
│  │   ├─ Bear Researcher → Bull's Arguments          │
│  │   └─ Bull Researcher → Bear's Arguments          │
│  └─ Round 2:                                        │
│      ├─ Bear Researcher → Bull's Rebuttals          │
│      └─ Bull Researcher → Bear's Rebuttals          │
└─────────────────────────────────────────────────────┘
  ↓
┌─────────────────────────────────────────────────────┐
│  Layer 3: Final Decision                            │
│  └─ SubAgent 7: Research Manager                    │
│      (Synthesizes all reports + debate history)     │
└─────────────────────────────────────────────────────┘
  ↓
Output: BUY/SELL/HOLD + Investment Plan (Markdown)
```

### Step 7: Export to Markdown Report

Research Manager outputs the complete report to a markdown file:
```
~/.openclaw/workspace/memory/reports/trading-agents-[stock_code]-[timestamp].md
```

The markdown file contains:
- Part I: Final Investment Decision
- Part II: Layer 1 Reports (4 reports)
- Part III: Layer 2 Reports (2 initial reports)
- Part IV: Debate History (4 responses)
- Part V: Appendix

---

## Execution Steps

### Step 1: Parse Stock Ticker

Extract stock ticker from user input, format to standard:
- A-shares: `600519.SH`, `300750.SZ`
- HK stocks: `00700.HK`
- US stocks: `AAPL`

### Step 2: Execute Layer 1 SubAgents in Parallel

Use `sessions_spawn` to **launch in parallel** 4 SubAgents:

| SubAgent | Task | Output |
|----------|------|--------|
| **Fundamental Analyst** | Fundamental analysis | Fundamental report |
| **Market Analyst** | Market technical analysis | Market analysis report |
| **News Analyst** | News analysis | News summary report |
| **Social Media Analyst** | Social sentiment analysis | Sentiment report |

### Step 3: Collect Layer 1 Reports

Use `subagents(action=list)` to check all SubAgent completion status, then collect report content.

### Step 4: Execute Layer 2 SubAgents in Parallel (Initial Reports)

Pass Layer 1 reports to Layer 2, **launch in parallel** 2 SubAgents:

| SubAgent | Task | Input | Output |
|----------|------|-------|--------|
| **Bull Researcher** | Initial bull report | Layer 1 4 reports | Bull report (initial) |
| **Bear Researcher** | Initial bear report | Layer 1 4 reports | Bear report (initial) |

### Step 5: Two-Round Debate

After Layer 2 completes, initiate **two rounds of debate**:

#### Round 1:
1. **Bear Researcher** receives Bull's initial report → Refutes bull arguments
2. **Bull Researcher** receives Bear's initial report → Refutes bear arguments

#### Round 2:
1. **Bear Researcher** receives Bull's Round 1 rebuttals → Counter-rebuttal
2. **Bull Researcher** receives Bear's Round 1 rebuttals → Counter-rebuttal

**Debate Rules**:
- Use specific data and reasoning to refute opponent's arguments
- Cite sources from all available reports
- Apply conversational debate style
- Reflect on past experience and lessons learned
- Each response should directly address opponent's specific points
- **Never include API keys or tokens in debate content**

### Step 6: Execute Final Decision SubAgent

Launch **Research Manager** with ALL inputs:
- Layer 1: 4 reports (Fundamental, Market, News, Social)
- Layer 2: 2 initial reports (Bull, Bear)
- Layer 2.5: 4 debate responses (Round 1 + Round 2)

Research Manager synthesizes all information and makes final investment recommendation.

---

## SubAgent Details

### SubAgent 1: Fundamental Analyst

**Data Sources**:
- Tushare Pro API (financial data, valuation metrics)
- Company annual/quarterly reports

**Analysis Dimensions**:
1. Financial statement analysis
2. Valuation metrics (PE/PB/PS percentile)
3. Growth metrics
4. Company basic information
5. Shareholder structure

**Detailed Prompt**: See [references/fundamental-analyst.md](references/fundamental-analyst.md)

---

### SubAgent 2: Market Analyst

**Data Sources**:
- Tushare Pro API (daily data)
- Technical indicator calculations

**Analysis Dimensions**:
1. Price trend (MA system)
2. Technical indicators (MACD, RSI, KDJ, BOLL)
3. Volume analysis
4. Capital flow
5. Market anomaly signals

**Detailed Prompt**: See [references/market-analyst.md](references/market-analyst.md)

---

### SubAgent 3: