你卡在安裝步驟，或不確定多個 AI 的分析結果能不能直接拿來用？
最快做法：先把 TradingAgents 當作股票研究輔助工具，依官方文件核對環境、安裝依賴並設定所需服務，再跑一次官方範例、檢查輸出；它不保證收益，也不代替你的投資判斷。
適合想了解 TradingAgents 是否能輔助研究的個人投資者。
也適合想從頭安裝並完成第一次執行的開發者，以及評估 AI Agent 環境的技術人員。
| 時間 | 本週建議動作 | 完成的判斷 |
|---|---|---|
| 了解功能 | 對照官方說明，確認角色協作和輸出形式 | 判斷是否符合研究用途 |
| 準備與安裝 | 核對 Python、依賴及服務帳戶，再安裝專案 | 確認程式可載入 |
| 設定與執行 | 依設定範例加入憑據，執行官方示例 | 檢查日誌與分析結果 |
TradingAgents 的角色協作與單一模型用法有何不同
TradingAgents 把股票研究拆成多個 AI 角色的協作流程。專案文件列出的角色涵蓋基本面、情緒、新聞及技術分析等研究面向，也包含多頭與空頭研究員、研究管理及交易決策等角色；其設計目標是整理多方分析，而非只產生一段沒有過程脈絡的回答。角色安排與工作流程可參照官方專案說明，研究設計背景則見專案研究論文。
| 比較面向 | TradingAgents 的多角色流程 | 單一模型直接提問 |
|---|---|---|
| 分析組織 | 依角色分工整理不同研究面向 | 由同一模型直接回覆問題 |
| 過程呈現 | 可查看不同角色及研究流程的產出 | 需自行追問或整理分析步驟 |
| 使用限制 | 需要專案依賴和外部服務設定 | 仍須自行檢查資料來源與模型回答 |
因此，你可以用它整理研究思路、查看不同角色的觀點，以及檢視流程生成的分析結果；但不能據此認定它會自動交易、準確預測股價，或替你承擔投資風險。輸出是研究材料，不是收益承諾，也不是個人化投資建議。
開始前也要考慮幾項容易被忽略的成本：外部模型或資料服務可能需要帳戶及有效憑據；服務不可用時，安裝完成仍可能無法完成分析；環境設定錯誤會讓輸出缺漏或中斷；而角色文字看起來完整，也不代表其資料來源和推論已經獨立驗證。
安裝前：先核對環境、依賴與服務條件
不要先複製一串安裝指令就假設環境相容。專案的 pyproject.toml 列有 Python 版本要求，應以目前的專案設定為準；若執行環境不符合，先處理版本問題再安裝套件。Python 官方文件也說明，可用 venv 建立隔離的虛擬環境，避免專案套件與其他程式互相影響。
| 準備項目 | 你要確認什麼 | 未確認時可能遇到的問題 |
|---|---|---|
| Python 與虛擬環境 | 版本符合專案設定，已進入該專案環境 | 套件安裝到別的環境，執行時找不到依賴 |
| 原始碼與依賴 | 能取得專案程式碼，並依官方說明安裝 | 缺少模組或版本不相容 |
| 模型與資料服務 | 所需帳戶、金鑰及服務權限可用 | 連線或資料請求失敗 |
| 敏感憑據 | 金鑰存放在本機設定，不進入公開程式碼庫 | 憑據外洩或遭未授權使用 |
TradingAgents 的分析需要依賴相應模型與資料服務。你應先查看官方環境變數範例，確認當前設定所需的項目，而不是從其他人的設定複製變數名稱。特別留意帳戶是否已開通、金鑰是否仍有效，以及目前網路是否能連線到服務端點。可先閱讀環境變數範例，並對照預設設定檔理解程式如何讀取設定。
安裝與設定：先隔離依賴，再加入服務憑據
第一步：取得程式碼並進入專案目錄
在終端機切換到你有寫入權限的位置，依官方安裝說明取得專案原始碼。若使用 Git，git clone 的用途是複製遠端倉庫；指令格式可查閱官方 Git 說明。接著進入剛取得的專案目錄。若你使用圖形化工具或其他克隆方式，仍須確認後續指令是在專案根目錄執行。
第二步：建立並啟用虛擬環境
依你的作業系統建立 Python 虛擬環境並啟用。這一步把專案依賴與系統層級或其他專案的套件分開。啟用後，檢查終端機目前指向的 Python 是否位於該環境；若不確定，先回看虛擬環境文件，不要直接在全域環境反覆安裝套件。
第三步：依官方方式安裝依賴
回到專案根目錄，按官方 README所列指令安裝依賴。若文件提供以 pip 安裝本機專案的方式，請依其說明及專案當前檔案執行；pip 對本機專案的安裝選項可參考官方文件。安裝過程沒有錯誤訊息只是初步訊號，還要確認命令正常結束，並能在此環境匯入專案模組。
| 安裝階段 | 你要看到的訊號 | 若未符合 |
|---|---|---|
| 取得原始碼 | 專案目錄及其設定檔可讀取 | 確認克隆位置與目錄權限 |
| 安裝依賴 | 安裝程序結束，沒有未解決的依賴錯誤 | 核對 Python 版本與啟用的環境 |
| 載入設定 | 專案模組可匯入，設定檔可讀取 | 回到專案根目錄並檢查安裝方式 |
第四步：設定模型與資料服務
對照 .env.example 設定環境變數，再按官方說明選擇專案使用的模型及分析設定。.env 檔案適合保存在本機，應避免提交到公開倉庫；若意外公開了金鑰，請按服務方提供的方式撤銷或更新。不要自行猜測預設檔中未列出的參數，也不要以為填好一個模型金鑰就代表資料服務也已準備妥當。
第一次執行：用官方流程驗證安裝結果
官方 README 提供透過 Python 建立分析圖並執行 propagate 的範例。你可以先按文件載入預設設定與 TradingAgentsGraph，再使用有效的股票代號及符合資料服務要求的日期執行。以下只示意程式呼叫方式；實際值與設定應按官方範例及你的服務條件填入：
from tradingagents.graph.trading_graph import TradingAgentsGraph
from tradingagents.default_config import DEFAULT_CONFIG
trading_graph = TradingAgentsGraph(debug=True, config=DEFAULT_CONFIG)
_, decision = trading_graph.propagate("YOUR_TICKER", "YYYY-MM-DD")
print(decision)
第一次跑通，不只看終端機有沒有輸出文字。你還要核對程式是否讀取預期的設定、日誌有沒有服務連線或資料讀取錯誤，以及結果是否包含可辨識的研究內容。輸入日期能否取得資料，會受資料服務涵蓋範圍影響；若結果缺漏，先確認輸入、服務權限與日誌，不要將空白或不完整輸出當成有效分析。
常見問題與可勾選的跑通檢查
首次執行失敗時，按問題發生的階段排查，避免同時更動多項設定：
- 依賴缺失或匯入失敗：確認已啟用正確的虛擬環境，再核對專案 Python 要求及依賴安裝是否完成。
- 設定錯誤：對照
.env.example和預設設定檔，檢查必要變數是否存在、是否由目前執行環境讀取。不要在日誌或公開討論中貼出完整金鑰。 - 服務無法使用：確認帳戶、金鑰、權限及網路連線；安裝成功不代表外部模型或資料服務必然可連線。
- 輸出異常或不完整：檢查輸入的股票代號與日期，再核對資料服務回傳狀態及執行日誌。若問題仍在，保留錯誤訊息並按專案文件定位，不要自行把失敗原因歸結為模型預測能力。
可勾選的完成清單：
- [ ] 我已按專案設定核對 Python，並在預期的虛擬環境內操作。
- [ ] 我已按官方文件取得專案程式碼，並從專案目錄安裝依賴。
- [ ] 我已對照環境變數範例設定必要服務，且金鑰沒有提交到公開倉庫。
- [ ] 我已依官方範例執行分析，並檢查日誌、資料來源與輸出是否完整。
- [ ] 我知道角色分析是研究輔助，仍須自行核實資料並作出投資判斷。
如果你的目前做法是在個人電腦上執行，主要代價通常是佔用本機環境、依賴可能與其他專案互相影響，還要自行維護執行時的網路與憑據管理。遠端 Mac 可作為另一種隔離執行環境，但它不是 TradingAgents 必需條件；應先確認專案官方相容性、模型與資料服務的連線要求，以及你是否真的需要 macOS。若只是短期測試且已確認工作流程適用，租用 Hashvps 的 Mac 可作為自購設備以外的選項；先查看Hashvps 方案實際列出的配置與交付資訊，並透過服務說明確認是否符合你的用途。否則，沿用已符合官方要求的本機或其他環境即可。
為你的股票研究準備一台雲端 Mac
透過 Hashvps 租用原生 macOS Mac mini，將程式安裝與執行環境留在專屬雲端機器上。
可透過 SSH 或 VNC 遠端操作，按需要使用命令列或圖形桌面，方便測試與日常管理。