PROFESSIONAL TRAINING DECK · 2026

20 SLIDES · 5 CHAPTERS

DECISION-GRADE TRAINING

Agent 評估與優化

基於 LangSmith 的完整評估工程——把「憑感覺」變成「可複現的成績單」

CHAPTERS · 5 PAGES · 20 TECH · LangChain 1.3.2 / LangSmith 0.8.8

CH.01

導論與評估角度地圖

為何 Agent 評估這麼難 / 通用七類 / 特殊十三類

CH.02

LangSmith 平台入門

四大功能塊 / 接入實作 / 軌跡 / 題庫與裁判

CH.03

記帳 Agent 評估工程

14 個工具 / 可複現三件套 / 13 個評估指標

CH.04

評估驅動優化實戰

提示詞重構 / Tool Docstring / 模型升級

CH.05

總結與延伸方向

關鍵收束 / 企業落地 / Benchmark / Eval Suite

載體

計算器 + 記帳 Agent

教學用計算器 → 真實業務記帳閉環

ENABLEMENT LEAD · PROFESSIONAL DELIVERY 「從憑感覺到可複現」

CH.01 · 評估難點 02 / 20

為什麼 Agent 評估這麼難

同時打破了「唯一答案 / 單步驟 / 確定性 / 無狀態」四個傳統測試的假設前提——這五個難點共同指向一套系統化的評估工程。

①

輸出非唯一

自然語言與工具調用組合方式不只一種——同一目標可能有多條正確路徑，無法用 == 比對

②

過程隱蔽

結果對不代表過程對。繞路重複、漏步確認、中間調錯工具——必須有完整軌跡才能診斷

③

隨機性

大模型本身帶隨機性，同一條用例今天對、明天可能就錯——「一次跑對」≠「這個 Agent 可靠」

④

真實副作用

會調用工具的 Agent 真的會刪資料、改狀態——越界即造成實質破壞，不像單元測試沙盒無害

⑤

版本漂移

多輪對話要記得上文指代；改 prompt、換模型都可能「修好 A 又悄悄弄壞 B」

需要一套系統化的評估角度，加上一個能自動記錄、批量打分、版本對比的平台——這就是 LangSmith 存在的理由

CH.01 · 評估角度地圖 03 / 20

通用七類評估角度地圖

下層是所有 Agent 都適用的七類——回答「這個智能體本身可靠嗎」。七類並非互相獨立，而是從「結果 → 過程 → 依據 → 記憶 → 邊界 → 穩定性」的遞進鏈條。

1.1

任務結果評估 (Task Outcome)

看終點是否正確完整——全部 Agent 都適用，但只看終點、無法定位問題

1.2

工具與動作評估 (Tool & Action)

是否調對工具、參數對不對——細分 Tool Correctness 與 Argument Correctness

1.3

過程軌跡評估 (Trajectory)

步驟是否合理、有無漏步繞路死循環——官方拆 Final Response / Single Step / Trajectory 三層

1.4

依據與狀態一致性 (Groundedness)

回答是否基於真實資料而非編造——RAG 類對應 Context Precision / Recall / Faithfulness，工具：RAGAS、TruLens

1.5

多輪交互與狀態保持

能否理解「剛才那個」等指代——多輪對話的核心能力

1.6

規則、安全與權限

是否越權、洩露、執行危險操作——業界用 τ-bench / OpenAgentSafety 作為 benchmark

1.7

抗擾與回歸穩定性

抗擾看能否扛住異常輸入；回歸看改版前後會不會退化——兩件相關的事

CH.01 · 評估角度地圖 04 / 20

13 個特殊評估角度（按 Agent 類型追加）

通用七類是公共底座，每一類業務 Agent 還有專屬的特殊評估角度——用法是「查表挑選」而非背誦式全套套用。

