📥 Download Jupyter Notebook

Download complete Jupyter Notebook

---

Agent SDK vs 傳統 If-Else：客服系統從 500 行代碼到 10 行的蛻變

📋 快速摘要

• Agent SDK 將 500+ 行 if-else 邏輯簡化為 ~10 行配置
• 維護成本從「高」降到「低」—— 新增規則只需改提示，無需改代碼
• 適用場景：客服回覆、內容審核、工單分類
• 不適用場景：金融交易、爬蟲、醫療診斷（需要 100% 確定性）
• 本文包含可運行的 Jupyter Notebook 對比演示

爲什麽選擇 Agent SDK 而非傳統 If-Else？

想象你在維護一個客服系統。每當新的詢問類型出現，你就得添加 5-10 行 if-elif-else 代碼。6 個月後，代碼變成 500+ 行的怪獸，充滿邊界情況處理。

現在有一個更好的方式：用 Agent SDK 讓 AI 自動理解客戶意圖，不需要每次都改代碼。

實例對比：傳統方式 vs Agent SDK

❌ 傳統方式：500+ 行代碼

典型的 if-else 實現（簡化版本）：

def traditional_customer_service(inquiry: str) -> str:
    if "退貨" in inquiry or "return" in inquiry.lower():
        if "7天" in inquiry or "7 days" in inquiry.lower():
            return "✓ 好消息！7 天內的商品我們接受退貨。請提供訂單號和退貨原因。"
        elif "30天" in inquiry or "30 days" in inquiry.lower():
            return "⚠ 30 天內的商品需要評估狀況。請寄回商品，我們會判斷是否可退。"
        else:
            return "✗ 超過退貨期限（30天），無法退貨。詳見購買頁面。"
    # ... 還有物流、商品、預設回覆，加起來 500+ 行
    else:
        return "感謝您的詢問。請告訴我更多細節，我會盡快幫您解決。"

問題：

• 新增詢問類型 → 需要改代碼 → 需要測試 → 需要重新部署
• 邊界情況處理複雜（用戶說「退貨」的 10 種不同表達方式）
• 代碼量隨詢問類型線性增長
• 維護成本高、Bug 多

✨ Agent SDK 方式：~10 行配置

from claude_agent_sdk import query, ClaudeAgentOptions

async for message in query(
    prompt="You are a customer service agent. Understand customer inquiries and help with returns, invoices, shipping, and product issues.",
    options=ClaudeAgentOptions(
        allowed_tools=["Retrieve Policy", "Query Order", "Update Status"],
        permission_mode="acceptEdits"
    )
):
    if isinstance(message, ResultMessage):
        print(message.result)  # AI-generated response

優勢：

• 新增規則 → 只需改系統提示，無需改代碼
• 自動理解變通說法
• 代碼量固定，不隨規則增加而增加
• 維護成本低、Bug 少

真實測試結果

5 個實際客戶詢問測試：

測試	傳統方式	Agent SDK	勝者
回覆時間	0.03ms	150ms	If-Else (快 5000x)
代碼行數	500+	~10	✨ Agent SDK (簡潔 50x)
新增規則難度	高（改代碼→測試→部署）	低（改提示→即時生效）	✨ Agent SDK
維護成本	高	低	✨ Agent SDK
用戶體驗	生硬、標準化	自然、親切	✨ Agent SDK

何時使用 Agent SDK vs If-Else

✅ 適合 Agent SDK 的場景

• 客服回覆 — 自然理解客戶意圖
• 內容審核 — 判斷垃圾信息、仇恨言論
• 工單分類 — 自動分類優先級
• 推薦系統 — 推薦相關商品
• 數據提取 — 從非結構化文本提取信息

❌ 不適合 Agent SDK 的場景

• 金融交易 — 需要 100% 確定性
• 醫療診斷 — 需要絕對準確
• 法律判決 — 需要精確遵循規則
• 實時系統 — AI 延遲 100-500ms
• Web 爬蟲 — 需要精確控制

Claude API vs Agent SDK：核心差異

這是很多人困惑的地方。讓我用實例說明。

場景：客服回答「我的訂單呢？」

系統需要：

1. 查訂單資料庫
2. 查物流資料庫
3. 組合信息回答客戶

