# TradingAgents: đội agent AI phân tích cổ phiếu, crypto — hướng dẫn cài đặt và dùng

> TradingAgents là framework mã nguồn mở bằng Python, dựng một "công ty giao dịch" gồm nhiều agent AI: nhà phân tích, nhóm bull/bear, trader, quản lý rủi ro. Bạn nhập mã cổ phiếu hoặc crypto và một ngày, hệ thống chạy cả quy trình rồi trả về quyết định cùng báo cáo. Cài đặt không khó nếu đã có Python 3.11+ và một API key LLM; repo chỉ phục vụ nghiên cứu, không phải lời khuyên đầu tư.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-06-08 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/tradingagents-multi-agent-phan-tich-giao-dich-huong-dan

TradingAgents là một framework mã nguồn mở bằng Python, mô phỏng cách một công ty giao dịch làm việc bằng nhiều agent AI. Mỗi agent đóng một vai: phân tích cơ bản, tâm lý thị trường, tin tức, kỹ thuật, rồi đến nhóm tranh luận, trader và quản lý rủi ro. Bạn đưa vào một mã (ví dụ NVDA) và một ngày, nó chạy cả quy trình và trả về một quyết định kèm báo cáo.

Repo hợp với ai? Người thích tìm hiểu cách các agent AI phối hợp, lập trình viên muốn thử nghiệm ý tưởng giao dịch có hỗ trợ LLM, hoặc người làm tài chính muốn có một bản "báo cáo nháp" nhiều góc nhìn. Hiện repo có khoảng 122.000 sao và 23.400 fork, giấy phép Apache-2.0, và vẫn được cập nhật trong vài tháng gần đây.

Điểm đáng giá nhất là cách chia vai: các agent không chỉ đưa ra một câu trả lời, mà còn tranh luận bull/bear trước khi quyết định. Ngoài ra bạn chọn được nhiều nhà cung cấp mô hình, kể cả mô hình chạy trên máy mình. Lưu ý quan trọng ngay từ đầu: tác giả ghi rõ đây là công cụ nghiên cứu, không phải lời khuyên tài chính hay đầu tư.

```repo
- repo | TauricResearch/TradingAgents
- kind | Framework
- desc | TradingAgents là framework Python cho nhiều agent LLM cùng phân tích thị trường, tranh luận và đưa ra quyết định giao dịch mô phỏng, dùng cho nghiên cứu.
- stars | 122k
- lang | Python
- license | Apache-2.0
```

## TradingAgents làm được gì

### Chia việc như một công ty giao dịch

Framework tách bài toán lớn thành các vai nhỏ. Nhờ vậy mỗi agent chỉ tập trung một mảng, và bạn đọc được lý do đằng sau từng nhận định thay vì chỉ thấy kết luận.

- **Nhóm phân tích**: Fundamentals (báo cáo tài chính, chỉ số, dấu hiệu rủi ro), Sentiment (gom tin, StockTwits, Reddit thành một nhận định tâm lý ngắn hạn), News (tin thế giới và chỉ báo vĩ mô), Technical (chỉ báo như MACD, RSI). Các analyst được chọn sẽ chạy cùng lúc nên nhanh hơn.
- **Nhóm nghiên cứu**: một bên bull, một bên bear, tranh luận có cấu trúc để cân nhắc lợi ích và rủi ro.
- **Trader**: tổng hợp báo cáo để quyết định thời điểm và quy mô lệnh.
- **Quản lý rủi ro và Portfolio Manager**: đánh giá biến động, thanh khoản, rồi duyệt hoặc từ chối đề xuất. Nếu duyệt, lệnh được gửi tới sàn mô phỏng.

### Chọn nhà cung cấp mô hình tuỳ ý

Bạn dùng được OpenAI, Google (Gemini), Anthropic (Claude), xAI, DeepSeek, Qwen, GLM, MiniMax, OpenRouter, Mistral, Kimi, Groq, NVIDIA, Azure OpenAI, Bedrock, hoặc mô hình cục bộ qua Ollama. Còn có chế độ chạy bằng gói ChatGPT Plus/Pro của bạn thay cho API key. Ai ngại chi phí API sẽ thấy lựa chọn này hữu ích.

### Nhiều thị trường, có CLI và có thư viện

