{"repo": "agentscope-ai/agentscope-samples", "files": {"evotraders/README.md": {"c7f3174cbbd32a96c796571d0fe930ac80ddd523": {"t": 1785674104.311307, "n": 8755, "h": "80b354726577c1d0", "c": "<p align=\"center\">\n  <img src=\"./docs/assets/evotraders_logo.jpg\" width=\"45%\">\n</p>\n\n<h2 align=\"center\">EvoTraders: A Self-Evolving Multi-Agent Trading System</h2>\n\n<p align=\"center\">\n  📌 <a href=\"http://trading.evoagents.cn\">Visit us at EvoTraders website !</a>\n</p>\n\n![System Demo](./docs/assets/evotraders_demo.gif)\n\nEvoTraders is an open-source financial trading agent framework that builds a trading system capable of continuous learning and evolution in real markets through multi-agent collaboration and memory systems.\n\n---\n\n## Core Features\n\n**Multi-Agent Collaborative Trading**\nA team of 6 members, including 4 specialized analyst roles (fundamentals, technical, sentiment, valuation) + portfolio manager + risk management, collaborating to make decisions like a real trading team.\n\nYou can customize your Agents here: [Custom Configuration](#custom-configuration)\n\n**Continuous Learning and Evolution**\nBased on the ReMe memory framework, agents reflect and summarize after each trade, preserving experience across rounds, and forming unique investment methodologies.\n\nThrough this design, we hope that when AI Agents form a team and enter the real-time market, they will gradually develop their own trading styles and decision preferences, rather than one-time random inference.\n\n**Real-Time Market Trading**\nSupports real-time market data integration, providing backtesting mode and live trading mode, allowing AI Agents to learn and make decisions in real market fluctuations.\n\n**Visualized Trading Information**\nObserve agents' analysis processes, communication records, and decision evolution in real-time, with complete tracking of return curves and analyst performance.\n\n<p>\n  <img src=\"docs/assets/performance.jpg\" width=\"45%\">\n  <img src=\"./docs/assets/dashboard.jpg\" width=\"45%\">\n</p>\n\n---\n\n## Quick Start\n\n### Installation\n\n```bash\n# Clone repository\ngit clone https://github.com/agentscope-ai/agentscope-samples\ncd agentscope-samples/EvoTraders\n\n# Install dependencies (Recommend uv!)\nuv pip install -e .\n# optional: pip install -e .\n\n\n# Configure environment variables\ncp env.template .env\n# Edit .env file and add your API Keys. The following config are required:\n\n# finance data API: At minimum, FINANCIAL_DATASETS_API_KEY is required, corresponding to FIN_DATA_SOURCE=financial_datasets; It is recommended to add FINNHUB_API_KEY, corresponding to FIN_DATA_SOURCE=finnhub; If using live mode, FINNHUB_API_KEY must be added\nFIN_DATA_SOURCE =   #finnhub or financial_datasets\nFINANCIAL_DATASETS_API_KEY=  #Required\nFINNHUB_API_KEY=  #Optional\n\n# LLM API for Agents\nOPENAI_API_KEY=\nOPENAI_BASE_URL=\nMODEL_NAME=qwen3-max-preview\n\n# LLM & embedding API for Memory\nMEMORY_API_KEY=\n```\n\n### Running\n\n**Backtest Mode:**\n```bash\nevotraders backtest --start 2025-11-01 --end 2025-12-01\nevotraders backtest --start 2025-11-01 --end 2025-12-01 --enable-memory # Use Memory\n```\n\nIf you do not have market data APIs and just want to try the backtest demo, download the offline data and unzip it into `backend/data`:\n```bash\nwget \"https://agentscope-open.oss-cn-beijing.aliyuncs.com/ret_data.zip\"\nunzip ret_data.zip -d backend/data\n```\nThe zip includes basic stock price data so you can run the backtest demo out of the box.\n\n**Live Trading:**\n```bash\nevotraders live                    # Run immediately (default)\nevotraders live --enable-memory    # Use memory\nevotraders live --mock             # Mock mode (testing)\nevotraders live -t 22:30           # Run daily at 22:30 local time (auto-converts to NYSE timezone)\n```\n\n**Get Help:**\n```bash\nevotraders --help           # View global CLI help\nevotraders backtest --help  # View backtest mode parameters\nevotraders live --help      # View live/mock run parameters\n```\n\n**Launch Visualization Interface:**\n```bash\n# Ensure npm is installed, otherwise install it:\n# npm install\nevotraders frontend                # Default connects to port 8765, you can modify the address in ./frontend/env.local to change the port number\n```\n\nVisit `http://localhost:5173/` to view the trading room, select a date and click Run/Replay to observe the decision-making process.\n\n---\n\n## System Architecture\n\n![Architecture Diagram](docs/assets/evotraders_pipeline.jpg)\n\n### Agent Design\n\n**Analyst Team:**\n- **Fundamentals Analyst**: Financial health, profitability, growth quality\n- **Technical Analyst**: Price trends, technical indicators, momentum analysis\n- **Sentiment Analyst**: Market sentiment, news sentiment, insider trading\n- **Valuation Analyst**: DCF, residual income, EV/EBITDA\n\n**Decision Layer:**\n- **Portfolio Manager**: Integrates analysis signals from analysts, executes communication strategies, combines analyst and team historical performance, recent investment memories, and long-term investment experience to make final decisions\n- **Risk Management**: Real-time price and volatility monitoring, position limits, multi-layer risk warnings\n\n### Decision Process\n\n```\nReal-time Market Data → Independent Analysis → Intelligent Communication (1v1/1vN/NvN) → Decision Execution → Performance Evaluation → Learning and Evolution (Memory Update)\n```\n\nEach trading day goes through five stages:\n\n1. **Analysis Stage**: Each agent independently analyzes based on their respective tools and historical experience\n2. **Communication Stage**: Exchange views through private chats, notifications, meetings, etc.\n3. **Decision Stage**: Portfolio manager makes comprehensive judgments and provides final trades\n4. **Evaluation Stage**\n   - **Performance Charts**: Track portfolio return curves vs. benchmark strategies (equal-weighted, market-cap weighted, momentum). Used to evaluate overall strategy effectiveness.\n\n   - **Analyst Rankings**: Click on avatars in the Trading Room to view analyst performance (win rate, bull/bear market win rate). Used to understand which analysts provide the most valuable insights.\n\n   - **Statistics**: Detailed position and trading history. Used for in-depth analysis of position management and execution quality.\n\n5. **Review Stage**: Agents reflect on decisions and summarize experiences based on actual returns of the day, and store them in the ReMe memory framework for continuous improvement\n\n---\n\n### Module Support\n\n- **Agent Framework**: [AgentScope](https://github.com/agentscope-ai/agentscope)\n- **Memory System**: [ReMe](https://github.com/agentscope-ai/reme)\n- **LLM Support**: OpenAI, DeepSeek, Qwen, Moonshot, Zhipu AI, etc.\n\n---\n\n## Custom Configuration\n\n### Custom Analyst Roles\n\n1. Register role information in [./backend/agents/prompts/analyst/personas.yaml](./backend/agents/prompts/analyst/personas.yaml), for example:\n\n```yaml\ncomprehensive_analyst:\n  name: \"Comprehensive Analyst\"\n  focus:\n    - ...\n  preferred_tools: # Flexibly select based on situation\n  description: |\n    As a comprehensive analyst ...\n```\n\n2. Add role definition in [./backend/config/constants.py](./backend/config/constants.py)\n```python\nANALYST_TYPES = {\n    # Add new analyst\n    \"comprehensive_analyst\": {\n        \"display_name\": \"Comprehensive Analyst\",\n        \"agent_id\": \"comprehensive_analyst\",\n        \"description\": \"Uses LLM to intelligently select analysis tools, performs comprehensive analysis\",\n        \"order\": 15\n    }\n}\n```\n\n3. Introduce new role in frontend configuration [./frontend/src/config/constants.js](./frontend/src/config/constants.js) (optional)\n```javascript\nexport const AGENTS = [\n    // Override one of the agents\n  {\n    id: \"comprehensive_analyst\",\n    name: \"Comprehensive Analyst\",\n    role: \"Comprehensive Analyst\",\n    avatar: `${ASSET_BASE_URL}/...`,\n    colors: { bg: '#F9FDFF', text: '#1565C0', accent: '#1565C0' }\n  }\n]\n```\n\n### Custom Models\n\nConfigure models used by different agents in the [.env](.env) file:\n\n```bash\nAGENT_SENTIMENT_ANALYST_MODEL_NAME=qwen3-max-preview\nAGENT_FUNDAMENTALS_ANALYST_MODEL_NAME=deepseek-chat\nAGENT_TECHNICAL_ANALYST_MODEL_NAME=glm-4-plus\nAGENT_VALUATION_ANALYST_MODEL_NAME=moonshot-v1-32k\n```\n\n### Project Structure\n\n```\nEvoTraders/\n├── backend/\n│   ├── agents/           # Agent implementation\n│   ├── communication/    # Communication system\n│   ├── memory/          # Memory system (ReMe)\n│   ├── tools/           # Analysis toolset\n│   ├── servers/         # WebSocket services\n│   └── cli.py           # CLI entry point\n├── frontend/            # React visualization interface\n└── logs_and_memory/     # Logs and memory data\n```\n\n---\n\n## License and Disclaimer\n\nEvoTraders is a research and educational project, open-sourced under the Apache 2.0 license.\n\n**Risk Warning**: Before trading with real funds, please conduct thorough testing and risk assessment. Past performance does not guarantee future returns. Investment involves risks, and decisions should be made with caution.\n"}}}}