❌ Claude API（你控制流程）

from anthropic import Anthropic

client = Anthropic()

# 第 1 次調用
response1 = client.messages.create(
    model="claude-opus-4-6",
    messages=[{
        "role": "user",
        "content": "客戶說：我 3 月 10 號買的商品，現在還沒收到"
    }]
)
# Claude：「我需要查一下你的訂單...」

# ❌ 你必須手動查資料庫
order = query_order_db(customer_id, "2026-03-10")

# ❌ 第 2 次調用 Claude
response2 = client.messages.create(
    model="claude-opus-4-6",
    messages=[{
        "role": "user",
        "content": f"""訂單信息：{order}

請回答客戶。"""
    }]
)

# ❌ 如果客戶追問，又要第 3、4 次調用...

你的應用程式在做決策：

• 「我應該先查訂單」
• 「我應該問 Claude 什麼問題」
• 「我應該再查一次物流」

✅ Agent SDK（Claude 自動控制流程）

from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

# 就一次調用，Claude 自動做一切
async for message in query(
    prompt="""你是客服系統。根據客戶問題，查詢訂單和物流信息，給出完整回答。

客戶問題：「我 3 月 10 號買的商品，現在還沒收到，怎麼辦？」

工具說明：
- query_order(customer_id, date)：查訂單
- query_shipping(tracking_id)：查物流

請自動使用這些工具，給出完整回答。""",

    options=ClaudeAgentOptions(
        allowed_tools=["query_order", "query_shipping"]
    )
):
    if isinstance(message, ResultMessage):
        print(message.result)
        # 完成！Claude 自動完成了一切

Claude 自動做決策：

• ✅ Claude 看到問題
• ✅ Claude 決定「我需要查訂單」
• ✅ Claude 自動調用工具
• ✅ Claude 看結果，決定「我還需要查物流」
• ✅ Claude 自動調用工具
• ✅ Claude 綜合所有信息，給出回答

一句話總結

Claude API	我知道要查 DB 的順序 → 我來組織
Agent SDK	我把查 DB 的工具做好 → Claude 自己組織順序

Agent SDK vs Claude API 完整對比

特性	Claude API	Agent SDK
使用場景	一次性請求、內容生成	決策型任務、自動化工作流
流程控制	你的應用程式控制	Claude 自動決策
工具調用	手動查 DB，手動傳給 Claude	Claude 自動調用工具和解析
複雜度	簡單 – 一個請求，一個回應	複雜 – 多步驟推理、工具調用
代碼量	多（需要寫 loop 邏輯）	少（一句話啟動）
安全性	你負責驗證輸出	內置權限管理、審計日誌

決策樹：選擇正確的工具

你的任務來了
    ↓
「這個任務需要 AI 自己決策嗎？」
    ├─ YES → 「結果容錯為零嗎？」
    │         ├─ YES → ❌ 不用 AI，用硬編碼邏輯
    │         └─ NO  → ✅ 用 Agent SDK
    │
    └─ NO  → 「只是單純生成內容/回答嗎？」
              ├─ YES → ✅ 用 Claude API
              └─ NO  → 「需要多步驟工作流嗎？」
                        ├─ YES → 你控制流程 + Claude API
                        └─ NO  → ✅ Claude API 就夠了

真實案例：電商商品自動分類系統

背景： 某線上購物平台（如東森）需要自動將客戶上傳的商品歸類到正確的分類。

情況說明

規模： 4 萬個商品分類（電子產品、服裝、家居、運動等）

挑戰： 如何在成本可控的情況下，快速準確地進行分類？

方案 1：傳統 TFIDF 模型

實現方式：

1. 收集所有商品描述 + 人工標註的分類
2. 用 TFIDF 算法訓練模型，提取關鍵詞權重
3. 客戶輸入新商品描述 → 模型計算與各分類的相似度 → 返回排名前 3 的分類

# 傳統 TFIDF 方法
from sklearn.feature_extraction.text import TfidfVectorizer
from sklearn.neighbors import NearestNeighbors

# 1. 訓練
vectorizer = TfidfVectorizer()
tfidf_matrix = vectorizer.fit_transform(product_descriptions)
model = NearestNeighbors(n_neighbors=3, metric='cosine')
model.fit(tfidf_matrix)