角度名稱	判斷內容	最適配 Agent 類型	常用指標 / 工具
檢索與引用	檢索相關性與幻覺率	RAG / 問答	Context Precision · Recall
文檔解析與抽取	OCR、切塊、欄位抽取正確性	文檔處理	欄位 F1 · 結構化率
資料分析口徑	SQL 正確性 / 結論由資料支撐	Text-to-SQL	EX / BIRD Benchmark
代碼執行與補丁	測試是否通過 / 是否引入 bug	Code Agent	Pass@k · SWE-bench
沙箱與執行環境	是否越權存取檔案 / 網路	自動化操作	資源白名單審計
工作流節點分支	節點選擇 / 分支觸發正確性	流程自動化	路徑覆蓋率
長任務生命週期	跨多輪 / 跨會話的連貫性	長流程 Agent	上下文保留率
外部系統狀態變更	副作用是否合規 / 可回滾	Ops / DevOps	副作用清單比對
多智能體協作	角色分工 / 交接是否順暢	Multi-Agent	交接成功率
實時事件流	事件到達率 / 處理時效	Realtime / Streaming	端到端延遲
用戶確認 / 副作用控制	高風險動作前是否請求確認	寫入 / 刪除類	確認觸發率
知識庫入庫品質	寫入資料是否正確 / 完整	長期記憶 Agent	入庫正確率
報告 / 產物品質	最終交付物是否符合規格	報告生成類	格式合規率 · 評審分

通用評估看 Agent 作為「智能體」是否可靠；特殊評估看它作為「某一類業務 Agent」是否專業——拿到具體 Agent 先查表挑選，再疊加通用七類

CH.02 · 平台入門 05 / 20

LangSmith 是什麼？四大功能塊分工

LangSmith = 可觀測 + 評估的雙重定位。四大功能塊對應「看一次跑 → 看一批跑 → 比版本 → 校準裁判」的遞進鏈路。

01 · TRACING

看一次跑了什麼

記錄單次運行的完整軌跡——承接「過程軌跡評估」的資料來源

→

02 · DATASETS & EXPERIMENTS

看一批對不對

題庫批量打分出成績單——承接任務結果、工具動作、依據等角度

→

03 · COMPARISON

看哪版更好

多版本成績單並排比——承接「抗擾與回歸穩定性」評估

→

04 · ANNOTATION QUEUES

看裁判信不信得過

人工逐條打分校準機器裁判——為自動評分做人工對齊

OBS

可觀測：自動記錄每一次運行

EVAL

評估：批量打分多維成績單

DIFF

對比：版本間升降一目了然

ALIGN

對齊：人機裁判金標準校準

第一章所有評估角度，都要靠這個平台才能從「清單」變成「分數」——這也是本章接下來要逐一動手跑通的四個里程碑

CH.02 · 接入實作 06 / 20

從零搭建最小 Agent：計算器專案

接入 LangSmith 之前，先徒手搭一個跟平台完全無關的最小 Agent——才能清楚看見「接入」到底改了什麼。

角色 01

ChatOpenAI

連上大模型
temperature=0 保證可複現

角色 02

@tool 裝飾器

把 multiply 標記為工具
docstring 餵給模型

角色 03

create_agent

langchain 1.x 新接口
底層為 LangGraph CompiledStateGraph

                calculator_agent.py
from langchain.chat_models import ChatOpenAI
from langchain.tools import tool
from langchain.agents import create_agent

@tool
def multiply(a: int, b: int) -> int:
    """兩數相乘 — 模型自己心算必錯的工具"""
    return a * b

llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)
agent = create_agent(llm, tools=[multiply])

def call_math_agent(question: str):
    return agent.invoke({"messages": [("user", question)]})

為何選「乘法」而非「加法」？

大數相乘模型自己心算幾乎必錯——必須老實調用工具才能算對
凸顯 Agent 調用工具的價值——不靠工具就答錯
驗證評估的基礎前提——若 Agent 走對路徑（先調工具）就能算對

本節的對照基準意義

✓

完全沒有任何 LangSmith 相關程式碼

下頁再接上觀測平台時，才能清楚感受到「幾乎沒動業務代碼」這件事

CH.02 · 接入實作 07 / 20

接入 LangSmith：環境變數 + @traceable

接入 LangSmith 只需三件事——生成 API Key、補上四個環境變數、加一行 @traceable 裝飾器。業務邏輯幾乎一行未改。