Repo làm việc với mọi thị trường Yahoo Finance có, dùng mã kèm hậu tố sàn: `AAPL`, `0700.HK`, `7203.T`, `AZN.L`, `RELIANCE.NS`, `600519.SS`, và crypto như `BTC-USD`. Bạn có thể dùng giao diện dòng lệnh tương tác, chạy không cần trả lời câu hỏi (cho tác vụ lên lịch), hoặc gọi từ code Python. Báo cáo lưu được thành một trang HTML (`complete_report.html`) để đọc trên trình duyệt, điện thoại hoặc in ra.

## Cần chuẩn bị gì

- **Python 3.11 trở lên** (pyproject.toml yêu cầu `>=3.11`). README ví dụ dùng Python 3.13.
- **Git** để tải repo về.
- **Một cách gọi mô hình AI**, chọn một trong các hướng: API key của nhà cung cấp bạn thích; hoặc đăng nhập bằng gói ChatGPT Plus/Pro; hoặc Ollama chạy local (không cần key).
- Khoá tuỳ chọn: `FRED_API_KEY` (dữ liệu vĩ mô, README ghi là miễn phí, không bắt buộc), `ALPHA_VANTAGE_API_KEY`, `TYPESAFE_API_KEY` (lọc bài đăng mạng xã hội, tuỳ chọn).
- Nếu muốn dùng Docker: cần Docker và Docker Compose (repo có Dockerfile và docker-compose.yml).

README không nêu yêu cầu GPU cho cách dùng qua API. Với mô hình local qua Ollama, cấu hình phần cứng cần thiết thì tư liệu chưa ghi.

```note
API key là chìa khoá tính tiền. Đừng dán key vào code rồi đưa lên GitHub, và đừng chia sẻ file .env. Mỗi lần chạy có nhiều agent gọi mô hình, nên chi phí có thể cao hơn bạn nghĩ. Hãy bắt đầu với một mã và mức tranh luận thấp (1 vòng).
```

## Cài đặt từng bước

```steps
- Tải repo | Clone TradingAgents về máy và vào thư mục
- Tạo môi trường ảo | Dùng conda hoặc uv với Python 3.11 trở lên
- Cài gói | Chạy pip install . trong thư mục repo
- Khai báo key | Sao chép .env.example thành .env rồi điền key
- Chạy CLI | Gõ tradingagents để mở giao diện chọn mã và ngày
```

### Tải repo về

Mở terminal (PowerShell hoặc Terminal trên máy bạn), đi tới thư mục muốn đặt dự án rồi chạy:

```bash
git clone https://github.com/TauricResearch/TradingAgents.git
cd TradingAgents
```

Lệnh đầu tải mã nguồn, lệnh sau đi vào thư mục vừa tải. Người mới hay quên lệnh `cd`, rồi các lệnh sau chạy sai chỗ.

### Tạo môi trường ảo

Môi trường ảo giúp gói của dự án không lẫn với các dự án khác. README đưa hai cách. Cách với conda:

```bash
conda create -n tradingagents python=3.13
conda activate tradingagents
```