# 2. 預測
new_product = "輕便防水的戶外登山背包，容量 40L"
new_tfidf = vectorizer.transform([new_product])
distances, indices = model.kneighbors(new_tfidf)

# 結果：前 3 個分類
# [運動戶外, 旅遊用品, 箱包配飾]

優勢：

• ⚡ 毫秒級回應（無網路延遲）
• 💰 零成本（本地運行）
• 🎯 可控、可解釋（看得到關鍵詞權重）

缺點：

• ❌ 無法理解語義（「便宜的手機」vs「經濟型手機」被當作完全不同的商品）
• ❌ 變通說法識別差（「登山背包」識別不了，但「戶外登山用雙肩包」就被歸錯類）
• ❌ 每次添加新分類或修改規則都需要重新訓練
• ❌ 無法跨語言（中文和英文分開訓練）
• ❌ 無法處理複雜邏輯（「防水的同時是否防塵？」這類二次判斷）

方案 2：單純 AI 分類（Claude API）

天真的做法：把 4 萬個分類都給 Claude

from anthropic import Anthropic

client = Anthropic()

response = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    messages=[{
        "role": "user",
        "content": f"""根據這個商品描述進行分類：

商品描述：輕便防水的戶外登山背包，容量 40L

可用分類：
- 電子產品
- 服裝鞋履
... (共 4 萬個)

返回最相關的前 3 個分類 + 置信度。"""
    }]
)

問題： 4 萬個分類 × 10 tokens/分類 = 40 萬 tokens 光是分類列表

• 成本：$5 / 次（按 Claude Opus 定價）
• 日成本（10,000 商品）：$50,000 / 天 = **$1.5M / 月** ❌
• 完全不可行

方案 3：向量搜尋 + AI 精確分類（最優）

核心思想： 不是把 4 萬個分類都給 Claude，而是：

1. 預先計算： 將 4 萬個分類嵌入向量空間（一次性，離線）
2. 實時檢索： 商品描述進來 → 向量相似度搜尋 → 找出最相關的 Top 50 分類
3. 精確分類： 只把 50 個候選分類傳給 Claude
4. 結果： 成本 = 原本的 1/800，準確度反而更高

# 向量檢索 + AI 分類架構

from sentence_transformers import SentenceTransformer
from milvus import connections, Collection
from anthropic import Anthropic

client = Anthropic()

# ============ 階段 1：預先計算分類向量（一次性） ============
def initialize_category_embeddings():
    """將 4 萬個分類嵌入向量空間"""
    connections.connect("default", host="127.0.0.1", port="19530")
    collection = Collection("products_categories")

    # 從資料庫讀取所有分類
    categories = get_all_categories_from_db()

    # 計算向量（使用本地模型）
    model = SentenceTransformer('all-MiniLM-L6-v2')
    embeddings = model.encode([cat['name'] for cat in categories])

    # 插入向量資料庫
    collection.insert({
        "id": [cat['id'] for cat in categories],
        "category_name": [cat['name'] for cat in categories],
        "embedding": embeddings
    })
    collection.load()
    print("✅ 4 萬個分類向量化完成！")

# ============ 階段 2：實時檢索 + AI 分類 ============
def classify_product_optimized(product_description):
    """實時分類流程"""

    # 1. 將商品描述向量化
    model = SentenceTransformer('all-MiniLM-L6-v2')
    query_embedding = model.encode(product_description)

    # 2. 向量搜尋：找出最相關的 Top 50 分類（< 50ms）
    connections.connect("default", host="127.0.0.1", port="19530")
    collection = Collection("products_categories")

    search_results = collection.search(
        data=[query_embedding],
        anns_field="embedding",
        param={"metric_type": "L2", "params": {"nprobe": 10}},
        limit=50  # 只取 Top 50
    )

    top_categories = [hit.entity.get("category_name") for hit in search_results[0]]
    categories_text = '\n'.join([f"- {cat}" for cat in top_categories])

    print(f"✓ 向量搜尋找到 50 個候選分類（用時：< 50ms）")

    # 3. Claude 從 50 個候選中精確選擇（150ms）
    response = client.messages.create(
        model="claude-opus-4-6",
        max_tokens=1024,
        messages=[{
            "role": "user",
            "content": f"""根據這個商品描述進行分類：

商品描述：{product_description}

相關分類候選（已按相似度排序，僅展示 Top 50）：
{categories_text}

請從上述候選中選擇最相關的前 3 個分類 + 置信度。

返回格式：
1. 分類名稱 (置信度: 95%)
2. 分類名稱 (置信度: 80%)
3. 分類名稱 (置信度: 65%)

同時說明理由。"""
        }]
    )

    return response.content[0].text