❌ BEFORE · 純 Agent

# 純 Agent，無任何 LangSmith 程式碼
def call_math_agent(question):
    return agent.invoke({"messages": ...})
                

✓ AFTER · 接入 LangSmith

# 業務入口加一行裝飾器
from langsmith import traceable

@traceable(name="call_math_agent")
def call_math_agent(question):
    return agent.invoke({"messages": ...})
                

01

LANGSMITH_TRACING=true
總開關，關掉就停上報

02

LANGSMITH_API_KEY
身份認證金鑰

03

LANGSMITH_PROJECT
專案命名分組

04

LANGSMITH_ENDPOINT
服務地址

!

國內常見坑：系統代理干擾

系統代理會讓 SDK 上報卡住——解法：把 LangSmith 服務地址加進 no_proxy 環境變數，讓 SDK 直連

✓

零侵入式可觀測性

環境變數負責自動上報底層調用，裝飾器負責立一個清晰的業務頂點——兩者分工明確

CH.02 · 看軌跡 08 / 20

Tracing 與 Run Tree：過程軌跡評估的資料來源

Tracing 把 Agent 每次運行的完整軌跡記錄下來，是回放與除錯的入口——但它本身不打分，要把記錄變成分數得靠下一塊 Datasets & Experiments。

Run Tree 示意

CALL TREE

▸ call_math_agent (@traceable)

├─ ChatOpenAI.invoke gpt-4o-mini

├─ multiply(7, 8) → 56

└─ ChatOpenAI.invoke final answer

每步耗時 · token 消耗 · 輸入輸出參數 · 工具真實結果

三種粒度對照

粒度	顆粒度	適用場景
Threads	按會話線程	追一整段連續對話
Traces	按單次運行	逐次排查某一回執行
Runs	最細顆粒	每個模型 / 工具調用節點

過程軌跡評估「依賴完整執行記錄」——沒有 Tracing，這類評估無從下手

CH.02 · 實作閉環 09 / 20

建題庫 · 跑評估 · 比版本 · 人工校準：四塊實作總覽

本章後半段把 Datasets & Experiments、Comparison、Annotation Queues 三塊全部動手跑過一遍，形成完整的評估操作閉環。

STEP 01

建題庫

Dataset = 題庫
Example = 一道題
Experiment = 成績單
Client · create_dataset · create_examples

→

STEP 02

跑評估

核心 API：evaluate()
四要素：target / data / evaluators / experiment_prefix

→

STEP 03

比版本

改 PROMPT_MODE 重跑兩份
勾選 Compare 並排看升降

→

STEP 04

人工校準

規則裁判 · LLM-as-judge
人工標注金標準對齊

三種裁判的適用邊界

裁判類型	原理	適用場景	成本 / 速度	可信度
規則裁判	exact_match / 正則	有唯一答案的題	零成本 · 毫秒	高（確定性）
LLM-as-judge	大模型當評委	主觀開放性輸出	中成本 · 秒級	中（需校準）
人工標注	人逐條打分	機器裁判金標準	高成本 · 慢	最高

一份 Dataset 可以掛多個評估器——這正是第三章記帳 Agent「一份題庫多維打分」的地基

CH.03 · 真實業務場景 10 / 20

記帳 Agent 架構總覽：14 個工具 + MoE 模型

把整套評估能力從教學用計算器搬到真實業務場景——一個能用自然語言記帳、查帳、改帳、管預算的中文記帳 Agent。

14 個工具 · 六組業務線

業務組	工具名	職責
日期類	`get_current_datetime · resolve_date`	解析「上週三」等相對日期
分類 / 計算	`classify_category · calculate`	消費分類、算術運算
記帳 / 收入	`add_transaction · add_income`	寫入支出 / 收入
查改刪	`query · update · delete`	讀取 / 修改 / 刪除交易
統計 / 餘額	`summarize_expense · get_balance`	月度統計、帳戶餘額
帳戶 / 預算	`set_account · set_budget · check_budget`	帳戶管理、預算設定與提醒

qwen3-coder-flash

MoE · 30.5B 總參數

→

每次激活 3.3B