Hoặc cách với [uv](https://docs.astral.sh/uv/):

```bash
uv venv --python 3.13
source .venv/bin/activate
```

Dòng `source .venv/bin/activate` là cú pháp macOS/Linux. README không ghi lệnh kích hoạt riêng cho Windows với uv, nên nếu dùng Windows và chưa quen, cách conda ở trên là lựa chọn đơn giản hơn.

### Cài gói

Trong thư mục TradingAgents, với môi trường đã kích hoạt:

```bash
pip install .
```

Nếu dùng uv thì README ghi là `uv pip install .`. Dấu chấm ở cuối nghĩa là "cài thư mục hiện tại", đừng bỏ nó.

### Khai báo API key

Cách dễ nhất cho người mới là dùng file `.env`:

```bash
cp .env.example .env
```

Sau đó mở file `.env` bằng trình soạn thảo và điền key của nhà cung cấp bạn chọn, ví dụ `OPENAI_API_KEY`, `GOOGLE_API_KEY` hoặc `ANTHROPIC_API_KEY`. Trên PowerShell, nếu `cp` không chạy như mong muốn, bạn có thể tự sao chép file bằng File Explorer rồi đổi tên thành `.env`.

Cách khác theo README là đặt biến trong terminal, ví dụ:

```bash
export OPENAI_API_KEY=...          # OpenAI (GPT)
export GOOGLE_API_KEY=...          # Google (Gemini)
export ANTHROPIC_API_KEY=...       # Anthropic (Claude)
```

Chỉ cần đặt key của nhà cung cấp bạn thực sự dùng. Các biến khác trong README (DeepSeek, Qwen, Groq, Mistral, OpenRouter…) làm tương tự.

### Tuỳ chọn: chạy bằng gói ChatGPT Plus/Pro

Nếu không muốn dùng API key, chọn "Subscription" trong menu nhà cung cấp của CLI, rồi đăng nhập một lần:

```bash
tradingagents login chatgpt
```

Lệnh này in ra một địa chỉ để bạn mở bằng trình duyệt. Phiên đăng nhập lưu ở `~/.tradingagents/chatgpt-auth.json`, và `tradingagents logout chatgpt` sẽ thu hồi. Các lần chạy tính vào hạn mức gói của bạn.

### Tuỳ chọn: dùng Docker

```bash
cp .env.example .env  # add your API keys
docker compose run --rm tradingagents
```

Với Docker, key phải nằm trong `.env` vì image không chứa file `.env`. Sau khi cập nhật repo, chạy `docker compose build` để dựng lại image. Muốn dùng mô hình local với Ollama:

```bash
docker compose --profile ollama run --rm tradingagents-ollama
```

### Chạy giao diện CLI

```bash
tradingagents          # installed command
python -m cli.main     # alternative: run directly from source
```

Lệnh đầu dùng khi gói đã cài; lệnh sau chạy thẳng từ mã nguồn nếu lệnh đầu không nhận. Màn hình sẽ hỏi mã cổ phiếu, ngày phân tích, nhà cung cấp LLM, độ sâu nghiên cứu… Lần sau, câu trả lời lần trước hiện sẵn làm mặc định, chỉ cần nhấn Enter.

## Kiểm tra đã chạy được chưa

Cách kiểm tra đơn giản nhất: gõ `tradingagents` và xem có hiện màn hình chọn mã, ngày, nhà cung cấp hay không. Nếu hiện, gói đã cài đúng. Tiếp theo chạy thử một mã với mức nghiên cứu thấp. Theo README, một giao diện sẽ hiện kết quả khi chúng được tải, để bạn theo dõi tiến độ của từng agent.

Kết quả mong đợi: các agent lần lượt báo cáo, cuối cùng có một quyết định giao dịch. Khi lưu báo cáo, bạn có thêm file `complete_report.html` để mở trong trình duyệt. Nếu thiếu key, chương trình sẽ báo lỗi từ phía nhà cung cấp mô hình, nên hãy kiểm tra `.env` trước tiên.

Cách thứ hai là chạy bằng Python. Repo có sẵn `main.py`, và README có ví dụ ngắn:

```python
from tradingagents.graph.trading_graph import TradingAgentsGraph
from tradingagents.default_config import DEFAULT_CONFIG

ta = TradingAgentsGraph(debug=True, config=DEFAULT_CONFIG.copy())

# forward propagate
state, decision = ta.propagate("NVDA", "YYYY-MM-DD")
print(decision)

# the same report tree the CLI saves, under results_dir/reports
ta.save_reports(state, "NVDA")
```

Thay `YYYY-MM-DD` bằng ngày bạn muốn phân tích (định dạng năm-tháng-ngày). Nếu `print(decision)` in ra một quyết định, mọi thứ đã thông.

## Dùng vào việc thật

### Nhà đầu tư cá nhân muốn một bản "đọc nhanh" nhiều góc nhìn

Bạn đang theo dõi một mã và muốn xem phân tích cơ bản, tin tức, tâm lý và kỹ thuật cùng lúc. Mở CLI bằng `tradingagents`, chọn mã (ví dụ `AAPL`), chọn ngày, chọn nhà cung cấp, để độ sâu ở mức thấp cho đỡ tốn. Kết quả là chuỗi báo cáo của từng analyst, phần tranh luận bull/bear và quyết định cuối. Hãy coi đó là tài liệu tham khảo để bạn tự suy nghĩ, không phải tín hiệu để làm theo.

> Để nhiều agent tranh luận thay vì chỉ hỏi một chatbot, bạn thấy được lý do đằng sau mỗi nhận định.
>
> — Ông T

### Người làm kỹ thuật muốn chạy theo lịch, không cần trả lời câu hỏi

Nếu bạn muốn một tác vụ chạy định kỳ, dùng cờ lệnh và biến môi trường thay cho màn hình hỏi đáp. Theo README:

```bash
export TRADINGAGENTS_LLM_PROVIDER=openai TRADINGAGENTS_QUICK_THINK_LLM=gpt-6-luna TRADINGAGENTS_DEEP_THINK_LLM=gpt-6-sol
export TRADINGAGENTS_OUTPUT_LANGUAGE=English TRADINGAGENTS_MAX_DEBATE_ROUNDS=1 TRADINGAGENTS_MAX_RISK_ROUNDS=1
tradingagents --ticker NVDA --date YYYY-MM-DD --analysts market,news,fundamentals --save --no-show
```

Hai dòng `export` chọn nhà cung cấp, mô hình, ngôn ngữ đầu ra và số vòng tranh luận. Dòng cuối chọn mã, ngày, các analyst, lưu báo cáo và không bật giao diện. Nếu thiếu thông tin khi chạy không có terminal, chương trình dừng trước khi bắt đầu và nói rõ cờ hoặc biến cần đặt. Đây là cách phù hợp để tạo báo cáo HTML mỗi ngày.

### Lập trình viên muốn tuỳ chỉnh trong code

Bạn muốn đổi mô hình hay số vòng tranh luận, rồi nhúng vào ứng dụng của mình. Chỉnh cấu hình trong Python:

```python
from tradingagents.graph.trading_graph import TradingAgentsGraph
from tradingagents.default_config import DEFAULT_CONFIG

config = DEFAULT_CONFIG.copy()
config["llm_provider"] = "openai"
config["deep_think_llm"] = "gpt-6-sol"
config["quick_think_llm"] = "gpt-6-luna"
config["max_debate_rounds"] = 2

ta = TradingAgentsGraph(debug=True, config=config)
_, decision = ta.propagate("NVDA", "YYYY-MM-DD")
print(decision)
```

`deep_think_llm` dành cho suy luận phức tạp, `quick_think_llm` cho việc nhanh. Kết quả nhận được là biến `decision` để bạn đưa vào bảng tính, bot nhắn tin hay hệ thống kiểm thử riêng.

### Người muốn thử với thị trường châu Á hoặc crypto, giữ dữ liệu trên máy

Với mã như `0700.HK`, `7203.T`, `600519.SS` hoặc `BTC-USD`, bạn nhập đúng mã có hậu tố khi CLI hỏi. Nếu không muốn gửi dữ liệu ra dịch vụ đám mây, đặt `llm_provider` là `ollama` (mặc định trỏ tới `http://localhost:11434/v1`) và kéo mô hình bằng `ollama pull <tên>`. Cần lưu ý: dữ liệu thị trường vẫn được lấy từ nguồn bên ngoài, chỉ phần LLM chạy local.

## Lỗi hay gặp và cách xử lý

### Lỗi do chưa điền hoặc điền sai API key

Triệu chứng thường là báo lỗi xác thực khi agent đầu tiên gọi mô hình. Kiểm tra file `.env` có đúng tên biến (ví dụ `OPENAI_API_KEY`), không thừa khoảng trắng hay dấu ngoặc. Nếu chạy Docker, nhớ rằng key phải ở `.env`, vì image không chứa file này.

### Phiên bản Python quá cũ

Repo cần Python 3.11 trở lên. Nếu `pip install .` báo không đáp ứng yêu cầu, kiểm tra bằng `python --version` rồi tạo lại môi trường ảo với phiên bản đúng như các lệnh ở trên.

### Gõ `tradingagents` báo không tìm thấy lệnh

Thường là do chưa kích hoạt môi trường ảo ở terminal đang mở, hoặc đã cài ở môi trường khác. Kích hoạt lại môi trường rồi thử lại. Cách dự phòng theo README là chạy từ thư mục repo: `python -m cli.main`.

### Chạy chậm hoặc tốn phí

Nhiều agent và nhiều vòng tranh luận nghĩa là nhiều lần gọi mô hình. Giảm `max_debate_rounds` (và `TRADINGAGENTS_MAX_DEBATE_ROUNDS`, `TRADINGAGENTS_MAX_RISK_ROUNDS` xuống 1), chỉ chọn vài analyst qua `--analysts`, hoặc dùng mô hình rẻ hơn cho `quick_think_llm`.

### Dữ liệu một số nguồn bị thiếu

Các nguồn như Yahoo hay mạng xã hội đôi khi không trả dữ liệu. Phần changelog của repo cho thấy tác giả đã xử lý các trường hợp kiểu này qua nhiều bản, nên hãy cập nhật repo bằng `git pull` rồi cài lại. Với Docker, chạy thêm `docker compose build`. Nếu vẫn lỗi, tìm trong mục Issues của repo xem có ai gặp chưa.

## Có nên dùng không

**Điểm mạnh.** Cấu trúc nhiều vai rõ ràng, dễ đọc lý do của quyết định. Hỗ trợ rất nhiều nhà cung cấp LLM, kể cả chạy local hay dùng gói ChatGPT. Có CLI, có Docker, có API Python, lưu báo cáo HTML dễ chia sẻ. Giấy phép Apache-2.0 và cộng đồng lớn.

**Giới hạn.** Tác giả nói thẳng đây là công cụ nghiên cứu: kết quả phụ thuộc vào mô hình nền, nhiệt độ mô hình, giai đoạn thời gian, chất lượng dữ liệu và các yếu tố ngẫu nhiên. Lệnh được gửi tới sàn mô phỏng, không phải tài khoản thật. Cài đặt đòi hỏi bạn quen terminal ở mức cơ bản, và chi phí gọi LLM có thể tăng nhanh nếu để nhiều vòng tranh luận.

**Khi nào chọn cách khác.** Nếu bạn cần một hệ thống giao dịch tự động có đảm bảo kết quả, hoặc lời khuyên đầu tư đáng tin cậy, repo này không dành cho mục đích đó. Nếu chỉ muốn tra nhanh giá và biểu đồ, một ứng dụng chứng khoán thông thường sẽ đơn giản hơn. Còn nếu bạn muốn hiểu cách các agent AI phối hợp, thử nghiệm ý tưởng và tự đánh giá kết quả, TradingAgents là điểm khởi đầu đáng thử.

## Câu hỏi thường gặp

### TradingAgents có miễn phí không?

Mã nguồn dùng giấy phép Apache-2.0 nên tải và dùng miễn phí. Tuy vậy, bạn vẫn phải trả phí cho nhà cung cấp LLM nếu dùng API, hoặc dùng hạn mức gói ChatGPT Plus/Pro, hoặc chạy mô hình local qua Ollama. README nói khoá FRED cho dữ liệu vĩ mô là miễn phí và tuỳ chọn.

### Cần GPU để chạy không?

README không yêu cầu GPU khi bạn gọi mô hình qua API của nhà cung cấp. Với Ollama hay máy chủ tương thích OpenAI chạy local, tư liệu chưa nêu cấu hình phần cứng cụ thể, nên bạn cần xem tài liệu của chính mô hình đó.

### Chạy được trên Windows không?

README không có mục riêng cho hệ điều hành, nhưng ghi nhận bản sửa lỗi mã hoá UTF-8 trên Windows trong lịch sử phát hành và hướng dẫn cài bằng conda hoặc Docker. Lệnh kích hoạt môi trường uv trong README là cú pháp macOS/Linux, nên người dùng Windows nên ưu tiên conda hoặc Docker.

### TradingAgents có tự mua bán thật trên tài khoản của tôi không?

Không theo mô tả trong README: Portfolio Manager duyệt hoặc từ chối đề xuất, và nếu duyệt thì lệnh được gửi tới sàn mô phỏng. Tác giả cũng nói rõ framework dành cho nghiên cứu, không phải lời khuyên tài chính, đầu tư hay giao dịch.

### Dữ liệu của tôi có an toàn không?

Khi dùng nhà cung cấp đám mây, nội dung phân tích sẽ được gửi tới dịch vụ đó nên bạn cần xem chính sách của họ. Bạn có thể chạy LLM local qua Ollama hoặc máy chủ tương thích OpenAI. README cho biết bước kiểm tra bản mới chỉ chạy tối đa một lần mỗi ngày, không gửi gì về lần chạy của bạn, và tắt được bằng TRADINGAGENTS_NO_UPDATE_CHECK=1.

### Phân tích được những thị trường nào?

README nói repo hoạt động với mọi thị trường mà Yahoo Finance có, dùng mã kèm hậu tố sàn. Ví dụ có US (AAPL, SPY), Hồng Kông (0700.HK), Tokyo (7203.T), London (AZN.L), Ấn Độ, Canada, Úc, A-share Trung Quốc và crypto như BTC-USD.

### Khác gì việc hỏi một chatbot AI về cổ phiếu?

Thay vì một câu trả lời, TradingAgents chia thành nhiều agent chuyên trách, có phần tranh luận bull/bear và đánh giá rủi ro trước khi ra quyết định. Các analyst chạy song song và báo cáo được lưu thành cấu trúc để xem lại. Tư liệu chưa có so sánh định lượng với chatbot thông thường.