性能對比：

指標	TFIDF	純 AI （全部分類）	向量 + AI （推薦）
分類傳輸	不適用	40 萬 tokens	500 tokens（50 個）
成本/次	$0	$5.00	$0.005
日成本（10K 商品）	$0	$50,000	$50
響應時間	1ms	1-2 秒	200ms
準確度	中	中（容易混淆）	⭐⭐⭐ 高
語義理解	❌ 差	✅ 強	✅ 強
多語言支持	❌ 差	✅ 強	✅ 強

如何讓 Agent SDK / Claude 存取動態分類列表？

問題： 上面的案例中，分類是硬編碼或簡單傳輸。但在真實系統中，分類會經常變動。Agent SDK 怎麼知道最新的分類清單？

三種方案對應不同規模

方案 A：應用層查詢（適合 < 500 分類）

流程： 應用程式 → 查詢資料庫 → 替換提示詞佔位符 → Agent 使用

import sqlite3
from anthropic import Anthropic

client = Anthropic()

# 應用程式層：查詢資料庫
def get_categories_from_db():
    conn = sqlite3.connect('products.db')
    cursor = conn.cursor()
    cursor.execute('SELECT name FROM categories WHERE active = 1 ORDER BY name')
    categories = [row[0] for row in cursor.fetchall()]
    conn.close()
    return categories

# 獲取最新分類
categories = get_categories_from_db()
categories_text = '\n'.join([f"- {cat}" for cat in categories])

# 生成提示詞
prompt = f"""根據商品描述選擇分類：

商品描述：輕便防水的戶外登山背包，容量 40L

可用分類：
{categories_text}

返回前 3 個分類。"""

# Claude 使用最新分類進行分類
response = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": prompt}]
)

優勢： 簡單、直接、零複雜度

缺點： 每次請求都要查資料庫

方案 B：Agent 工具查詢（適合 500-5000 分類）

流程： Agent 調用自訂工具 → 工具查詢資料庫 → Agent 使用結果

from anthropic import tool
import sqlite3

@tool
def query_categories(keyword: str = None) -> str:
    """查詢可用的商品分類。

    Args:
        keyword: 可選的搜尋關鍵詞（例如：'電子' 會返回 '電子產品'）
    """
    conn = sqlite3.connect('products.db')
    cursor = conn.cursor()

    if keyword:
        cursor.execute(
            'SELECT name FROM categories WHERE active = 1 AND name LIKE ? ORDER BY name',
            (f'%{keyword}%',)
        )
    else:
        cursor.execute('SELECT name FROM categories WHERE active = 1 ORDER BY name')

    categories = [row[0] for row in cursor.fetchall()]
    conn.close()
    return ', '.join(categories)

# Agent 可以調用工具
prompt = """根據商品描述選擇分類：

商品描述：輕便防水的戶外登山背包，容量 40L

步驟：
1. 使用 query_categories 工具查詢所有或相關分類
2. 從結果中選擇最相關的前 3 個

返回格式：
1. 分類名稱 (置信度: 95%)
...
"""

優勢： 動態、Agent 可以「思考」查詢策略

缺點： 增加 API 往返次數

方案 C：向量檢索（適合 > 5000 分類，如東森 4 萬）

流程： 預先嵌入分類 → 商品描述進來 → 向量搜尋 Top 50 → Claude 精確選擇

（詳見上方「向量搜尋 + AI 精確分類」段落）

方案選擇表

分類規模	推薦方案	成本	延遲	複雜度
< 100	方案 A（直接傳）	最低	最快	⭐ 最簡
100-500	方案 A（推薦）	低	快	⭐ 簡
500-5000	方案 B（推薦）	中	中	⭐⭐ 中
> 5000（東森 4 萬）	方案 C（必須）	最低	最快	⭐⭐⭐ 複