128 專家中選 8 · 256K context

→

選型理由

基礎夠用但有明顯短板

利於第四章優化示範

CH.03 · 評估工程地基 11 / 20

可複現性三件套：評估工程的地基

把能控制的變量都固定住，讓每次評估都在同樣條件下進行——缺一份，成績單就不能拿來做回歸對比。

01

固定時間

記帳有大量相對日期（「今天」「上週三」）。若用真實系統時間，今天跑和明天跑「上週三」指向不同日期

EVAL_NOW = "2026-06-04T12:00:00"

02

每例重置

每條用例跑前，先把帳本重置成同一份種子資料，保證每條用例面對的初始帳本都一樣，不被上一條污染

db.reset_db(seed=True)

03

串行執行

所有用例共用同一個評估資料庫、每條跑前都要重置——並發跑會同時重置同時寫入導致帳本錯亂

max_concurrency = 1

三件套擋住的是「環境雜訊」（可消除）——「模型隨機性」（無法消除）要靠多次取均值或換評估策略處理

可評估包結構（evaluable payload）

# 每一條用例跑完後產出的五欄位結構
{
    "final_answer":  # Agent 最終回覆
    "tool_calls":    # 工具調用清單
    "db_after":     # 跑完後帳本快照
    "accounts_after":# 帳戶餘額
    "budgets_after": # 預算剩餘
}
            

CH.03 · 題庫設計 12 / 20

資料集設計哲學：一份題庫覆蓋多個評估角度

核心集 20 道題的 CSV 設計，讓一行用例同時被多個評估器讀取——直接落地「一份 Dataset 掛多個評估器」的核心哲學。

CSV 欄位結構 · 11 個欄位

# easy-accounting-core.csv · 核心集 20 題
case_id, user_input,
expected_tool, expected_amount, expected_category,
expected_date, expected_account,
answer_contains, expect_alert, expect_clarify,
case_type
            

一行用例對應多個評估器

欄位	對應評估角度	觸發的評估器
`expected_tool`	工具與動作評估	tool_selection
`expected_amount / category / date / account`	參數抽取準確性	arg_correctness (4 個)
`answer_contains`	依據與狀態一致性	balance_correct / query_grounded
`expect_alert`	副作用控制	budget_alert_triggered
`expect_clarify`	該問則問	should_ask_when_uncertain

✓

種子資料刻意設計「已超支」

交通已超支、購物與總預算接近上限——讓超支提醒類用例有真實的預算壓力可測

Σ

四套題庫 × 20 題 = 80 道評估用例

easy-accounting-core / -multi-turn / -safety / -robustness——分場景驗證不同評估角度

CH.03 · 評估器實作 13 / 20

評估器撰寫規範與核心集 13 個評估指標

評估器統一約定為 (inputs, outputs, reference_outputs) → {key, score, comment}——score=None 代表不適用，LangSmith 自動跳過不拉低分母。

                1. tool_selection
# 工具與動作評估
exp = ref.get("expected_tool")
if not exp:
    return {"score":None}
called = {tc["name"]
          for tc in outputs["tool_calls"]}
hit = bool(called &
    set(exp.split("|")))
return {"key":"tool",
        "score":int(hit)}
              

                2. balance_correct
# 依據與狀態一致性
seed = ref["seed_balance"]
spent = ref["expected_amount"]
actual = outputs["accounts_after"]
         ["cash"]
expected = seed - spent
ok = abs(actual - expected) < 0.01
return {"key":"balance",
        "score":int(ok),
        "comment":f"預期{expected}"}
              

                3. used_date_tool
# 過程軌跡評估
def used_date_tool(_, outputs, _ref):
    names = [tc["name"]
             for tc in outputs["tool_calls"]]
    return {"key":"date_tool",
            "score":int(
              "resolve_date" in names)}
              

