Agent Lightning v1.0 把一個很難的問題變得具體：已經接上搜尋、計算器、程式工具與多輪控制流程的 Agent，能不能保留原本的執行框架，直接用真實軌跡做強化學習（RL）？微軟把這種方法稱為 Harnessed Agentic RL。它不是讓 Agent 自稱「學會了」，而是要求模型權重在可驗證 reward 與訓練迴圈中真的更新。
這篇會帶你建立官方 Calc-X 的一 GPU 最小實驗：先凍結 baseline，再跑訓練、保存 trajectory、reward 與成本，最後只用未參與調整的 held-out 題驗收。先說清楚執行邊界：官方 v1.0 路徑要求 NVIDIA CUDA 12.9／13.0，Calc-X 規格是 1×A100 80GB；本文提供可重跑 runbook 與空白驗收表，不會把未在相符硬體執行的數字包裝成實測結果。
先說結論：會變好的 Agent，需要三個條件同時成立
先記住這個驗收式：會變好的 Agent ＝ 真實 Harness × 可驗證 Reward × Held-out Eval。Harness 是把模型接到 prompt、工具、環境與控制流程的執行層；reward 是每次完整嘗試後可重算的分數；held-out eval 則是從未拿來調 prompt、reward 或超參數的封存測試。
三者是乘法，不是裝飾。拿掉真實 harness，訓練的是簡化玩具；reward 有漏洞，模型會學會拿分而非解題；沒有 held-out 題，train reward 上升也可能只是背答案或迎合評分器。若你還不熟悉執行層，可先看AI Agent Harness 白話解析與從零建立 Agent Harness。
Harnessed Agentic RL 是什麼？先和兩種常見方法分開
模型 RL：改權重，但訓練器常自己掌握互動迴圈
一般模型 RL 會用 reward 更新 policy（策略模型）的權重。若任務只是單輪數學題，trainer 可以自己產生回答、打分再更新；但真實 Agent 可能有十幾個工具、框架自己的 memory、多輪 retry 與外部環境。把這些邏輯重寫進 trainer，容易讓訓練環境和正式部署分家。
Prompt Optimization：改提示或範例，模型權重不動
Prompt Optimization 會搜尋、改寫或選擇較好的 system prompt、few-shot 範例、skill 與路由規則。它通常不更新底層模型權重，優點是便宜、可回滾；限制是能力仍受原模型約束。先做 prompt／harness 優化通常合理，但它不能直接替代權重訓練。
Harnessed Agentic RL：改權重，並讓正式 Harness 留在迴圈裡
Agent Lightning v1.0 技術報告把 deploy-time harness 定義為負責 context 建構、工具、環境互動與控制流程的系統。訓練端不接管它，而是透過 OpenAI 相容端點代理觀察模型 request／response、事件與 rollout reward，再把一次 rollout 組裝成一筆或多筆訓練 sample。這就是「harnessed」的核心。
Agent Lightning v1.0 架構：Trainer、Gateway、Controller 各做什麼？
- API Gateway：提供 OpenAI 相容 proxy、模型與 rollout 端點及 event store，記錄 prompt ID、回應 token ID 與被選 token 的 log probability。v1 proxy 只接受支援的 chat／completions 路徑，且不支援 streaming；不要假設任何 OpenAI-compatible client 都能原封不動接上。
- Rollout Controller：把每筆任務啟動成本機 subprocess，或建立 Kubernetes Job，並管理執行狀態。它是調度器，不會替你定義正確答案、環境 reset 或安全政策。
- Customized Trainer：建立 rollout、收集 request／reward／event，以
verl執行 sample 組裝、advantage 計算與 policy update。官方 v1 採 exact token-prefix merging、rollout-level advantage 與 per-rollout mean loss。
一次 Agent 任務可能呼叫模型多次，所以 rollout 不等於 training sample。論文作者在 coding 實驗中報告，只有 36% rollout 最後是一筆 sample，平均則是 2.41 筆。這正是 Agent RL 比單輪問答麻煩的地方：同一場任務的多次決策，必須在 tokenizer、advantage 與 loss normalization 上保持一致。
v1 預設採 rollout-level advantage，trainer 取整趟任務最後一個 reward event 作為 final reward。白話說，它知道整趟成功或失敗，不代表能精準指出哪一個工具決策做對；credit assignment 的解析度仍受 reward 與 sample 組裝方式限制。
開始前檢查：官方 Calc-X 路徑需要 A100 80GB
官方安裝頁要求 uv 與 NVIDIA CUDA 12.9 或 13.0；Calc-X 文件列出的硬體是 1×A100 80GB、模型是 Qwen/Qwen2.5-1.5B-Instruct。Local controller 不需要 Kubernetes；Minikube 版本則還需要 Docker、Minikube 與至少 64GB 記憶體。
準備一台符合規格的 Linux CUDA 主機、足夠磁碟、Hugging Face 模型存取與 Weights & Biases（W&B）帳號。W&B 是官方預設 logger，軌跡可能包含 prompt、工具輸入與任務資料；使用真實公司資料前，先確認資料政策，或在設定中改用允許的紀錄方式。以下命令以 v1.0.0 tag 為基準，避免 main branch 日後變動。
步驟 1：凍結版本，安裝官方測過的 GPU Stack
git clone https://github.com/microsoft/agent-lightning.git
cd agent-lightning
git checkout v1.0.0
uv sync
source .venv/bin/activate
bash scripts/setup_verl.sh 0.8.0 cu130
uv run wandb login官方腳本會配對 verl 0.8.0、vLLM 0.20.2、PyTorch CUDA wheel，並從原始碼建置 flash-attn 2.8.3；文件估計建置約 10～30 分鐘，實際仍看 CPU、網路與 wheel cache。若機器只有 CUDA 12.9，可依官方組合改用 verl 0.7.1 cu129，不要自行混搭版本後再把相依衝突歸因給 Agent Lightning。
先保存環境證據：tag／commit、nvidia-smi、CUDA、Python、套件 lock、模型 revision 與執行日期。這些欄位比 GitHub stars 更能回答「別人能否重跑」。
步驟 2：下載 Calc-X，先讀 Reward 再看訓練命令
依官方 Calc-X 資料準備說明下載壓縮檔，解到 examples/calc_x/data/。目錄應包含 train.parquet、test.parquet、test_mini.parquet 與 sample.jsonl，接著安裝範例依賴：
source .venv/bin/activate
uv pip install openai httpx sympy \
"autogen-agentchat" "autogen-ext[openai]" \
"mcp>=1.11.0,<2" mcp-server-calculator
cd examples/calc_x
unzip data/calc-x-data.zip -d data/Calc Agent 必須輸出 ### ANSWER: <answer> ###。官方 evaluator 先看字串與選項是否相同，數字則用 SymPy 解析，並以相對誤差 1e-2 判斷；答對 reward 1，否則 0。這種 deterministic verifier 比主觀 LLM judge 好重算，但仍要問三件事：答案是否可能洩漏到 prompt／工具？相對誤差是否符合你的任務？只驗最終答案會不會放過禁用操作？
把 POC Reward 改成真正隔離的 Verifier
原始碼檢查顯示，官方 POC 會把真值 RESULT 與 reward bearer key 放進 rollout agent process，並對模型可控制的答案呼叫 sympy.parse_expr。SymPy 官方文件明確警告這類 parser 使用 eval，不應直接處理未清洗輸入。這不證明範例已被利用，但代表 POC evaluator 不能原樣當成 production security boundary。
- 分開 trust domain：Agent process 只拿 question；canonical truth、reward key 與 verifier code 留在隔離服務，網路採 default-deny。
- 限制答案語法：只接受一個固定 JSON schema；整數／分數用 exact comparison，小數用固定 Decimal rounding，拒絕 identifier、function call、NaN／Inf 與過深 AST。
- 限制工具：calculator 是無網路、無檔案、無環境變數的純函式，每題使用新 process，並設 CPU、記憶體、時間與輸出上限。
- 分開指標：主要 reward 只看 canonical outcome correctness；工具使用率、格式有效率與禁用操作另列，不獎勵呼叫次數或文字長度。
不要一邊看正式測試分數、一邊改 reward。最穩妥做法是另外保留 pilot／validation 題供除錯與選 checkpoint，把一份最終 held-out manifest 封存 hash、限制存取，直到設計凍結才開封。若反覆用 test.parquet 選超參數，它就只是 validation，不再是 held-out。可搭配AI Eval 洩漏檢查建立資料邊界。
切分時不要只隨機拆 rows；要連題型 template、operand range 與 generator seed 一起隔離，再加等價改寫題與 canary。RL 前先對 verifier 跑攻擊測試：環境秘密、reward endpoint、Python／import payload、巨大指數、Unicode 運算符、雙 answer marker、timeout、retry 與 replay 都應 fail closed，且不能留下副作用。
步驟 3：先跑 Baseline，再啟動最小訓練
官方 Calc-X 預設 trainer.val_before_train=False，直接執行會缺少同一環境下的 step 0 對照。run_local.sh 會把額外參數交給 OmegaConf，因此建議第一次就開啟 baseline validation：
source .venv/bin/activate
cd examples/calc_x
bash run_local.sh \
trainer.val_before_train=true \
trainer.test_freq=10這個範例預設使用 GRPO、train batch 32、每題 4 個 rollout、單 GPU、兩個 epoch，actor learning rate 是 1e-6。腳本會啟動 Ray、port 8181 的 agl-server、local controller 與 trainer；server／controller log 寫進 /tmp/agl-*.log，訓練曲線與軌跡則進 W&B。
先不要同時改模型、資料、reward 與 batch size。第一輪目標不是追最高分，而是證明五件事：baseline 可保存、rollout 可回放、reward 可重算、checkpoint 可識別、held-out runner 不讀訓練答案。想建立更完整的 tracing，可接著看Agent Observability 教學。
步驟 4：保存四類證據，避免只剩一條漂亮曲線
- 版本：repo commit、模型 revision、資料 manifest、reward 與 harness commit、完整 config。
- 品質：baseline、各 checkpoint 的 validation、最後一次 held-out 成功數與總題數；不要只報百分比。
- 軌跡：抽樣保存成功與失敗 rollout、工具呼叫、reward event、timeout、解析失敗與人工介入。
- 成本：GPU 型號與時數、wall time、rollout 數、模型 token、工具／API 費用、失敗重跑與人工查核時間。
最低可交付紀錄可寫成：baseline = __ / __、best validation = __ / __ @ step __、final held-out = __ / __、GPU-hours = __、reward-hack cases = __。空白就是未知，不能填 0；若未執行，也不能把論文作者的 benchmark 數字貼進自己的欄位。
步驟 5：用 Held-out Eval 與人工稽核決定有沒有真的變好
held-out runner 必須使用同一個模型 decoding 設定、harness、工具權限、timeout 與重試規則；唯一允許改變的是 checkpoint。每題至少保留 pass／fail 與 failure type，若多次重跑則原樣報 x/n，不要把少量重跑說成穩定成功率。完整設計方法可參考AI Evals 七步教學。
人工抽查至少涵蓋：高 reward 但答案可疑、reward 突然跳升、工具回合異常短、讀到答案欄位、繞過 calculator、重複撞 tolerance，以及只在 train 題出現的固定字串。Coding Agent 還要查 git history、對外抓 GitHub、安裝含解答的 source package、用 urllib 繞過限制等路徑；這些都曾出現在論文作者的 reward-hacking 調查。網路 egress deny／allowlist 是使用者的安全責任，不是框架自動替你完成。
先寫停損線，才不會被 Train Reward 牽著走
- train reward 上升，但 validation／held-out 連續三個評估點不升或下降：停止並查 leakage、overfitting 與 evaluator。
- 發現任何可重現的答案洩漏、越權工具或網路繞行：該 checkpoint 不得算成功，先修環境再重跑 baseline。
- GPU-hours、wall time 或每個成功任務成本超過預算上限：停止，不用「再跑一點」追 sunk cost。
- 成功率改善只來自更長 timeout、更多 retry 或不同工具權限：分開報告，不能歸因為模型學會。
官方結果可以告訴我們什麼？又不能證明什麼？
技術報告作者在三類任務上都報告 validation 改善：搜尋 Agent 的 Llama-3.2-3B 從 25.1 到 41.7；一般指令 Agent 的 Qwen3-4B 從 51.9 到 70.2；coding 實驗的 Qwen3.5-9B 在 SWE-bench Verified 從 41.8 到 56.4（step 208）。這些是作者依各自設定報告的結果，三組資料、reward、模型、算力與 protocol 都不同，不能彼此橫比，也不是 Calc-X 一 GPU教學的預期成績。
尤其 coding recipe 並不「輕量」：官方 coding 文件列出 4×B200、Kubernetes 與 Qwen3.5-9B。再加上 v1 tag 與報告都在 2026 年 8 月才公開，現階段最可靠的結論是「方法已提出、官方例子與自報實驗存在」，不是「社群已廣泛獨立重現」。GitHub stars 可代表關注度，不能替代成功率、成本或相容性證據。
哪些人現在適合用 Agent Lightning？
- 適合：已經有可運作 Agent harness、可訓練的開放權重模型、能改指向 OpenAI-compatible 非串流端點的 client、deterministic reward、CUDA 訓練能力與嚴格 eval 管線，希望讓權重學習真實多輪任務的團隊。
- 先等等：仍在調 prompt、工具 schema 或基本 retry 的團隊。先把 harness 與 eval 穩定，通常比立刻加 RL 更容易定位收益。
- 不適合：沒有可驗證 reward、不能隔離資料／網路、只有 Apple Silicon 或低 VRAM 裝置，卻期待複製官方一 GPU路徑的讀者。
如果你只是想理解模型為何能從回饋改變，可先讀AI 模型如何學習；如果你要研究增加後訓練資源時的收益曲線，再延伸到Post-training Scaling Law。Agent Lightning 的價值在於把這些原理接回真實 Agent 系統，而不是取消前置工程。
Agent Lightning v1.0 常見問題
Agent Lightning 是微調工具嗎？
它是面向 Agent 強化學習的訓練框架，不是一般 supervised fine-tuning UI。v1 用 Gateway、Controller 與 customized trainer 把真實 rollout 轉成可供 verl 更新 policy 的 samples。
Harnessed Agentic RL 會取代 Prompt Optimization 嗎？
不會。Prompt optimization 改提示與範例，便宜且易回滾；Harnessed Agentic RL 更新模型權重，成本與風險都更高。實務上應先穩定 prompt、harness、reward 與 eval，再判斷 RL 是否值得。
一定要 A100 80GB 嗎？
官方 Calc-X v1.0 文件列出的驗證規格是 1×A100 80GB。其他 NVIDIA GPU 組合未必不能跑，但記憶體、速度與相依性要自行驗證，本文不把未列出的硬體推測成官方支援。
Apple Silicon 可以跑這個一 GPU 範例嗎？
不能照官方 CUDA／verl／vLLM 路徑直接跑。你可以在 Mac 閱讀程式與設計資料、reward、eval，但正式訓練應移到相符的 NVIDIA CUDA 主機。
為什麼一定要在訓練前跑 Baseline？
沒有同一模型 revision、harness、資料與 decoding 設定下的 step 0，你無法判斷變化來自訓練、環境或評測。Calc-X 預設不做 train 前 validation，所以本文明確打開 trainer.val_before_train=true。
Train Reward 上升就代表 Agent 變強嗎？
不代表。它也可能是背題、利用 tolerance、答案洩漏或 reward hacking。必須同時看未調整的 validation、最後 held-out、失敗案例與越權行為。
Agent Lightning 會自動幫我設計 Reward 與 Sandbox 嗎？
不會。框架負責訓練資料流與 rollout 調度；reward、環境 reset、工具權限、secret 隔離、網路政策與驗收規則仍是使用者責任。
GitHub Stars 很高，能代表已經成熟嗎？
不能。Stars 是關注與採用意願的 proxy，不會告訴你特定硬體是否安裝成功、reward 是否安全、held-out 是否改善或每次訓練要花多少。v1 很新，評估時應優先看版本固定的獨立重現與完整成本。
第一次實驗的驗收清單
- 凍結 v1.0.0、模型 revision、資料與 harness commit。
- 先跑並保存 baseline，不接受只有 train reward 的報告。
- 讓 reward 可離線重算，並封存從未拿來調整的 held-out 題。
- 保存成功／失敗 trajectories、GPU-hours、wall time 與每個成功任務成本。
- 人工檢查答案洩漏、越權工具、網路繞行與 tolerance 投機。
- 只在 held-out、行為安全與成本三關都過線時，才稱 Agent 變好。
想把這個實驗擴成正式開發流程，可以逛 AlphaLab AI 專區；想建立從提示、harness 到 eval 的完整系統，則可查看 AlphaLab 線上課程。
接著閱讀
左右滑動查看更多推薦
結語：不要問 Agent 有沒有學會，要問三份證據在不在
會變好的 Agent ＝ 真實 Harness × 可驗證 Reward × Held-out Eval。Agent Lightning v1.0 的突破，是讓現有 Agent 框架不必被 trainer 重寫，仍能把真實模型呼叫與完整任務 reward 接回 policy update；它沒有替你消除資料、評分、安全與算力工程。
第一次跑 Calc-X，真正的完成條件不是 W&B 曲線往上，而是你能交出固定版本的 baseline、可回放 trajectory、可重算 reward、從未調過的 held-out 結果與完整成本。五樣都在，才有資格說 Agent 變好了；少一樣，最誠實的答案仍是「還不知道」。