工具設計的正確思路：從問題出發

這是最重要的一個章節。 很多工程師設計 Agent 工具時，會陷入「工具先行」的誤區。但正確的做法是「需求驅動」。

❌ 錯誤的做法：工具先行

「我要做 Agent SDK」
  ↓
「我需要什麼工具？」
  ↓
設計工具：query(), update(), delete()
  ↓
「我怎麼用這些工具？」
  ↓
慢慢找場景...
  ↓
結果：工具太通用、有遺漏、或過度設計

✅ 正確的做法：從問題出發

「我的系統可能遇到什麼問題？」
  ↓
列舉所有可能的問題
  ↓
反推需要什麼工具來解決
  ↓
設計這些工具（不多不少）
  ↓
套入 Agent SDK
  ↓
結果：工具精準、完整、適中

實例 1：東森商品分類系統

第 1 步：列舉可能的問題

系統運行時會遇到什麼問題？

用戶層面：
  ✓ 「我怎麼知道這個商品該放哪一類？」
  ✓ 「系統選的分類對嗎？」
  ✓ 「能不能推薦其他可能的分類？」

系統層面：
  ✓ 「分類資料庫有沒有更新？」
  ✓ 「分類規則有沒有衝突？」
  ✓ 「某個分類底下有沒有商品？」

邊界問題：
  ✓ 「這個商品可能屬於多個分類嗎？」
  ✓ 「怎麼處理新加的分類？」
  ✓ 「怎麼回滾到之前的分類？」

第 2 步：反推需要的工具

問題                                 → 需要的工具
──────────────────────────────────────────────────
「能推薦其他可能的分類？」            → search_similar_categories()
「分類有沒有更新？」                  → get_latest_categories()
「分類規則有沒有衝突？」              → validate_category_rules()
「某分類有沒有商品？」                → count_products_in_category()
「可能屬於多個分類嗎？」              → get_ambiguous_categories()

第 3 步：只設計這些工具

@tool
def search_similar_categories(keyword: str, top_k: int = 5) -> list:
    """找相關分類"""

@tool
def get_latest_categories(updated_after: str = None) -> list:
    """取最新分類資料"""

@tool
def validate_category_rules(category_id: str) -> dict:
    """驗證分類規則有沒有問題"""

@tool
def count_products_in_category(category_id: str) -> int:
    """某分類有多少商品"""

@tool
def get_ambiguous_categories(product_desc: str) -> list:
    """找可能有歧義的分類"""

就這 5 個工具，不多不少！

實例 2：客服系統

列舉問題 → 推斷工具

問題列表：
1. 「客戶的訂單存在嗎？」
2. 「訂單現在在哪裡？」
3. 「這個客戶有沒有退貨紀錄？」
4. 「退貨政策允許嗎？」
5. 「要問主管才能退嗎？」
6. 「怎麼記錄這次交互？」

需要的工具：
1. query_order()
2. get_shipping_status()
3. get_customer_return_history()
4. check_return_policy()
5. escalate_to_manager()
6. log_interaction()

就這 6 個，不多不少！

為什麼這樣設計好？

優勢	解釋
✅ 不會過度設計	只有解決實際問題的工具
✅ 不會有遺漏	所有可能的問題都考慮到
✅ Claude 理解清楚	系統邊界明確，工具語義清晰
✅ 工具粒度適中	既不太大也不太小
✅ 易於維護和擴展	添加新問題 = 添加新工具

設計 Agent 工具時的關鍵決策：工具粒度

基於「從問題出發」的思路，現在我們討論工具粒度。 粒度（granularity）決定了 Claude 能否有效使用工具。

三種極端情況

❌ 工具太大（做太多事）

@tool
def query_order_everything(
    customer_id: str,
    order_id: str = None,
    status: str = None,
    start_date: str = None,
    end_date: str = None,
    shipping_status: str = None,
    include_items: bool = True,
    include_history: bool = True
) -> dict:
    """一個工具做所有事"""
    # 6 個 WHERE 條件
    # ...

問題：

• Claude 很容易參數填錯（太多選擇）
• Claude 不知道應該用哪些參數組合
• 你寫了 6 個 WHERE，Claude 可能只需要 1 個，浪費