序	指標 key	判斷內容	角度 (Chapter 1)
1	`tool`	選對工具（多候選用 \| 分隔）	1.2 工具動作
2-5	`amount / category / date / account`	四個參數抽取正確	1.2 工具動作
6	`balance`	記帳後餘額計算正確	1.4 依據一致性
7	`query_grounded`	查詢資料有真實依據	1.4 依據一致性
8	`date_tool`	有用 resolve_date 工具	1.3 過程軌跡
9	`tool_order`	工具調用順序合理	1.3 過程軌跡
10	`no_redundant`	無冗餘調用	1.3 過程軌跡
11	`budget_alert`	超支時主動提醒	1.6 安全權限
12	`format`	最終回答格式完整	1.1 任務結果
13	`clarify`	資訊不全時反問	1.5 多輪記憶

合併成 evaluate_all 一次呼叫——每條用例只產 1 條記錄，只回報適用指標，不刷屏

CH.03 · 場景擴展 14 / 20

多輪交互 · 安全邊界 · 抗擾穩健：三套題庫

核心集解決「記得清、算得對」，三套擴展題庫解決「聊得久、不越界、扛得住」——通用 7 類角度中 1.5 / 1.6 / 1.7 的具體落地。

M

easy-accounting-multi-turn

覆蓋通用 1.5「多輪交互與狀態保持」——測「剛才那個」「那筆咖啡改成分類午餐」等指代消解

關鍵指標：

coref_resolved · context_retained

S

easy-accounting-safety

覆蓋通用 1.6「規則、安全與權限」——測誤刪確認、餘額不足拒絕、敏感操作攔截

關鍵指標：

confirm_required · reject_overdraw · no_pii_leak

R

easy-accounting-robustness

覆蓋通用 1.7「抗擾穩定性」——測錯別字、別名、語序顛倒、極端數值

關鍵指標：

typo_resilient · alias_handled · extreme_value_safe

通用 7 類不是抽象分類——每類都有對應題庫 + 評估器實作路徑，這就是「一份題庫多維打分」的完整版

CH.03 · 回歸對比 15 / 20

比版本：回歸穩定性評估的標準作業

Comparison 是 LangSmith 把「改一版不知道是好是壞」這件事變得可見的關鍵工具——環境變數切版、跑兩次、勾選並排。

三步回歸對比 SOP

STEP 01

設環境變數

PROMPT_MODE=baseline
跑第一次 → baseline 成績單

→

STEP 02

切到新版

PROMPT_MODE=v2
同一份題庫重跑

→

STEP 03

Compare 並排

勾選兩個 experiment
逐指標看升降，識別退化

✓

健康的回歸：絕對分數 + 指標級升降

不只看整體平均，更要看每個評估指標是否退化——「整體提升但某指標暴跌」要警覺

!

陷阱：模型隨機性會偽裝成回歸

同樣 prompt 重跑兩次成績單可能 ±3 分浮動——上線前必須固定多次均值或顯著性檢驗

「改一版 + 跑一次 + 看一眼」是回歸穩定性評估的最小閉環——也是「修好 A 又悄悄弄壞 B」的唯一解藥

CH.04 · 優化實戰 16 / 20

優化案例一：提示詞重構驅動多輪指代消解

短板識別 → 「那筆咖啡改成午餐分類」測項「答非所問」（以為是新交易）。提示詞新增「代詞解析規則」後通過率從 35% 升至 80%。

❌ BASELINE · 35%

# 原 prompt 缺少代詞指引
你是一個記帳助手。
可用工具: add_transaction,
update_transaction, ...
使用者訊息: {input}
                

失敗樣本：「那筆咖啡改成午餐分類」
→ 誤以為新增「午餐」交易

✓ V2 · 80%

# 加代詞解析 + 更新優先級
你是一個記帳助手。
規則：
1. 若含「那筆/剛才/上次」，
   優先查詢並 update
2. 區分 add vs update
可用工具: ...
使用者訊息: {input}
                

通過樣本：同上
→ 正確定位舊交易 + update

35%

Baseline
多輪指代消解

→

單點提示詞重構

80%

V2
多輪指代消解

+45pp

無需改模型
純規則明確化

CH.04 · 優化實戰 17 / 20

優化案例二：Tool Docstring 改善工具選對率

短板識別 → 「查最近三筆交通」誤用 summarize_expense（聚合工具）。把 docstring 寫清「僅聚合、不列單筆」後選對率從 60% 升至 92%。

❌ BASELINE · 60%

@tool
def summarize_expense(category: str = "all"):
    """統計類別開銷總和"""
    return db.sum_by_category(category)
                

失敗樣本：「最近三筆交通」
→ 選了 summarize 而非 query_transactions

✓ V2 · 92%

@tool
def summarize_expense(category: str = "all"):
    """僅回傳聚合數字（如總和）。
絕不列舉單筆交易——列舉請用 query_transactions。
不要在「最近 N 筆」「明細」場景呼叫本工具。"""
    return db.sum_by_category(category)
                

通過樣本：同上
→ 明確導向 query_transactions

60%

Baseline
工具選對率

→

docstring 寫清否定邊界

92%

V2
工具選對率

+32pp

零 prompt 變動
工具自描述強化

Tool Docstring 是模型對工具的唯一想像空間——寫好「做什麼 / 不做什麼 / 反例場景」是最便宜的選對率提升手段

CH.04 · 優化實戰 18 / 20

優化案例三：模型升級作為最後手段

短板識別 → 「上週三跨月推算」類測項即使 prompt + docstring 都優化，仍有 18% 失敗。升級到旗艦模型後達 96%，但成本上漲 21 倍——這是評估驅動的成本決策。

qwen3-coder-flash

3.3B 激活 · ¥0.0003/1k

→

qwen3-coder-plus

全參數 · ¥0.006/1k

82%

flash
跨月日期推算

96%

plus
跨月日期推算

¥5

單次評估成本
flash

¥105

單次評估成本
plus

⚠

升級前必須確認 prompt 與 docstring 已窮盡優化

模型升級是最貴的解法——先用評估證明「提示詞層已無法再榨出 1pp」，否則是浪費錢

✓

評估驅動的成本決策

「+14pp 是否值得 21× Token 成本」要靠業務場景定奪——若該場景營收敏感，可接受；若只是邊緣場景，回退到 flash + 人工兜底

模型升級是優化最後一張牌——把前兩個槓桿（prompt + docstring）用盡再考慮，否則就是拿錢買懶惰

CH.05 · 總結 19 / 20

總結：把「憑感覺」變成「可複現的成績單」

20 頁走完的完整閉環——五個動詞開頭的核心命題，每一條都是可立即落地的工程準則。

①

建立：通用 7 類 + 業務特殊 N 類 = 完整評估清單

任何 Agent 上線前，先畫評估地圖——再寫第一行程式碼

②

接入：四個環境變數 + 一行 @traceable = 零侵入可觀測

業務程式碼幾乎一行動——把它當作平台化的起點

③

題庫：一份 Dataset 掛多個 Evaluator = 多維度同時打分

CSV 欄位設計決定一切——每個欄位都是一個評估器的入口

④

回歸：固定時間 + 每例重置 + 串行 = 可複現地基

環境雜訊摁不住，評估分數就不能拿來做版本對比

⑤

優化：prompt → docstring → 模型升級，依序升級

評估發現短板 → 最短路徑修法；先窮盡便宜槓桿，再花錢升旗艦

CH.05 · 延伸方向 20 / 20

延伸方向：把這套方法論推到企業級

本課是「記帳 Agent 一個案例」的完整閉環——企業落地要把同一套方法複製到所有業務 Agent，並建立常態化的 Benchmark 與 Eval Suite。

A

Eval Suite 制度化

把所有業務 Agent 統一收口到同一個 LangSmith workspace——題庫分場景命名（如 billing-* / customer-*），評估器跨 Agent 共享

eval-suite · weekly regression

B

Benchmark 外掛

把通用題庫（如 τ-bench、HotpotQA、SWE-bench）拉進自家題庫——既看自家業務分數，也看業界基準排名

open-benchmark · private-dataset

C

Online Eval

把 LangSmith 的 Evaluator 嵌進線上服務——每一次真實調用都打分，離線題庫之外的真實分佈補回

online-judge · drift-detector

評估不是上線前的考試，而是上線後的持續心跳——企業落地要把「評估」做成平台功能，不是一次性的專案交付