❌ 工具太小（太細碎）

@tool
def query_by_customer_id(customer_id: str) -> list:
    """只查客戶"""

@tool
def query_by_status(status: str) -> list:
    """只查狀態"""

@tool
def query_by_date_range(start: str, end: str) -> list:
    """只查日期"""

# ... 還有 10 個工具

問題：

• Claude 要調用 3-4 次工具才能完成一個查詢
• 延遲高、成本高
• Claude 要自己 join 結果，容易出錯

✅ 工具適中（語義相關的組合）

@tool
def get_customer_order_status(customer_id: str, order_id: str = None) -> dict:
    """查客戶的訂單，可選篩選特定訂單"""
    # WHERE customer_id = ? AND (order_id = ? if provided)

@tool
def get_orders_by_date(start_date: str, end_date: str) -> list:
    """查某個時間範圍的訂單"""
    # WHERE created_at BETWEEN ? AND ?

@tool
def get_orders_by_status(statuses: list) -> list:
    """查特定狀態的訂單"""
    # WHERE status IN (...)

優勢：

• 每個工具有單一職責（符合 SOLID 原則）
• Claude 能清楚理解用途
• 通常 1-2 次調用完成查詢
• 參數數量合理（不超過 3-4 個）

工具粒度判斷清單

設計工具時，問自己這些問題：

判斷點	好的工具	差的工具
工具名能清楚表達意圖嗎？	get_orders_by_customer()	query_db()
參數數量	< 4 個	> 5 個
Claude 能猜到用途嗎？	「我看到名字就知道查什麼」	「我完全不知道這是什麼」
通常多少次調用完成任務？	1-2 次	3-5 次或更多
工具代表一個業務概念嗎？	「訂單狀態」「物流追蹤」	「數據庫查詢」「參數組合」

實際案例：東森分類系統

❌ 太大的工具

@tool
def search_categories(
    keyword: str = None,
    parent_category: str = None,
    min_products: int = None,
    max_products: int = None,
    active_only: bool = True,
    sort_by: str = "name"
):
    """搜尋分類"""
    # 這是什麼？搜分類還是搜商品？太模糊

✅ 適中的工具（基於問題驅動）

@tool
def search_categories_by_keyword(keyword: str) -> list:
    """用關鍵詞搜分類

    例：keyword="運動" → 返回 [運動戶外, 運動服飾, ...]
    """

@tool
def get_category_children(parent_id: str) -> list:
    """取某分類的子分類"""

@tool
def get_products_in_category(category_id: str, limit: int = 100) -> list:
    """取分類下的商品"""

Claude 使用：

「我要分類一個『防水戶外背包』的商品」
↓
Claude：「我先搜 '戶外' 相關分類」
  → search_categories_by_keyword("戶外")
  → 返回 [運動戶外, 戶外用品, ...]

Claude：「運動戶外 有什麼子類別？」
  → get_category_children("運動戶外")
  → 返回 [登山, 露營, 滑雪, ...]

Claude：「登山 分類有什麼產品，我看看背包在哪」
  → get_products_in_category("登山")
  → 自動判斷這個背包應該是「運動戶外 > 登山」

Claude 自動組織，不需要你預先決定順序！

工具粒度的黃金法則

問自己：「Claude 看著這個工具名和參數，會不會用？」

• 如果會 → 工具大小合適
• 如果不會 → 工具太大或太模糊，要拆或改名

總結：何時遷移到 Agent SDK

如果你符合以下任何一個，考慮 Agent SDK：

• 代碼包含 200+ 行 if-elif-else 邏輯
• 每月都在添加新的處理規則
• 用戶經常報告「系統沒理解我」
• 客服系統無法適應變通表達方式
• 維護成本不斷上升

核心優勢總結：

• 代碼行數：500+ → 10（50 倍簡化）
• 新增規則：改代碼+測試+部署 → 改提示（即時生效）
• 用戶體驗：生硬規則化 → 自然親切
• 維護成本：高 → 低

工具設計思路：

• ❌ 不要：先設計工具，再找用處
• ✅ 要：從問題出發，反推需要的工具
• ✅ 結果：工具精準、完整、易用

準備好了嗎？下載 Jupyter Notebook，親手測試，然後在你的項目中試用 Agent SDK。